SQLMesh 用户定义变量详解：从全局到局部的全方位配置指南

SQLMesh 提供了灵活的多层级变量系统，支持从全局配置到模型局部作用域的变量定义。本文将详细介绍 SQLMesh 的四类用户定义变量（global、gateway、blueprint 和 local）以及宏函数的使用方法。

一、变量类型概述

SQLMesh 支持四种用户定义变量，按照作用域从广到窄排列：

1. Global Variables（全局变量） - 项目配置文件定义，全局可用
2. Gateway Variables（网关注释变量） - 特定网关注释配置，覆盖全局
3. Blueprint Variables（蓝图变量） - 模型蓝图定义，模型内优先
4. Local Variables（局部变量） - 模型内部定义，覆盖所有上级变量

当同名变量在不同层级定义时，遵循"就近原则"，即局部变量优先级最高，其次是蓝图变量、网关注释变量，最后是全局变量。

二、全局变量（Global Variables）

1. 定义与配置

全局变量在项目配置文件的 variables 键下定义，支持以下数据类型及其容器：

• 基本类型：int、float、bool、str
• 容器类型：包含上述类型的列表(list)或字典(dict)

YAML配置示例：

variables:
  int_var: 1
  float_var: 2.0
  bool_var: true
  str_var: "cat"
  list_var: [1, 2, 3]
  dict_var:
    key1: 1
    key2: 2

2. 访问方法

在模型定义中，可以通过两种语法访问全局变量：

1) 直接引用宏语法（区分大小写）

SELECT *
FROM table
WHERE int_variable = @INT_VAR  -- 注意：名称必须大写

2) 通过@VAR()宏函数（推荐，支持默认值）

-- 基本用法
SELECT *
FROM table
WHERE int_variable = @VAR('int_var')

-- 带默认值（变量未定义时使用）
SELECT *
FROM table
WHERE some_value = @VAR('missing_var', 0)  -- 渲染为 WHERE some_value = 0

Python模型中可通过context.var()方法访问：

# Python模型示例
context.var('int_var')  # 返回1
context.var('missing_var', 0)  # 返回默认值0

三、网关注释变量（Gateway Variables）

1. 定义与配置

网关注释变量在项目配置文件的特定网关下的variables键中定义：

YAML配置示例：

gateways:
  my_gateway:
    variables:
      int_var: 1  # 覆盖同名的全局变量

2. 特点

• 同名变量优先级高于全局变量
• 其他访问方式与全局变量相同（@VAR()或直接宏语法）

四、蓝图变量（Blueprint Variables）

1. 定义与用途

蓝图变量用于创建模型模板，定义在MODEL语句的blueprints块中：

配置示例：

MODEL (
  name @customer.some_table,
  kind FULL,
  blueprints (
    (customer := customer1, field_a := x, field_b := y),
    (customer := customer2, field_a := z, field_b := w)
  )
);

-- 使用蓝图变量
SELECT
  @field_a,                     -- 解析为x或z
  @{field_b} AS field_b         -- 解析为y或w
FROM @customer.some_source      -- 解析为customer1.some_source或customer2.some_source

2. 访问方法

1. 直接通过@VAR_NAME引用
2. 通过@BLUEPRINT_VAR()宏函数（支持默认值）：

SELECT @{BLUEPRINT_VAR('field_a', 'default_value')} AS safe_field_a

五、局部变量（Local Variables）

1. 定义与配置

局部变量在模型内部使用@DEF操作符定义，具有最高优先级：

基本语法要求：

1. MODEL语句必须以分号结束
2. 所有@DEF操作必须在MODEL语句之后、SQL查询之前
3. 每个@DEF操作必须以分号结束

示例：

MODEL (
  name sqlmesh_example.full_model,
  kind FULL,
  cron '@daily',
  audits (assert_positive_order_ids),
);  -- 注意：MODEL语句以分号结束

@DEF(size, 1);  -- 定义局部变量size，值为1

SELECT
  item_id,
  count(distinct id) AS num_orders,
FROM
  sqlmesh_example.incremental_model
WHERE
  item_size > @size  -- 使用局部变量
GROUP BY item_id

2. 高级用法

1) 多变量定义：

@DEF(var1, 'value1');
@DEF(var2, 123);

2) 动态计算：

@DEF(threshold, 100 * 1.1);  -- 定义变量时进行计算

六、宏函数（Macro Functions）

SQLMesh不仅支持简单变量替换，还支持内联宏函数，提供更强大的逻辑处理能力。

1. 基本语法

单参数函数：

@DEF(
  rank_to_int,
  x -> case when left(x, 1) = 'A' then 1 
            when left(x, 1) = 'B' then 2 
            when left(x, 1) = 'C' then 3 
       end
);

SELECT
  id,
  @rank_to_int(cust_rank_1) as cust_rank_1_int,
  @rank_to_int(cust_rank_2) as cust_rank_2_int
FROM some.model

多参数函数：

@DEF(pythag, (x, y) -> sqrt(pow(x, 2) + pow(y, 2)));

SELECT
  sideA,
  sideB,
  @pythag(sideA, sideB) AS sideC
FROM some.triangle

2. 标准数学函数

SQLMesh内置常用数学函数，可在宏函数中使用：

• 算术函数：+, -, *, /, pow(), sqrt()
• 三角函数：sin(), cos(), tan()
• 常量：pi()

实例：计算圆周长和容器体积

-- 定义半径计算函数
@DEF(area, r -> pi() * r * r);

-- 定义容器体积函数（嵌套函数）
@DEF(container_volume, (r, h) -> @area(r) * h);

SELECT container_id, 
       @container_volume(cont_di / 2, cont_hi) AS volume
FROM containers;

七、最佳实践

1. 命名规范：
   • 全局变量建议全大写（传统约定，虽非强制）
   • 局部变量使用有意义的名称，避免与变量冲突
   • 宏函数名称采用小写下划线风格
2. 错误处理：
   • 为关键变量设置合理的默认值
   • 在复杂计算中添加注释说明逻辑
3. 性能考虑：
   • 避免在宏函数中进行复杂计算
   • 复杂逻辑可考虑使用Python模型实现
4. 安全性：
   • 用户定义的变量最终会转换为SQL参数，但应仍注意SQL注入风险
   • 对用户输入进行适当的验证和清理

八、总结

SQLMesh的变量系统提供了从全局到局部的完整作用域控制，使数据管道配置更加灵活。通过合理使用这四类变量和宏函数，开发者可以：

1. 减少硬编码，提高配置的可维护性
2. 实现参数化的模型模板
3. 创建动态计算的派生指标
4. 提高代码的可重用性和一致性

理解变量优先级和访问方法，掌握宏函数的编写技巧，将显著提升SQLMesh项目的工作效率和可靠性。