SQL 任务用于在 Workflow 中调度运行 Studio 中的
.sql 文件，统一使用 Spark SQL 语法。SQL 任务支持引用工作空间或 Git 文件夹中的 SQL 文件，运行在数据分析型、数据计算型 Serverless 资源组上。概述
项目 | 说明 |
文件类型 | .sql |
语法 | Spark SQL（基于 Kyuubi） |
计算资源 | 数据分析型 / 数据计算型 Serverless 资源组 |
多语句 | 支持文件内多条 SQL（以 ; 分隔），按顺序执行 |
输出能力 | 可作为下游任务的参数来源（ {{tasks.<name>.output.rows}}） |
通用配置（任务名称、上游依赖、运行条件、参数、监控指标、告警、失败与超时策略）请参考 配置任务。
前提条件
工作空间已绑定 数据分析型 或 数据计算型 Serverless 资源组。详见 计算资源概述。
Studio 中已存在目标 SQL 文件，且当前用户（或 Run As 账号）具备「运行」权限以上。
已具备目标 Catalog 中相关库表的访问权限。
操作步骤
步骤 1：创建任务
1. 在工作流画布单击 + 添加任务 。
2. 任务类型选择 SQL 。
步骤 2：配置基本信息
参数 | 说明 | 是否必填 |
任务名称 | 同工作流内唯一。 | 是 |
任务类型 | SQL。可在下拉中切换为其他任务类型，切换后参数区会清空。 | 是 |
任务来源 | 工作空间 / Git。 | 是 |
路径 | 引用的 .sql 文件路径。 | 是 |
步骤 3：选择 SQL 文件
任务来源：工作空间
1. 单击「路径」输入框，弹出下拉列表：
仅展示当前用户具有「查看」及以上权限、且已发布过 的 SQL 文件。
列表显示文件名、文件路径，支持模糊搜索。
1. 选中后路径填入输入框，例如
/Workspace/your_username/daily_summary.sql。2. 选中文件后右侧操作：
预览图标 ：弹窗预览 SQL 代码内容。
跳转图标 ：新开页面到 Studio 中打开文件。
任务来源：Git
注意
若用户选中仅有「查看」权限的文件，输入框下方提示「当前文件仅有查看权限，无法用于任务运行」，创建、保存按钮置灰 。运行需要至少「运行」权限。
步骤 4：配置计算资源
参数 | 说明 | 是否必填 | 默认值 |
计算资源 | 数据分析型或数据计算型 Serverless 资源组。下拉仅展示这两类。 | 是 | 引用文件中选中的资源 |
允许在任务级别覆盖默认资源。任务中调整不会回写到 Studio 中的 SQL 文件 。
步骤 5：参数
工作空间 SQL 文件
任务配置面板自动从 Studio SQL 文件的「参数」弹窗中拉取参数（仅参数名置灰，参数值可改）。
在任务级别可新增任务专属参数，参数名不能与从文件下发的参数重复。
Git 远程仓库 SQL 文件
不自动解析文件中的参数；需要手动添加参数名与参数值。
SQL 中引用参数
SELECT *FROM your_catalog.your_schema.ordersWHERE dt = '${dp_data_dt}'LIMIT 100;
步骤 6：上游依赖、监控指标、告警、失败与超时策略
参考 配置任务。SQL 任务的失败与超时策略默认为「执行失败后重试 = 关闭」。
步骤 7：保存
单击 创建任务 或 保存任务 。
参数说明
SQL 输出作为下游参数
SQL 任务的输出可被下游任务通过参数引用：
引用 | 含义 | 限制 |
{{tasks.<name>.output.rows}} | 全部行（JSON 数组） | 最多 1000 行 / 48 KB |
{{tasks.<name>.output.first_row}} | 第一行（JSON 对象） | 同上 |
{{tasks.<name>.output.first_row.<col>}} | 第一行指定列值 | 同上 |
提示
SQL 文件中包含多条 SQL 时，只返回 第一个 SELECT 语句 的结果。INSERT、UPDATE 等不返回行的语句不计入输出。
运行结果 tab 展示上限
SQL 任务运行详情页的「运行结果」tab 直接展示 SELECT 语句返回的结果集，与下游参数传递的场景使用不同的上限：
场景 | 行数上限 | 大小上限 |
运行结果 tab 展示 | 1w 行 | 5 M |
作为下游参数源（ output.rows / output.first_row 等） | 1000 行 | 48 KB |
超出部分不展示、不计入参数传递。如需获取完整结果集，请在 SQL 中使用
INSERT INTO 写入目标表后再消费。默认 Catalog / Schema
任务运行时按 Studio SQL 文件中保存的「默认 Catalog」「默认 Schema」解析未带前缀的表名。如 SQL 中只写
table_name，会自动补全为 <默认 Catalog>.<默认 Schema>.table_name。详细规则参考 SQL IDE 基础操作。使用限制
计算资源仅支持数据分析型、数据计算型 Serverless 资源组。
SQL 任务文件必须是 已发布状态 （即已在 Studio 中保存为正式版本）；草稿态文件不能被任务引用。
多语句按顺序执行，遇错中断；不支持并行。
运行结果 tab 最多展示 1w 行 / 5M；作为下游参数源时最多 1000 行 / 48 KB（详见上文「运行结果 tab 展示上限」）。
SQL 输出最多 1000 行 / 48 KB；超出部分不参与下游传递。
任务运行需要 Run As 具备文件 ACL「运行」及以上权限，否则直接置失败。
当 Studio 中引用的 SQL 文件被删除后，工作流任务运行直接置失败。
常见问题
Q1：SQL 文件中包含
INSERT INTO 和 SELECT，下游能拿到 SELECT 结果吗？
取决于语句顺序。系统按出现的第一个 SELECT 返回结果；如果 SELECT 在 INSERT 之后，可正常被引用。Q2：从 Git 引用 SQL 文件，参数怎么写？
Git 引用不自动解析参数。需要：
1. 在 SQL 中使用
${param_name} 占位符。2. 在任务配置面板手动添加任务参数
param_name，并填入值。Q3：发布 Studio SQL 文件时会同步更新所有引用的任务参数吗？
新增参数 ：自动同步到所有引用任务。
任务中已有参数、工作流参数 ：不覆盖任务中的取值。
Q4：单文件多条 SQL 中只想运行其中一条怎么办？
SQL 任务执行整文件。如需精细化控制，请将不同语句拆为独立 SQL 文件、独立任务。
相关文档
SQL IDE 基础操作
