宏

在 Jinja 中，宏（Macro）类似于编程语言中的函数。它允许你定义可重用的代码块，接受参数、处理逻辑并返回结果。Jinja 宏常用于 SQL 模型中，以封装转换逻辑，避免重复的 SQL 代码，从而提升可维护性。

在 Recurve 项目中，你可以将宏定义为资产，并在不同模块和多个模型中复用。

语法

Jinja 宏通过 {% macro %} 和{% endmacro %} 语句进行定义。与 Python 函数类似，宏接受参数、处理逻辑并返回结果。

示例如下：

{% macro filter_by_status(min_amount, status='completed') %}
    select *
    from {{ source('jaffle_shop', 'orders') }}
    where status = '{{ status }}'
    and amount >= {{ min_amount }}
{% endmacro %}

上面的代码定义了一个名为 filter_by_status 的宏，该宏根据参数min_amount 和可选参数 status的值，从 orders 表中查询所有符合条件的订单记录。

定义宏

要定义一个项目级宏，请按照以下步骤操作：

1. 在 Recurve 中打开你的项目，进入 Library > Macro。

2. 点击 “新建 + Add New”。

3. 输入宏的名称、描述和 SQL 代码。

1. 点击 “创建/Add”。

新创建的宏将显示在 Library 的 Macro 部分。

默认情况下，创建的宏是启用状态，可以立即在模型中使用。如果需要停用宏，可以通过关闭 “启用/ Active” 选项来禁用它。

调用宏

在宏被定义并启用后，你可以在项目中的任何模型中调用它。宏通过 {{ ... }} 表达式进行调用。

例如，使用 filter_by_status 宏，我们可以进一步筛选出高价值的已完成订单。

with filtered_orders as (
   {{ filter_by_status(min_amount=50, status='completed') }}
),

enriched_orders as (
   select 
       order_id,
       amount,
       order_date,
       customer_id,
       case when amount > 100 then 'high_value' else 'standard' end as order_tier
   from filtered_orders
)

select * from enriched_orders

编译结果

with filtered_orders as (
    -- 按照传入的参数取值渲染可重用的代码
    select *
    from {{ source('jaffle_shop', 'orders') }}
    where status = 'completed'
    and amount >= 50
),

enriched_orders as (
   select 
       order_id,
       amount,
       order_date,
       customer_id,
       case when amount > 100 then 'high_value' else 'standard' end as order_tier
   from filtered_orders
)

select * from enriched_orders