SQLMesh 系列教程：解锁SQLMesh的宏与变量魔法

在数据库流水线开发中，代码复用与动态配置是提升效率的核心诉求。SQLMesh以其独特的宏系统与用户定义变量机制，重新定义了SQL生成的灵活性。与传统模板引擎不同，SQLMesh的宏并非简单的字符串替换，而是基于语义理解的智能代码重构——通过sqlglot库解析SQL结构，结合Python逻辑处理能力，让用户能够以声明式语法实现复杂查询的动态组装。

引言

无论是全局配置、网关级参数还是模型内局部变量，SQLMesh的三层变量体系（Global > Gateway > Local）提供了细粒度的数据管控能力。通过@DEF宏定义和@VAR()函数调用，开发者可以轻松将业务规则、环境参数与SQL逻辑解耦，实现“一次编写，多环境适配”。而宏函数的引入更进一步，允许将条件判断、数学计算等逻辑封装为可复用的代码片段，彻底告别重复代码。例如，通过嵌套宏函数@container_volume调用@area，SQLMesh不仅生成最终SQL，更赋予代码可读性与可维护性。

宏系统：两种方法

SQLMesh 中的宏与像 Jinja 这样的模板系统的宏表现不同。
宏系统基于字符串替换。宏系统会扫描代码文件，识别表示宏内容的特殊字符，并将宏元素替换为其他文本。
从广义上讲，这就是模板系统的全部功能。它们具有提供控制流逻辑（if-then）和其他功能的工具，但这些功能仅用于支持替换正确的字符串。

模板系统有意对所使用的编程语言保持中立，大多数模板系统适用于从博客文章到 HTML 再到 SQL 的各种内容。相比之下，SQLMesh 宏专门设计用于生成 SQL 代码。它们通过使用 Python 的 sqlglot 库对正在创建的 SQL 代码进行分析，从而具有对 SQL 代码的语义理解，并且允许使用 Python 代码，这样用户就可以整洁地实现复杂的宏逻辑。

SQLMesh 宏方法

本节描述SQLMesh宏在底层是如何工作的。你可以随意跳过这一节，并在有用的时候返回。使用SQLMesh宏不需要此信息，但它对于调试任何表现出令人困惑行为的宏非常有用。

SQLMesh宏方法和模板系统之间的关键区别在于字符串替换所起的作用。在模板系统中，字符串替换是全部和唯一的要点。

在SQLMesh中，字符串替换只是修改SQL查询的语义表示的一个步骤。SQLMesh宏通过构建和修改SQL查询的语义表示来工作。

在处理完所有非sql文本之后，它使用替换的值将查询的语义表示修改为其最终状态。

它采用以下五个步骤来实现这一目标：

1. 使用适当的 SQLGlot SQL 语境（例如，Postgres、BigQuery 等）解析文本。在解析过程中，它检测特殊宏符号 @ 以区分非 SQL 和 SQL 文本。解析器构建 SQL 代码结构的语义表示，将非 SQL 文本捕获为“占位符”值，以便在后续步骤中使用。

2. 检查占位符值，将其分类为以下类型之一：

   • 使用 @DEF 操作符创建用户自定义宏变量（有关用户自定义宏变量的更多信息请参阅后面章节）

   • 宏变量：SQLMesh 预定义的、用户自定义的局部变量以及用户自定义的全局变量

   • 宏函数，包括 SQLMesh 提供的以及用户自定义的

3. 替换检测到的宏变量值。在大多数情况下，这是与模板系统一样的直接字符串替换。

4. 执行任何宏函数并替换返回值。

5. 用(3)中替换的变量值和(4)中的函数修改SQL查询的语义表示。

用户定义的变量

SQLMesh支持三种用户定义的宏变量：global、gateway和local。

全局和网关宏变量在项目配置文件中定义，可以在任何项目模型中访问。局部宏变量在模型定义中定义，并且只能在该模型中访问。

可以在任何或所有全局、网关和本地级别指定具有相同名称的宏变量。当在多个级别上指定变量时，最特定级别的值优先。例如，局部变量的值优先于同名网关变量的值，网关变量的值优先于全局变量的值。

全局变量

全局变量在项目配置文件变量键中定义。

全局变量值可以是以下任何数据类型或包含这些类型的列表或字典：int， float, bool, str。

在模型定义中使用 @<VAR_NAME> 宏或 @VAR() 函数来访问全局变量值。后者函数要求将变量名称以单引号括起作为第一个参数，并将可选的默认值作为第二个参数。默认值是一种安全机制，用于在项目配置文件中未找到变量名称的情况下使用。
例如，以下这个 SQLMesh 配置键定义了六个不同数据类型的变量：

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

python版本：

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},
}

config = Config(
    variables=variables,
    ... # other Config arguments
)

模型定义可以像这样在WHERE子句中访问int_var值：

SELECT *
FROM table
WHERE int_variable = @INT_VAR

或者，可以通过将变量名传递给@VAR（）宏函数来访问相同的变量。注意，在调用@VAR（‘int_var’）时，变量名是用单引号括起来的：

SELECT *
FROM table
WHERE int_variable = @VAR('int_var')

默认值可以作为第二个参数传递给@VAR（）宏函数，如果配置文件中缺少该变量，该参数将用作回退值。

在这个例子中，WHERE子句将呈现为WHERE some_value = 0，因为在项目配置文件中没有定义名为missing_var的变量：

SELECT *
FROM table
WHERE some_value = @VAR('missing_var', 0)

对于 Python 宏函数，可通过 evalutor.var 方法获取类似的 API，对于 Python 模型，则可通过 context.var 方法获取类似的 API。

网关变量

与全局变量一样，网关变量在项目配置文件中定义。但是，它们是在特定网关的变量键中指定的：

gateways:
  my_gateway:
    variables:
      int_var: 1
    ...

python代码：

gateway_variables = {
  "int_var": 1
}

config = Config(
    gateways={
      "my_gateway": GatewayConfig(
        variables=gateway_variables
        ... # other GatewayConfig arguments
        ),
      }
)

在模型中使用与全局变量相同的访问方法来访问它们。
特定于网关的变量值优先于在根变量键中指定的具有相同名称的变量值。

局部变量

局部宏变量是在模型中定义的。局部变量的值优先于具有相同名称的全局变量或网关特定变量。
使用 @DEF 宏运算符定义您自己的局部宏变量。例如，你可以将宏变量 macro_var 设置为值 1 的方式如下：

@DEF(macro_var, 1);

SQLMesh 对使用 @DEF 运算符有着三项基本要求：

1. MODEL 语句必须以分号结尾；
2. 所有 @DEF 使用项都必须置于 MODEL 语句之后、 SQL 查询语句之前。
3. 每个 @DEF 使用都必须以分号结尾；
   例如，请参考 SQLMesh 快速入门指南中的以下模型 sqlmesh_example.full_model：

MODEL (
  name sqlmesh_example.full_model,
  kind FULL,
  cron '@daily',
  audits (assert_positive_order_ids),
);

SELECT
  item_id,
  count(distinct id) AS num_orders,
FROM
  sqlmesh_example.incremental_model
GROUP BY item_id

这个模型可以用一个用户定义的宏变量来扩展，以根据item_size过滤查询结果，如下所示：

MODEL (
  name sqlmesh_example.full_model,
  kind FULL,
  cron '@daily',
  audits (assert_positive_order_ids),
); -- NOTE: semi-colon at end of MODEL statement

@DEF(size, 1); -- NOTE: semi-colon at end of @DEF operator

SELECT
  item_id,
  count(distinct id) AS num_orders,
FROM
  sqlmesh_example.incremental_model
WHERE
  item_size > @size -- Reference to macro variable `@size` defined above with `@DEF()`
GROUP BY item_id

本例使用@DEF（size, 1）定义宏变量size。当模型运行时，SQLMesh将在where子句中出现@size的地方替换数字1。

宏函数

除了内联用户定义变量外，SQLMesh还支持内联宏函数。与单独使用变量相比，可以使用这些函数来表达更具可读性和可重用性的逻辑。让我们来看一个例子：

MODEL(...);

@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,
  cust_rank_1,
  cust_rank_2,
  cust_rank_3
  @rank_to_int(cust_rank_1) as cust_rank_1_int,
  @rank_to_int(cust_rank_2) as cust_rank_2_int,
  @rank_to_int(cust_rank_3) as cust_rank_3_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

@DEF(nrr, (starting_mrr, expansion_mrr, churned_mrr) -> (starting_mrr + expansion_mrr - churned_mrr) / starting_mrr);

SELECT
  @nrr(fy21_mrr, fy21_expansions, fy21_churns) AS fy21_net_retention_rate,
  @nrr(fy22_mrr, fy22_expansions, fy22_churns) AS fy22_net_retention_rate,
  @nrr(fy23_mrr, fy23_expansions, fy23_churns) AS fy23_net_retention_rate,
FROM
  some.revenue

你可以像这样嵌套宏函数：

MODEL (
  name dummy.model,
  kind FULL
);

@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

最后总结

SQLMesh的宏与变量系统，本质上是将SQL开发从“硬编码”推向“声明式编程”的桥梁。其核心价值体现在三方面：

1. 语义级宏处理：通过解析SQL结构而非单纯文本替换，确保宏操作不会破坏查询逻辑，同时支持复杂函数嵌套与Python代码注入。
2. 三层变量优先级：全局配置提供基础参数，网关变量细化环境差异，局部宏则实现模型级定制，层级间遵循“就近原则”，避免配置冲突。
3. 函数式宏编程：通过@DEF定义的宏函数支持多参数、条件分支与嵌套调用，将业务逻辑封装为SQL内的“插件”，显著提升复杂查询的复用性。

无论是处理多租户环境的动态表名替换，还是实现基于参数的查询条件分支，SQLMesh的宏系统都能以声明式语法简化开发流程。其设计哲学——“让SQL回归逻辑，让配置远离代码”，正在成为构建灵活、可扩展数据库流水线的标配工具。