SQLMesh 的宏变量是一个强大的工具，能够显著提高 SQL 模型的动态化能力和可维护性。通过合理使用宏变量，可以实现动态时间范围、多环境配置、参数化查询等功能，从而简化数据模型的开发和维护流程。随着数据团队的规模扩大和业务复杂度的增加，宏变量的重要性将愈发凸显。
介绍宏变量
SQLMesh 是一个开源的数据转换框架，旨在简化 SQL 数据模型的设计、维护和部署流程。它通过引入 DevOps 最佳实践，支持多引擎、虚拟环境和数据血缘分析等功能，帮助数据团队高效管理数据模型。在 SQLMesh 中，宏变量（Macro Variables）是一个重要的特性，用于在 SQL 模型中实现动态化和可重用性。以下将详细介绍 SQLMesh 的宏变量，并结合示例说明其用法和优势。
宏变量的定义与作用
宏变量是 SQLMesh 中用于动态替换值的占位符，允许用户在 SQL 模型中定义可重用的逻辑。它们的主要作用包括：
- 动态化 SQL 逻辑：通过宏变量，可以在运行时动态替换 SQL 中的值，避免硬编码。
- 提高代码复用性：将常用的逻辑封装为宏变量，减少重复代码。
- 简化维护：通过集中管理宏变量，降低维护成本。
SQLMesh 的宏变量通常以 @ 或 $ 开头，并在 SQL 模型中被引用。宏变量的值可以在模型定义、运行时或配置文件中指定14。
宏变量的分类
在 SQLMesh 中，宏变量可以分为以下几类：
- 内置宏变量：SQLMesh 提供了一些预定义的宏变量，例如
@start_date和@end_date，用于处理时间范围相关的逻辑。 - 用户自定义宏变量：用户可以根据需求定义自己的宏变量，并在 SQL 模型中引用。
- 环境变量：SQLMesh 支持从环境变量中读取值，并将其作为宏变量使用。
宏变量的使用场景
宏变量在 SQLMesh 中的应用场景非常广泛，以下是一些典型用例：
- 动态时间范围：在增量模型中，使用
@start_date和@end_date动态指定时间范围。 - 多环境配置：通过宏变量区分开发、测试和生产环境，例如动态切换数据库连接。
- 参数化查询：在查询中使用宏变量实现参数化，避免 SQL 注入风险。
- 代码复用：将复杂的逻辑封装为宏变量，供多个模型调用。
举例说明
宏变量是占位符，其值在呈现宏时被替换。它们支持动态宏行为——例如，日期参数的值可能基于宏运行的时间。
考虑一个在WHERE子句中按日期过滤的SQL查询。与每次运行模型时手动更改日期不同，您可以使用宏变量使日期动态。使用动态方法，日期会根据查询的运行时间自动更改。
这个查询过滤列my_date在‘2023-01-01’之后的行：
SELECT *
FROM table
WHERE my_date > '2023-01-01'
要使这个查询的日期动态，你可以使用预定义的SQLMesh宏变量@execution_ds：
SELECT *
FROM table
WHERE my_date > @execution_ds
@符号告诉SQLMesh， @execution_ds是一个宏变量，需要在执行SQL之前进行替换。
宏变量@execution_ds是预定义的，因此它的值将由SQLMesh根据执行开始的时间自动设置。如果模型在2023年2月1日执行，呈现的查询将是：
SELECT *
FROM table
WHERE my_date > '2023-02-01'
这个例子使用了SQLMesh的一个预定义变量，但是你也可以定义自己的宏变量。
我们将在下面描述SQLMesh的预定义变量；在SQLMesh宏和Jinja宏页面中讨论了用户定义的宏变量。
内置宏变量
SQLMesh附带了可以在查询中使用的预定义变量。它们由SQLMesh运行时自动设置。
大多数预定义变量都与时间相关，并使用前缀（start、end等）和后缀（date、ds、ts等）的组合。它们将在下一节中描述；下一节将讨论其他预定义变量。
时间变量
SQLMesh使用python datetime模块来处理日期和时间。它使用标准的Unix纪元开始符1970-01-01。
前缀:
- start - 包括模型运行的启动区间
- end - 包括模型运行的结束区间
- execution - 执行开始的时间戳
后缀：
- dt - Python 的 datetime 对象，可转换为原生的 SQL TIMESTAMP（或等效的 SQL 引擎类型）
- date - Python 的 date 对象，可转换为原生的 SQL DATE
- ds - 格式为 ‘%Y-%m-%d’ 的日期字符串
- ts - 格式为 ‘%Y-%m-%d %H:%M:%S’ 的 ISO 8601 日期时间格式字符串
- tstz - 格式为 ‘%Y-%m-%d %H:%M:%S%z’ 的带有时区的 ISO 8601 日期时间格式字符串
- hour - 表示一天中的小时数的整数，取值范围为 0 到 23
- epoch - 表示自 Unix 纪元以来的秒数的整数
- millis - 表示自 Unix 纪元以来的毫秒数的整数
所有预定义的时间宏变量：
- dt
- @start_dt
- @end_dt
- @execution_dt
- date
- @start_date
- @end_date
- @execution_date
- ds
- @start_ds
- @end_ds
- @execution_ds
- ts
- @start_ts
- @end_ts
- @execution_ts
- tstz
- @start_tstz
- @end_tstz
- @execution_tstz
- hour
- @start_hour
- @end_hour
- @execution_hour
- epoch
- @start_epoch
- @end_epoch
- @execution_epoch
- millis
- @start_millis
- @end_millis
- @execution_millis
运行时变量
SQLMesh提供了另外两个预定义变量，用于根据运行时可用的信息修改模型行为。
-
@runtime_stage — 字符串值，表示SQLMesh运行时的当前阶段。通常在模型中用于有条件地执行pre/post语句（在这里了解更多）。它返回以下值之一：
-
loading- 项目正在加载到 SQLMesh 的运行时上下文中。 -
creating- 模型表正在创建。 -
evaluating- 模型查询逻辑正在评估。 -
promoting- 模型正在目标环境中推广（虚拟层更新）。 -
auditing- 正在运行审计。 -
testing- 模型查询逻辑正在单元测试的上下文中评估。
-
-
@gateway — 包含当前网关名称的字符串值。
-
@this_model — 字符串值，包含模型视图选择的物理表的名称。通常用于创建通用审核。在on_virtual_update语句的情况下，它包含限定视图名称。
-
当SQLGlot不能完全解析语句，需要直接引用模型的底层物理表时，可以在模型定义中使用。
-
可以作为参数传递给访问或与底层物理表交互的宏。
-
实战案例
以下是一个完整的示例，展示如何在 SQLMesh 中使用宏变量实现动态时间范围和多环境配置。
1. 项目配置
gateways:
prod_gateway:
connection:
type: duckdb
database: prod.db
dev_gateway:
connection:
type: duckdb
database: dev.db
default_gateway: dev_gateway
2. 定义模型
MODEL (
name example.incremental_model,
owner Yuki,
kind INCREMENTAL_BY_TIME_RANGE (
time_column (updated_date, '%Y-%m-%d'),
lookback 5,
),
start '2025-01-01',
cron '@daily',
grain id,
column_descriptions (
id = 'primary key',
letter = 'alphabet letter',
updated_date = 'updated date',
)
);
3. 引用宏变量
SELECT
id,
letter,
updated_date
FROM
example.base_model
WHERE
updated_date BETWEEN @start_date AND @end_date
AND @gateway = 'prod_gateway';
4. 运行计划
sqlmesh plan --gateway prod_gateway
最后总结
SQLMesh 的宏变量是用于动态替换值的占位符，允许用户在 SQL 模型中定义可重用的逻辑。它们的主要作用包括动态化 SQL 逻辑、提高代码复用性和简化维护。SQLMesh 的宏变量可以分为内置宏变量、用户自定义宏变量和环境变量。宏变量在 SQLMesh 中的应用场景非常广泛，包括动态时间范围、多环境配置、参数化查询和代码复用。通过合理使用宏变量，可以显著提高 SQL 模型的动态化能力和可维护性。
