一、概述
| 项目 | 说明 |
| 文件类型 | .sql |
| 语法 | Spark SQL（基于 Kyuubi） |
| 计算资源 | 数据分析型 / 数据计算型 Serverless 资源组 |
| 多语句 | 支持文件内多条 SQL（以 ; 分隔），按顺序执行 |
| 输出能力 | 可作为下游任务的参数来源（{{tasks.<name>.output.rows}}） |
通用配置（任务名称、上游依赖、运行条件、参数、监控指标、告警、失败与超时策略）请参考 任务通用配置。
二、前提条件
·工作空间已绑定 数据分析型 或 数据计算型 Serverless 资源组。详见 计算资源概述。
·Studio 中已存在目标 SQL 文件，且当前用户（或 Run As 账号）具备「运行」权限以上。
·已具备目标 Catalog 中相关库表的访问权限。
四、步骤 1：创建任务
1. 在工作流画布单击 + 添加任务 。
2. 任务类型选择 SQL 。
五、步骤 2：配置基本信息
| 参数 | 说明 | 是否必填 |
| 任务名称 | 同工作流内唯一。 | 是 |
| 任务类型 | SQL。可在下拉中切换为其他任务类型，切换后参数区会清空。 | 是 |
| 任务来源 | 工作空间 / Git。 | 是 |
| 路径 | 引用的 .sql 文件路径。 | 是 |
七、任务来源：工作空间
1. 单击「路径」输入框，弹出下拉列表：
·仅展示当前用户具有「查看」及以上权限、且已发布过 的 SQL 文件。
·列表显示文件名、文件路径，支持模糊搜索。
2. 选中后路径填入输入框，例如 /Workspace/your_username/daily_summary.sql。
3. 选中文件后右侧操作：
·预览图标 ：弹窗预览 SQL 代码内容。
·跳转图标 ：新开页面到 Studio 中打开文件。
八、任务来源：Git
操作与 Notebook 任务一致，详见 Notebook 任务 的步骤 3：选择 Notebook 文件 – 任务来源：Git。
注意：若用户选中仅有「查看」权限的文件，输入框下方提示「当前文件仅有查看权限，无法用于任务运行」，创建、保存按钮置灰 。运行需要至少「运行」权限。
九、步骤 4：配置计算资源
| 参数 | 说明 | 是否必填 | 默认值 |
| 计算资源 | 数据分析型或数据计算型 Serverless 资源组。下拉仅展示这两类。 | 是 | 引用文件中选中的资源 |
允许在任务级别覆盖默认资源。任务中调整不会回写到 Studio 中的 SQL 文件 。
十、步骤 5：参数
参考 任务参数配置。SQL 任务的特殊行为：
十一、工作空间 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。
20、使用限制
·计算资源仅支持数据分析型、数据计算型 Serverless 资源组。
·SQL 任务文件必须是 已发布状态 （即已在 Studio 中保存为正式版本）；草稿态文件不能被任务引用。
·多语句按顺序执行，遇错中断；不支持并行。
·运行结果 tab 最多展示 1w 行 / 5M；作为下游参数源时最多 1000 行 / 48 KB（详见上文「运行结果 tab 展示上限」）。
·SQL 输出最多 1000 行 / 48 KB；超出部分不参与下游传递。
·任务运行需要 Run As 具备文件 ACL「运行」及以上权限，否则直接置失败。
·当 Studio 中引用的 SQL 文件被删除后，工作流任务运行直接置失败。
21、常见问题
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 文件、独立任务。
22、相关文档
·SQL 脚本运行
·参数化实现
·参数传递
·计算资源概述