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: 1float_var: 2.0bool_var: truestr_var: "cat"list_var: [1, 2, 3]dict_var:key1: 1key2: 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，值為1SELECTitem_id,count(distinct id) AS num_orders,
FROMsqlmesh_example.incremental_model
WHEREitem_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
);SELECTid,@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)));SELECTsideA,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項目的工作效率和可靠性。