SQL 数据集

概述

SQL 数据集通过一个「数据连接」执行一条 SQL，把查询结果作为数据集字段与行。它是最常用的数据集类型，报表参数、动态条件、集合参数、存储过程都在 SQL 数据集中使用。

本文说明编辑对话框的使用；SQL 中的参数占位与动态语法见 SQL 参数与动态语法，可直接套用的写法见 SQL 写法示例。

功能入口

报表设计器数据集面板：点击「新建SQL数据集」并选择「SQL数据集」，或右键已有数据集选择「编辑」。也可在「系统 > 公共数据集」中创建由多张报表共用的 SQL 数据集，见 公共数据集。

操作步骤

1. 打开「编辑数据集」对话框，「基础」标签页中填写「数据集名称」。
2. 在「数据连接」下拉框选择已建好的连接。
3. 在 SQL 编辑区写 SQL。右侧「语法」「函数」「代码片段」三个标签页可查阅语法与函数并插入，「常用写法」按钮打开「常用 SQL 写法」对话框，可点「复制 SQL」。
4. SQL 中引用了报表参数时，点击底部「从SQL提取参数到报表参数」，或直接预览、保存，系统会自动登记。参数类型可点「报表参数」按钮调整。
5. 点击「数据预览」，在「查询参数」区填写参数后点「查询」，检查字段和数据，见 数据集预览与调试。
6. 点击「确定」保存。保存时系统以 1 行的限制实际执行一次 SQL 来识别字段，SQL 有错会在此处提示。

关闭对话框时如有未保存的更改，提示「有未保存的更改，确认关闭吗？」。

属性说明

「基础」标签页

「数据粒度」只影响设计器中的提示，不改变查询输出。

数据大屏使用同一编辑器时，还会出现「增量消息流」与「保留窗口行数」（1–5000）两项，仅大屏用。

其他标签页

底部按钮

「报表参数」「从SQL提取参数到报表参数」「数据预览」「取消」「确定」。

行数限制与超时的取值顺序

数据集填写的值在允许范围内时优先采用，否则使用「系统 > 系统设置 > 报表 > 报表运行」中的全局值，见 数据集概述。查询结果超过行数上限会报错而不是截断；超时会报出含秒数的超时提示。执行器按 上限 + 1 行读取来判断是否超限，驱动默认抓取量较小时会提高到 500 行以减少往返。

示例

假设有医院门诊表 outpatient_visit（visit_id、patient_name、dept_code、visit_date、fee）。报表参数 startDate、endDate 为日期类型，deptCode 为字符串类型且可为空。

SELECT visit_id, patient_name, dept_code, visit_date, fee
FROM outpatient_visit
WHERE visit_date >= $startDate
  AND visit_date <  $endDate
  #{isEmpty($deptCode) ? '' : 'AND dept_code = $deptCode'}
ORDER BY visit_date DESC

点击「数据预览」，填入 startDate=2026-09-01、endDate=2026-10-01，「SQL 预览」标签页会给出参数化 SQL 与参数列表，可验证 deptCode 为空时条件被整段省略。

SQL 末尾的分号会被自动去除，写成 ORDER BY visit_date DESC; 同样可用。

注意事项

注意：引用报表参数要写成 $名。误写成 ${名}（缺少 $）时该表达式取不到值，编辑器会提示「SQL 里的 ${名} 取不到值——引用报表参数要写成 $名」。

注意：用了「数据浏览报表」时由系统接管分页，不要在同一个模板里再手写 LIMIT、OFFSET、ROWNUM 分页。

提示：把过滤条件放在 SQL 的 WHERE 中，让数据库过滤，比取回大量数据后在报表里筛选更快，也不容易触发行数上限。

相关文档

• SQL 参数与动态语法
• SQL 写法示例
• 存储过程数据集
• 数据集预览与调试
• 数据源配置