数据集与数据加工

数据集是报表中心的数据加工层，定义「取什么数、如何加工」。一个数据集绑定一个数据源，产出一张二维表（列 + 行），供仪表盘组件、打印报表、预警规则消费。在「报表中心 → 数据集」（/report/datasets）维护。

新建数据集

点击「新增」，填写名称、选择数据源（类型由数据源决定）。
按数据源类型编写取数内容（见下文）。
点击「试跑预览」查看取数结果（默认取前 50 行）。
点击「用结果生成字段」，自动把结果列生成字段定义。
保存。

SQL 数据集（内置库 / MySQL / PostgreSQL / SQL Server）

在「SQL」编辑框里编写只读查询：

sql

SELECT type AS name, count(*)::int AS value
FROM menus
GROUP BY type
ORDER BY value DESC

支持任意 SELECT / WITH（CTE）、JOIN、聚合、子查询。系统会自动限制返回行数并设置语句超时。

可视化建模（零 SQL 生成）

不熟悉 SQL 时，可点击「可视化建模」面板：选择数据表 → 勾选维度（分组列）与指标（聚合列）→ 可选筛选条件 / 排序 / 行数限制 → 「生成 SQL」自动回填编辑器（可继续手工微调）。

表/列清单来自内置只读主库元数据，敏感表与敏感列（密码、密钥、会话等）已自动隐藏；
生成的 SQL 标识符经白名单校验与转义，仍走只读执行通道；
建模配置随数据集保存，再次编辑可回显继续调整。

参数化查询 `${param}`

在 SQL 中用 ${参数名} 占位，声明参数后即可在运行时注入（防注入：参数以绑定变量传入，绝不字符串拼接）：

sql

SELECT * FROM orders
WHERE (${status} = '' OR status::text = ${status})
  AND created_at >= ${startDate}

在「参数定义」区声明每个参数的参数名、标题、类型、默认值与是否必填（参数名不能以 __ 开头，该前缀为系统变量保留）。「试跑预览」时可直接填入参数值验证参数化查询。参数可在仪表盘中与全局筛选器绑定，实现联动取数。

数据权限系统变量

以下系统变量由服务端权威注入当前登录用户上下文，可用于行级数据权限过滤（用户无法伪造）：

变量	含义
`${__userId}`	当前用户 ID
`${__username}`	当前用户名
`${__tenantId}`	当前租户 ID
`${__deptId}`	当前用户所属部门 ID

sql

-- 仅查询当前用户所在部门的数据
SELECT * FROM orders WHERE dept_id = ${__deptId}

注意

使用了系统变量的数据集不能启用物化快照（见下文），否则会把首个请求者的数据发给所有人；系统会在保存时拦截。

行级权限规则（声明式）

除了手写系统变量，还可以在「行级权限」区配置声明式规则，按角色下发行级过滤，无需改动 SQL 本身：

字段	说明
角色	规则生效的角色（多选）；留空 = 对所有登录用户生效
WHERE 片段	过滤条件（不含 `WHERE` 关键字），可引用 `${__userId}` 等系统变量与数据集参数，禁止分号
启用	规则开关

取数时把命中的规则（用户角色匹配）以「或」合并，包裹原查询过滤：

用户未命中任何规则 → 不受限（规则是「限制」性的）；
超级管理员始终不受限；
无用户上下文的场景（预警 Cron 评估、订阅推送、公开分享）跳过行级过滤——创建这些资源的人已通过权限门槛，公开分享属数据主人主动公开；
配置了行级规则的数据集不能启用物化快照（快照对所有人一致会绕过过滤，保存时拦截）；
结果缓存按「生效规则」隔离，不同权限视角互不串扰。

例：销售角色只看华东区 → 角色选「销售」，WHERE 片段填 region = '华东'；销售总监不配置规则即可看全部。

血缘与删除保护

列表「血缘」可查看数据集的上游数据源与下游引用（哪些仪表盘组件/筛选器、打印报表、预警规则在使用）。存在下游引用的数据集无法删除（后端拦截并列出引用明细），防止仪表盘悄悄失效或预警被级联误删。

API 数据集

数组路径：响应中数组所在的点分隔路径（如 data.list），留空表示响应根即数组。
附加参数：选填 JSON 键值，作为查询参数（GET 拼到 URL，POST 放入 body）；运行时参数优先级更高。

静态数据集与文件上传

数据源选「静态数据」时：

粘贴 JSON：在文本框粘贴一个对象数组，如 [{"city":"北京","sales":120}]。
上传文件：点击「上传 Excel/CSV」，系统解析首个工作表（首行为表头）并预览。CSV 单元格统一按文本读取，避免手机号、前导零、大整数被破坏。

静态数据最多 5000 行。

计算字段（衍生列）

在原始结果之上用表达式计算新列，无需修改 SQL。在「计算字段」区添加：

列名 / 显示名 / 类型
表达式：直接引用其它列名

text

round(amount / 100, 2)            金额分转元
concat(province, '-', city)       拼接地区
profit > 0 ? '盈利' : '亏损'       条件判断

支持运算 + - * / %、比较、三元 ?:、逻辑 && ||，以及函数 round / floor / ceil / abs / min / max / sqrt / pow / concat / upper / lower / trim / length / substr / coalesce / ifnull / if 等。表达式在服务端安全求值（无 eval，白名单函数）。

字段格式化与字典翻译（语义层）

每个字段可配置显示格式，统一在表格组件、打印报表中生效：

格式	说明
number	千分位 + 小数位
percent	百分比（值 ×100 加 `%`）
currency	货币符号 + 千分位
date / datetime	截取为 `YYYY-MM-DD` / `YYYY-MM-DD HH:mm:ss`
dict	按字典编码把存储值翻译为字典标签（如 `1` → `启用`）

结果缓存（TTL）

为高频读取的数据集设置「缓存(秒)」（cacheTtl，0 = 不缓存）。命中后按 数据集 + 参数 + 用户 维度从 Redis 返回，降低数据库压力。数据集更新/删除时缓存自动失效。

物化快照

「物化快照」把取数结果持久化为全局快照，适合给大屏/高频报表降压：

启用后取数优先返回快照，不再实时查库。
可配置刷新 Cron（留空 = 仅手动刷新）；也可在列表点「刷新物化」手动触发。
快照带 24h 安全 TTL，刷新由定时任务每分钟巡检到期项。

物化的约束

物化是全局快照，会忽略运行时参数、且不含用户上下文。因此含参数或使用了 ${__*} 数据权限变量的数据集不允许启用物化（保存时拦截），避免筛选被忽略或跨用户串号。物化只适用于「对所有人一致」的结果集。

导出

数据集列表每行提供 Excel / CSV 导出，接入项目统一的导出中心（异步任务 + 下载中心 + 水印 + 留存策略）。列结构按数据集字段（含计算字段）动态生成。

权限

操作	权限码
查看 / 预览 / 导出	`report:dataset:list`
新增 / 上传解析	`report:dataset:create`
编辑 / 手动刷新物化	`report:dataset:update`
删除	`report:dataset:delete`

数据集与数据加工 ​

新建数据集 ​

SQL 数据集（内置库 / MySQL / PostgreSQL / SQL Server） ​

可视化建模（零 SQL 生成） ​

参数化查询 ${param} ​

数据权限系统变量 ​

行级权限规则（声明式） ​

血缘与删除保护 ​

API 数据集 ​

静态数据集与文件上传 ​

计算字段（衍生列） ​

字段格式化与字典翻译（语义层） ​

结果缓存（TTL） ​

物化快照 ​

导出 ​

权限 ​