SQL Macros 不是 PL/SQL 函数的替代品，而是编译期内联 SQL 片段的机制；它仅支持 VARCHAR2/CLOB 返回类型、纯表达式拼接、无运行时逻辑，适用于重复性纯计算 SQL 表达式抽象，不可用于复杂业务逻辑或数据库访问。
SQL Macros 在 Oracle 19c 中不是 PL/SQL 标量函数的“替代品”，而是完全不同语义的机制：它在编译期展开为内联 SQL 片段，不执行、不存储状态、不参与 PL/SQL 执行引擎。直接用 SQL_MACRO(SCALAR) 去“替换”一个已有 calculate_tax 这类 PL/SQL 函数，大概率会失败或产生意料外结果。
SQL_MACRO(SCALAR) 不能复用 PL/SQL 函数逻辑
PL/SQL 标量函数（如 calculate_tax）依赖运行时上下文：可调用 DBMS_OUTPUT、查询表、抛异常、使用游标、读取会话变量等。而 SQL_MACRO(SCALAR) 只能返回一个纯表达式（RETURN VARCHAR2 或 RETURN CLOB），且该表达式必须能在 SQL 解析器中静态验证——例如 salary * 0.15 可以，但 SELECT tax_rate FROM config WHERE ... 不行。
- 你无法在 macro 里写
IF语句块，只能用 SQL 的CASE或DECODE - 所有参数必须是 SQL 数据类型（
NUMBER,VARCHAR2），不能是RECORD、REF CURSOR等 PL/SQL 专有类型 - macro 定义中不能包含 DML、DDL、事务控制或任何副作用操作
什么时候该用 SQL_MACRO(SCALAR) 而不是 PL/SQL 函数
适用场景非常具体：当你有一组重复出现、结构固定、纯计算型的 SQL 表达式，想避免硬编码又不想承担函数调用开销时。典型例子是统一的日期格式化、条件字段拼接、权限过滤谓词生成。
- 比如把
TO_CHAR(hire_date, 'YYYY-MM')封装成 macro，让不同查询复用同一格式逻辑 - 又如生成动态列别名：
col_name || '_cleaned'，用于多个视图定义 - 再如构建安全谓词：
'department_id IN (SELECT dept_id FROM user_depts WHERE user_id = SYS_CONTEXT(''USERENV'', ''SESSION_USER''))'，供多处WITH SECURITY POLICY引用
注意：这些都必须是字符串拼接出来的合法 SQL 片段，最终由优化器内联、重写、下推——不是“执行”一段逻辑。
迁移前必须检查的三个硬限制
Oracle 19c 对 SQL_MACRO 有明确语法和语义边界，踩中任意一条就无法创建或报错：
-
RETURN类型只能是VARCHAR2或CLOB，不能是NUMBER、DATE等；返回值必须是可解析的 SQL 表达式文本，不能带分号或 PL/SQL 关键字 - macro 内部不能引用任何 PL/SQL 变量、包变量、会话级绑定变量（如
:bind_var）；所有输入必须显式声明为 macro 参数 - 不能嵌套调用另一个
SQL_MACRO；也不能在 macro 定义中调用 PL/SQL 函数（哪怕那个函数本身是DETERMINISTIC）
例如，下面这段看似合理，但会报 PLS-00711: SQL macro cannot reference PL/SQL function：
CREATE OR REPLACE FUNCTION f_month_str(p_date DATE)
RETURN VARCHAR2 SQL_MACRO(SCALAR) AS
BEGIN
RETURN 'TO_CHAR(' || p_date || ', ''YYYY-MM'')'; -- ❌ 错误：p_date 是 DATE 类型，不能直接拼进字符串
END;
/真正可行的 scalar macro 示例
以下是一个能通过编译、被 SQL 正确消费的最小可用 macro：
CREATE OR REPLACE FUNCTION format_dept_name(p_dept_id NUMBER, p_suffix VARCHAR2 DEFAULT '_DEPT')
RETURN VARCHAR2 SQL_MACRO(SCALAR) AS
BEGIN
RETURN q'[CASE WHEN ]' || p_dept_id || q'[ = 10 THEN ''ACCOUNTING'' || ]' || p_suffix ||
q'[ WHEN ]' || p_dept_id || q'[ = 20 THEN ''RESEARCH'' || ]' || p_suffix ||
q'[ ELSE ''OTHER'' END]';
END;
/调用方式：
SELECT employee_id, format_dept_name(department_id, '_TEAM') dept_label FROM employees;
关键点：所有逻辑都转成了字符串拼接出的 CASE 表达式，没有运行时分支，不查表，不调函数，不依赖会话状态。
复杂业务规则、需要访问数据库对象或做决策链的场景，仍应保留 PL/SQL 函数；SQL Macro 的价值在于消除 SQL 层的重复表达式，而不是取代过程逻辑。最容易被忽略的是：macro 的参数类型和值在定义时就被固化进生成的 SQL 文本，它不感知数据分布、不参与统计信息推导，过度使用可能干扰优化器选择执行计划。
