概述
本文介绍如何为仪表盘添加数据集（Dataset）。仪表盘支持 3 种数据集来源：SQL 编写、Catalog 表、本地文件上传 。同时介绍如何配置数据集的参数、自定义计算字段，并查看查询性能。
数据集是仪表盘内对一份查询结果的抽象，可被同一仪表盘内多个图表复用。每次仪表盘刷新时，平台按照数据集的查询语句重新拉取数据。
前提条件
在开始本操作前，请确保满足以下条件：
已开通 DataBuddy 服务并完成空间初始化。
当前账号在仪表盘中拥有 可编辑 或更高权限。
已选择并启动一份「交互式集群」计算资源（详见下方 计算资源概述 章节）。
接入的 Catalog 表，当前账号拥有访问权限。
使用限制
限制项 | 说明 |
数据集名称 | 最多 100 个字符，由字母、汉字、数字和下划线组成，不能以数字开头 |
自定义计算字段名称 | 最多 128 个字符，规则同上 |
自定义计算字段备注 | 最多 255 个字符 |
单个数据集参数数量上限 | 512 |
文件上传 | 支持 .csv / .avro / .json / .parquet / .txt / .xml；最多 10 个，总大小 ≤ 2 GB |
查询结果缓存 | 24 小时（共享发布模式整库一份；查看者权限模式按用户级缓存） |
数据集自身缓存 | 数据量 ≤ 10 万行且 ≤ 100 MB 时缓存数据集；否则仅缓存查询结果 |
操作步骤
步骤 1：选择计算资源
数据集运行需要「交互式集群」计算资源。
1. 在仪表盘编辑态，画布顶部的 计算资源 下拉中选择一份计算资源。
2. 系统会自动选择上一次仪表盘使用过的计算资源；如该资源已启动则立即可用，未启动显示「启动中」。
3. 切换计算资源会中断当前刷新，使用新资源重新执行查询。
注意：
若未选择计算资源就执行 SQL、添加数据集或上传文件，会报「请先选择计算资源！」。计算资源被删除或权限被回收时，组件会报错。
步骤 2：从 SQL 创建数据集
在画布中间&左侧数据集右上角 面板中，点击 从 SQL 创建 ：
1. 弹出 SQL 编辑器，左侧列表显示数据集名称（默认「无标题数据集1」，可重命名）。
2. 在编辑器中编写 SQL；编辑器支持代码高亮，默认不附加 LIMIT 子句。
3. 点击 运行 执行查询；运行中按钮变为「终止」，可随时点击终止。
4. 查询完成后，底部展示：
结果表 ：查询结果，支持字段排序。
Schema ：字段类型（左侧 icon）、字段名、备注；支持升降序排序，并标注计算字段。
可在 SQL 中调用平台提供的 AI 函数进行分析，例如：
函数 | 用途 |
ai_forecast | 时间序列预测（表值函数） |
ai_summarize | 文本自动摘要 |
ai_sentiment | 情感分析 |
ai_translate | 翻译 |
ai_extract | 实体/关键词抽取 |
ai_classify | 文本分类 |
ai_chat | 与大模型对话 |
ai_mask | 敏感信息脱敏 |
ai_similarity | 文本相似度 |
vector_search | 向量索引语义搜索 |
数据集名称重命名、删除：
点击数据集更多，可重命名或删除；删除前需二次确认。
当数据集仍被仪表盘组件使用时，会提示「无法删除此数据集，因为有仪表盘组件在使用此数据集」。
步骤 3：从 Catalog 创建数据集
在数据面板点击 从 Catalog 创建 ：
1. 在弹窗中拉取 Catalog 目录树，按 Catalog → Schema → Table / View 三级浏览。
2. 支持搜索、刷新；选择多张表、视图加入右侧 已选择 区，可点击 × 取消。
3. 点击 确认 后，所选表会以独立数据集形式加入仪表盘。
说明：
同一张表可重复添加进同一仪表盘的不同数据集。
步骤 4：从本地文件上传
在数据面板点击 上传文件 ：
1. 在弹窗中选择文件，支持 .csv / .avro / .json / .parquet / .txt / .xml，单次最多 10 个，总大小 ≤ 2 GB。
2. 配置上传选项：
选择引擎 ：影响后续表存储引擎。
上传方式、建表方式 ：创建新表、覆盖现有表。
表名称 ：命名规则与从 SQL 创建一致。
存储位置 ：
catalog.schema。选择字段、高级设置 。
3. 点击 确定 上传完成后：
数据面板新增「上传文件」数据集，SQL 编辑器自动写出引用建表的 SELECT（不含 LIMIT）。
Catalog 中也会新增对应数据表。
编辑器底部立即预览查询结果。
步骤 5：配置查询参数
参数用于让查询接受外部传入的值，在仪表盘端常用于配合筛选器实现「动态查询」。
触发与新建
在 SQL 编辑器中输入
${参数名} 时会自动解析为参数；上方 参数 按钮出现红点提示。配置参数
参数支持设置如下：
配置项 | 说明 |
类型 | 字符串（默认）/ 数值（包括小数 Decimal、整数 Integer）/ 日期 / 日期和时间 |
显示名称 | 参数在筛选器中显示的标题，最多 50 个字符 |
关键字 | 即 SQL 中 ${...} 内的标识符 |
参数值 | 参数运行时的初始值 |
多值开关 | 开启后参数支持多值（数组） |
参数与组件联动
修改 参数范围 ：所有引用该参数的图表立即按新范围重新计算；之前选中的值若不在新范围内会被重置为默认值或空值。
修改 参数类型 ：仪表盘中的参数控件类型会随之变化（如文本框变为数字输入框）；引用该参数的 SQL 若类型不匹配会报错。
删除参数 ：仪表盘中引用该参数的图表会失去绑定，相关查询将报「参数未定义」。
参数多值在筛选器中的输入
参数-设置，点击开启参数值多值，并且文案提示：请输入(${参数名})来使用参数多值。
非时间类型：在输入框中输入值后用英文逗号分隔；分隔后以标签形式展示。
时间类型：通过日历选择，多次选择以标签形式叠加。
参数单、多值切换规则：
多选转单选：仅保留多选的第一个值。
单选转多选：原值显示为标签。
多选 → 单选 → 多选：若中间未变更，原多值会回显。
步骤 6：配置自定义计算字段
自定义计算字段允许在数据集层面定义新的度量或维度，避免在每个图表中重复编写表达式。
1. 在 SQL 编辑器顶部点击 自定义计算 ，右侧抽屉中填写：
名称 （必填）：最多 128 字符。
备注 （选填）：最多 255 字符。
表达式 （必填）：使用 SQL 表达式，例如
(SUM(Price) - SUM(Cost)) / SUM(Price)。2. 表达式校验通过后，创建 按钮可点击；点击后字段保存。
3. 计算字段在 Schema 中以 fx 图标标识，分为：
度量 ：聚合值，如总销售额、平均成本。
维度 ：未聚合值或转换。
4. 在计算字段右侧的···更多中，支持编辑与删除（删除需要二次确认）自定义计算。
校验与限制
校验项 | 报错说明 |
SQL 语法 | 关键字拼写、缺逗号、结构错误 |
列名 | 引用不存在或拼写错误的列 |
数据类型 | 类型不兼容操作（如字符串加数字） |
除零 | 分母可能为零 |
NULL 处理 | 未正确处理 NULL |
保留字 | 用 SQL 保留字作为字段名时未加反引号 |
名称长度 | 超过 128 字符 |
聚合使用 | 混合聚合与非聚合列且无 GROUP BY |
列引用歧义 | 多表中存在同名列且未限定 |
同名 | 名称与已存在的列名相同 |
嵌套 | 不允许在自定义计算中嵌套引用其他自定义计算 |
在图表中的可用范围
图表类型 | 自定义维度 | 自定义度量 |
表格 | ✓ | ✗（不展示） |
点地图 | ✗ | ✗ |
饼图 / 指标卡 / 折线 | ✓ | ✓ |
柱状图 X 轴 | ✓ | ✗ |
柱状图 Y 轴 | ✓ | ✓ |
无效计算字段在图表配置下拉中不可选，悬停提示「计算无效，请更新表达式」。
步骤 7：查看查询性能
在 SQL 编辑器中运行查询后，点击 查看性能 可查看：
字段 | 说明 |
语句 | SQL 语句 |
启动于 | 运行时间，格式 yyyy-MM-dd HH:mm |
调度时间 | 调度引擎资源的时间。 |
持续时间 | SQL 执行时间。 |
读取的行 | 查询读取的行数 |
读取的字节 | 读取的数据的大小。 |
参数说明
数据集字段
参数 | 说明 | 是否必填 | 默认值 | 取值范围 |
数据集名称 | 数据集显示名 | 是 | 「无标题数据集1」 | ≤ 100字符，字母/汉字/数字/下划线 |
来源 | 数据集来源类型 | 是 | - | SQL / Catalog / 上传文件 |
自定义计算字段
参数 | 说明 | 是否必填 | 默认值 | 取值范围 |
名称 | 计算字段名 | 是 | - | ≤ 128 字符 |
备注 | 描述文字 | 否 | - | ≤ 255 字符 |
表达式 | SQL 表达式 | 是 | - | 支持引擎当前支持的函数 |
计算资源
仪表盘运行查询使用 交互式集群 计算资源。
状态 | 行为 |
资源未启动 | 编辑态会弹窗提示启动；启动失败时图表报「计算资源未启动」 |
用户失去授权 | 图表报「缺少权限」，资源选择框置为待选择 |
资源被删除 | 图表报「计算资源不存在」，资源选择框置为待选择 |
查看态访问仪表盘时，不显示计算资源选择 ；如刷新所需的 Serverless 资源未启动，会自动启用（此时基于仪表盘自身权限即可，无需 Serverless 单独授权）。
验证结果
完成数据集配置后：
1. 数据面板列表中可以看到刚添加的数据集，点击展开后能看到 Schema 与计算字段。
2. 在图表组件中下拉「数据集」可以选到该数据集，并在轴、字段配置中看到 Schema 中的字段。
3. SQL 数据集运行成功后，底部 结果表 与 Schema 同步显示。
常见问题
Q：为什么 SQL 运行很久依然没结果？
A：可能原因包括：① 计算资源刚启动，需冷启动时间；② 查询数据量大，需要较长执行时间；③ 系统正在排队。可点击运行按钮旁的 终止 中断查询，或查看 查看性能 了解实际执行情况。
Q：报「找不到表或视图」怎么办？
A：通常是 SQL 中的 catalog/schema/table 拼写错误，请检查后重新执行查询。
Q：DLC 报错信息看不懂？
A：平台已对常见 DLC 报错做了分类封装，常见场景包括 SQL 语法错误、无数据、操作权限、数据源不可用、查询超时、依赖对象变更、网络、连接问题、数据格式或类型不匹配等。
Q：上传 Excel 提示失败怎么排查？
A：① 文件格式是否在支持列表（.csv / .avro / .json / .parquet / .txt / .xml）；② 单次上传不超过 10 个文件且总大小 ≤ 2 GB；③ 是否选择了计算资源。
Q：参数取值是否区分查看者权限？
A：目前 PRD 并未明确区分；推荐由仪表盘管理员设置参数默认值。
相关文档
管理仪表盘权限
