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

news2025/6/2 4:06:10

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

一、变量类型概述

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

Global Variables（全局变量） - 项目配置文件定义，全局可用
Gateway Variables（网关注释变量） - 特定网关注释配置，覆盖全局
Blueprint Variables（蓝图变量） - 模型蓝图定义，模型内优先
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. 访问方法

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

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

五、局部变量（Local Variables）

1. 定义与配置

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

基本语法要求：

MODEL语句必须以分号结束
所有@DEF操作必须在MODEL语句之后、SQL查询之前
每个@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;