创建宏

宏是一种可复用的高级（DAG）工作流，带有已声明的输入/输出契约。可以通过 Macro Run 步骤或 Macro Concurrent 步骤从另一个工作流中调用宏。每次调用都在各自独立的临时架构中运行，因此同一个宏可以被多个父工作流或多个驱动行并发调用，而运行之间不会冲突。

当存在可重复、带参数的数据转换时，请使用宏，例如“处理某个区域一个月的销售数据”，并希望由驱动工作流按月、按区域或两者兼有的方式逐次调用。调用方将表和变量绑定到宏声明的输入端口；宏运行结束后，声明的输出表会复制回调用方的目标位置。

注意

宏是高级工作流专属的功能。请先将工作流转换为高级工作流。宏内部的步骤必须适合在宏中使用：表转换、导入、导出、运行范围的变量步骤、嵌套的 Macro Run 调用，以及少数几个控制流步骤。维度导入和更新维度的步骤会被拒绝，因为维度是项目全局状态。

步骤

1. 打开包含要转换为宏的工作流的项目。
2. 切换到工作流选项卡，选择该工作流所在的行。
3. 在右侧的工作流详细信息面板中，确认工作流类型为高级。如果是标准工作流，请先使用转换为高级操作。
4. 在工作流详细信息面板的宏部分，点击转换为宏…，并在对话框中确认。工作流随即切换为宏模式，并出现端口编辑器。
5. 点击添加端口，声明宏接受或产生的每个输入或输出。对于每个端口：
   • 名称：调用方用来绑定到该端口的简短标识符（例如 month、region_sales）。
   • 方向：输入（由调用方提供该值或表）或输出（由宏生成，调用方获取）。
   • 类型：表表示数据表，标量表示单个值（字符串 / 整数 / 浮点数 / 布尔值 / 日期），维度表示对层次维度的引用。
   • 必填：如果宏在该端口未绑定的情况下也可以运行，请取消勾选。
   • 备注：简要说明该端口代表什么，会在调用方的绑定表单中显示给作者。
6. 点击保存端口。

该工作流现在就是一个宏。在其他工作流中添加 Macro Run 步骤的作者，将看到您声明的端口，并按名称绑定到这些端口。

每个端口是宏契约中一个具名、带类型的槽位。调用方按名称绑定到端口：输入被复制进来，输出被复制出去。

调用宏

在调用方工作流中：

1. 添加一个宏：运行步骤。
2. 在要运行的宏中，选择项目和宏工作流。
3. 输入端口绑定：为宏声明的每个输入端口添加一个绑定：
   • 表端口接收调用方的源表；可以选择列的子集并添加筛选器（引用宏的标量输入变量的 WHERE 子句），这样只有所需的数据切片才会具体化到宏的运行架构中。
   • 标量 / 维度端口接收一个值（通常是调用方的工作流变量），须在表复制进入之前设置，这样表输入筛选器才能引用它。
4. 输出端口绑定：为宏生成的每个输出端口指定调用方的目标表（如果尚不存在，则即时创建）。
5. 保存该步骤。

父工作流运行到 Macro Run 步骤时，运行器会：

1. 为本次宏调用生成一个新的 run_id。
2. 在项目目录中创建每次运行专用的临时架构（macrorun_<run_id>）。
3. 将已绑定的输入表复制到临时架构中（在复制进入时应用列投影和筛选器，因此筛选器会下推）。
4. 在宏的运行范围变量覆盖层上设置已绑定的标量 / 维度输入变量。
5. 在进程内运行宏的步骤。宏内的每个 SQL 步骤都读写临时架构，而不是项目架构。
6. 将声明的输出表复制回调用方的目标位置。
7. 删除临时架构（始终执行，即使宏内的某个步骤失败也是如此）。

每次调用都有全新的 run_id 和自己的临时架构。步骤只读写该架构，运行结束时（无论成功、出错还是停止）它都会被删除。

由于每次调用都有自己的临时架构，同一个宏的两次并发调用（来自循环、扇出或相互独立的工作流）绝不会在中间表名称上发生冲突。

为每个驱动行运行一个宏

当需要由一个调用方表驱动多个相互独立的宏调用时，请使用宏：并发运行。

1. 添加一个宏：并发运行步骤。
2. 在驱动中，选择调用方的驱动表，并将并发运行设置为同时运行的子宏调用的最大数量。
3. 在表数据选择中，映射每个子调用所需的驱动表列。
4. 在驱动因素筛选器中，可以选择性地限制要处理的驱动行。
5. 在宏中，选择宏工作流。
6. 在输入绑定中，将驱动列的值绑定到宏的标量或维度变量，并将调用方的表绑定到宏的表端口。
7. 在输出绑定中，将宏的输出端口映射到调用方的目标表。

每个选定的驱动行都有各自独立的 run_id 和临时架构。停止父步骤会停止所有活动的子调用并删除它们的运行架构。

每个驱动行对应一次调用，各自使用独立的临时架构，因此中间表绝不会冲突。并发运行限制同时运行的数量，每一行写入各自的 results_{region} 表。

降级宏

随时可以在工作流详细信息面板中点击降级为高级… 来清除宏标志。工作流会恢复为普通的高级工作流，任何引用它的调用方 Macro Run 步骤在运行时都会失败，并报“不是宏”的错误。已声明的端口会保留在记录中，因此之后重新转换时可以恢复它们。

限制（v1）

• 宏可以包含表转换、导入和导出，因为表的读写被隔离在该次调用的临时架构中。不允许使用维度导入和更新维度的步骤，因为维度是项目全局状态。其他非表的副作用步骤，例如文档操作和代理调用，在 v1 中不适合在宏中使用。
• 宏必须与调用方位于同一项目中。暂不支持跨项目宏。
• Macro Run 步骤不能由 Run Workflow、Workflow Loop 或带条件的 Run Workflow 调用，因为这些步骤在未隔离的状态下运行，会破坏每次运行专用架构的契约。请改为在调用方中使用 Macro Run 步骤。

后续步骤

• Macro Run 步骤参考：调用步骤的逐字段参考。
• Macro Concurrent 步骤参考：为驱动表的每一行运行一次宏调用。
• Run Workflow 步骤：适用于不需要按调用隔离的子工作流。