数据集预览与调试
数据集预览对话框的使用：查询参数、预览行数、数据与 SQL 预览、复制与下载，以及常见报错的排查。
概述
在保存数据集之前，可以用「数据预览」实际执行一次查询，查看字段、数据以及最终发给数据库的 SQL。预览用于确认动态条件、参数绑定和后处理结果是否符合预期。
功能入口
各数据集编辑对话框底部的「数据预览」按钮。SQL 数据集打开「数据集预览」对话框，标题为「数据集预览 数据集名」。
操作步骤
- 点击「数据预览」。
- 在「查询参数」区为参数填值，设置「预览数据行数」。
- 点击「查询」，在「数据预览」标签页看结果；点击「重置」恢复默认。
- 切换到「SQL 预览」标签页核对实际执行的 SQL。
- 结果不对时回到编辑器修改，再次预览。
属性说明
查询参数区
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
| 预览数据行数 | 预览返回的行数 | 界面 1–1000，默认 100；后端限制在 1–3000，越界时按 100 |
| 「查询」/「重置」 | 执行预览、恢复默认参数 | 按钮 |
「数据预览」标签页
| 项 | 说明 |
|---|---|
| 「共 N 条数据」 | 预览返回的行数 |
| 「复制 CSV」「复制 TSV」「下载 CSV」 | 导出预览数据 |
| 双击单元格 | 查看单元格内容，可切换 文本、JSON、XML、HTML 视图 |
| 「数据集预览失败」与「重试」 | 预览出错时显示，可重试 |
「SQL 预览」标签页
| 项 | 说明 |
|---|---|
| 「参数化 SQL（? 占位符）」 | 实际发送的预编译 SQL |
| 「参数」 | 依次绑定到 ? 的值 |
| 「可执行 SQL（参数已替换，可复制到数据库查询工具验证）」 | 把参数替换进去的完整 SQL，用于在数据库工具中复现 |
预览的处理顺序是：执行查询，应用后处理脚本，再应用计算字段。
后端接口
| 用途 | 接口 |
|---|---|
| SQL 结果与字段 | /dataset/buildSqlResult、/dataset/previewSql |
| API、派生数据集预览 | /previewApiDataset、/previewDerivedDataset |
| 字段校验 | /checkFields |
这些接口需要系统权限 datasource 或 report-design。
示例
调试一个可选条件：
SELECT visit_id, dept_code, fee
FROM outpatient_visit
WHERE visit_date >= $startDate
#{isEmpty($deptCode) ? '' : 'AND dept_code = $deptCode'}
- 填
startDate=2026-09-01，deptCode留空，查询后在「SQL 预览」看到参数化 SQL 中没有dept_code条件。 - 再填
deptCode=D01，查询，SQL 中出现AND dept_code = ?，参数列表多一个D01。 - 复制「可执行 SQL」到数据库工具，与预览结果对照。
注意事项
常见报错
| 提示 | 常见原因 |
|---|---|
| 「SQL 里的 ${名} 取不到值——引用报表参数要写成 $名」 | 缺少 $ |
| 「SQL 中第N个 ${...} 表达式看起来在生成动态 SQL 片段……」 | 用 ${} 拼了表名或子句，应用 #{} |
| 「SQL查询结果超过最大行数限制(N行)…」 | 结果行数超过限制，加 WHERE 条件或调大数据集「查询行数限制」 |
| 「SQL查询超时(N秒)…」 | 查询太慢，优化 SQL 或调大「查询超时(秒)」 |
| 「数据库连接失败:」 | 数据连接问题，见 数据源配置 |
| ORDER BY 或 FROM 后面为空 | #{} 多语句正文漏写 return |
注意：开启「输出每条SQL日志」会把查询参数写入日志，可能含患者信息，仅在排查问题时临时开启。
提示：预览成功不等于运行成功：运行时的参数来自查询表单，类型与预览时手填的可能不同，上线前用真实查询表单再测一次。
