查询模板与动态参数

核心概念：报表管理 | 查询模板与动态参数 | 概览

先在主后台调试明文查询，再通过“报表查询加解密”生成密文，最后交给 GoView 使用。GoView 不接受明文 SQL、DSL 或 Redis 命令，也不会自动把明文转换成密文。

示例中的表、索引、字段和 Key 均需按实际数据替换；常量查询可用于先检查基本查询通路。

语法参考：官方查询手册与版本说明（TDengine 3.3.8、MySQL 8.0、Redis 6.x、ES 7.17.6）。ES 的 _MAP、分组统计、日期条件和模式差异，详见 Calcite SQL 与原生 DSL 详解。

---

核心概念：报表管理 | 查询模板与动态参数 | 明文查询调试

明文查询调试

1. 打开“报表数据源配置管理”，在对应行点击“查询数据”。
2. 核对数据源名称、类型、编号和配置版本。
3. 填写 SQL、ES DSL 或 Redis 只读命令。ES 需先选择“Calcite SQL”或“原生 DSL”；只有 DSL 填写固定索引/别名。
4. 查询包含占位符时添加参数定义，在“动态参数”中填写本次值；无参数填 []。
5. 点击“执行只读查询”，检查列名、数据和查询条件是否符合预期。

图中使用以下 MySQL 常量查询，不读取业务表，可作为柱状图数据示例：

SELECT 'probe' AS product, 7 AS data1, 3 AS data2

预期返回一行：product 为 probe，data1 为 7，data2 为 3。参数定义留空，动态参数填写 []。

“执行只读查询”会真实访问数据库。“取消等待”只取消前端等待，不保证数据库已立即终止执行。关闭弹窗或离页后会清除当前明文、参数和结果；请在离页前按工作需要将已确认的模板转入加解密页面。

---

核心概念：报表管理 | 查询模板与动态参数 | 按数据源编写查询

按数据源编写查询

MySQL 与 TDengine

官方参考：MySQL 8.0 SELECT、TDengine 3.3.8 数据查询（中文）。数据库完整语法与本系统开放范围有区别，使用扩展语法前先调试。

先使用无参数的最小查询：

SELECT 1 AS probe

带数字参数时使用值占位符：

SELECT :value AS probe

点击“添加参数”，定义 value / LONG / CLIENT / 必填，动态参数填写：

[{"name":"value","value":7}]

:value 不加引号，不写成 ':value'。参数只能代替值，不能代替表名、列名或整段条件。TDengine 使用已配置的 REST 连接，不在查询中填写 JDBC URL。

ES：Calcite SQL

参考 Calcite 官方 SQL 手册及本站中文详解。当前源码依赖 Calcite 1.39.0；它与 ES 7.17.6 的兼容边界见版本说明。

选择“Calcite SQL”，不填写 DSL 索引字段。以下示例要求存在 base_device 索引及 status 字段：

select _MAP['status'] as status, count(*) as `count`
from es.base_device
where _MAP['status'] in (0, 1)
group by _MAP['status']
order by _MAP['status']

需要动态状态条件时：

select count(*) as `count`
from es.base_device
where _MAP['status'] = :status

定义 status / LONG / CLIENT / 必填，动态参数填写：

[{"name":"status","value":1}]

该模式由服务端将 SQL 转成 ES 查询，不支持所有 MySQL 语法。提示语法不支持时应调整模板。

ES：原生 DSL

官方参考：Elasticsearch 7.17 Query DSL。当前系统开放的查询、聚合及限制见原生 DSL 对照。

选择“原生 DSL”，固定索引/别名填写实际索引，例如 base_device。不能填写 URL、请求路径或通配符。

{
  "size": 1,
  "query": {"match_all": {}}
}

参数化条件示例：

{
  "size": 1,
  "query": {"term": {"status": "${status}"}}
}

仍定义 status / LONG / CLIENT / 必填，动态参数使用上例的 name/value 数组。${status} 必须占据完整 JSON 值节点，服务端按 LONG 绑定数字；不能把参数嵌入 JSON 结构或拼成字符串片段。

Redis：已知 Key 的只读命令

官方参考：命令索引。该站持续更新，Redis 6.0 与 6.2 的可用参数有差别，使用前查看Redis 版本说明。

先确认实际 DB、已知 Key 及其数据类型。读取字符串示例：

GET report:summary

动态 Key 示例：

GET ${key}

定义 key / STRING / CLIENT / 必填，固定 Key 前缀填写 report:。动态参数填写：

[{"name":"key","value":"report:summary"}]

Key 必须在定义的固定前缀内；Key 不存在可能返回空值。参数不能作为命令名；不开放 SET、DEL、FLUSH、SELECT、KEYS、SCAN 或脚本执行。

---

核心概念：报表管理 | 查询模板与动态参数 | 参数定义规则

参数定义规则

参数定义随模板一起生成密文；动态参数是每次查询的实际值。只改 CLIENT 参数值无需重新生成密文；修改模板、参数名、类型、来源或限制后必须重新生成。

设置	规则
参数名	字母开头，仅包含字母、数字、下划线，最长 64 字符，名称唯一
参数数量	最多 50 个
参数类型	STRING、LONG、DECIMAL、BOOLEAN、DATE、DATETIME
CLIENT	由调用者提供值，可设置必填、默认值及允许的限制
SERVER_TENANT	取当前租户编号，类型 LONG，不在 GoView 中传值
SERVER_USER	取当前用户编号，类型 LONG，不在 GoView 中传值
SERVER_DATE	由服务端计算日期，支持 STRING、DATE、DATETIME
SQL 占位符	:name，只用于值位置
ES DSL 占位符	完整 ${name} JSON 值节点
Redis 占位符	独立 ${name} 参数，不作片段拼接

动态参数必须为 name/value 数组，值只允许字符串、数字、布尔或 null，不允许对象、数组或 JavaScript。只传 CLIENT 参数，不传服务器参数。

DATE 使用 yyyy-MM-dd，DATETIME 使用 yyyy-MM-dd'T'HH:mm:ss。数字须避免超出浏览器可精确表示的范围；null 不会绕过必填或类型限制。

日期值示例分别为 2026-09-19、2026-09-19T23:33:01。如果用 GoView 时间选择器传值，必须选用匹配的输出格式：默认毫秒时间戳不会自动转换成 DATETIME，带空格的日期时间通常用 STRING。控件自定义格式使用大写 YYYY 等 Day.js 标记，与本页服务器日期格式的 Java 写法不同。

用户自选时间范围应定义两个 CLIENT 参数；完整模板、参数值和控件绑定步骤见日期控件与时间范围筛选。

---

核心概念：报表管理 | 查询模板与动态参数 | 服务器日期参数

服务器日期参数

日期随时间自动变化的报表，优先使用 SERVER_DATE，无需每天手动修改 GoView 参数。先选值来源 SERVER_DATE，再选所需类型、偏移、单位、时区和格式。

SERVER_DATE 适用于固定相对范围，例如始终查询今天或本月；如果需要发布后的查看人员自由选择日期，改用 CLIENT 参数和时间选择器联动。控件的“动态默认值”只负责给选择器设置初始日期，不等同于每次查询重新计算的 SERVER_DATE。

等于今天零点

以下条件表示时间恰好等于今天零点，不是查询当天全部记录：

select count(*) as `count` from es.base_device
where _MAP['status'] = 1 and _MAP['activation_time'] = :todayStart

定义 todayStart / STRING / SERVER_DATE / 必填，NOW 偏移为 0，单位 DAYS，时区 Asia/Shanghai，格式选“当天零点（00:00:00）”。动态参数填写 []。

查询本月

使用“本月起点包含、下月起点不包含”的范围：

select count(*) as `count` from es.base_device
where _MAP['status'] = 1
  and _MAP['activation_time'] >= :monthStart
  and _MAP['activation_time'] < :nextMonthStart

两个参数均为 STRING / SERVER_DATE / 必填，时区 Asia/Shanghai：

参数名	NOW 偏移	单位	格式
monthStart	0	MONTHS	月初零点（1 日 00:00:00）
nextMonthStart	1	MONTHS	月初零点（1 日 00:00:00）

动态参数填写 []。实际字段的日期存储格式需与条件匹配。偏移单位支持 DAYS、HOURS、MINUTES、MONTHS、YEARS，同次查询的服务器日期参数使用同一基准时刻。

兼容已有 ES 日期宏

已有 ES SQL 模板可保留以下字符串值写法：

select count(*) as `count` from es.base_device
where _MAP['status'] = 1
  and _MAP['activation_time'] = '$date_format(now, null, 0, d, yyyy-MM-dd) 00:00:00'

select count(*) as `count` from es.base_device
where _MAP['status'] = 1
  and _MAP['activation_time'] >= '$date_format(now, null, 0, d, yyyy-MM)-01 00:00:00'
  and _MAP['activation_time'] < '$date_format(now, null, 1, M, yyyy-MM)-01 00:00:00'

这两例参数定义留空、动态参数填 []。大写 M 表示月，小写 m 表示分钟；旧 now 使用服务器默认时区。该兼容写法仅用于 ES SQL 受控值位置，新模板优先使用明确时区的 SERVER_DATE。

---

核心概念：报表管理 | 查询模板与动态参数 | 生成查询密文

生成查询密文

操作入口：报表管理 → 报表查询加解密。

1. 选择刚刚调试成功的数据源。
2. ES 选择相同的查询模式；原生 DSL 同时填写相同的固定索引/别名。
3. 在“明文模板”中粘贴已验证的 SQL、DSL 或 Redis 命令。
4. 按调试时的设置填写参数定义。此页不填写 CLIENT 参数的本次动态值。
5. 点击“服务端加密”，获得 RQ2. 开头的查询密文。
6. 复制完整密文，在 GoView 数据配置中粘贴。

图中未展示有效密文；实际使用时必须复制完整生成结果，不添加引号或代码围栏。加密仅校验模板和规则，不执行数据库查询；不能用加密成功代替明文调试。

时间范围模板的加密配置

图中 startTime、endTime 均声明为 DATETIME / CLIENT / 必填，模板中的占位符不加引号。示例表 example_order 需替换为实际表；截图展示加密前的填写方式，未执行该查询或生成有效密文。完整的日期筛选步骤见准备范围查询。

完成后点击“清空本页内容”或离页。不要把数据库密码、明文模板放入 GoView 项目或参数中。

---

核心概念：报表管理 | 查询模板与动态参数 | 解密与修改模板

解密与修改模板

加密配置区下方是解密入口。图中密文留空；实际使用时粘贴完整 RQ2. 密文，不把明文模板填入“待解密密文”。

1. 选择原数据源，在“待解密密文”中粘贴完整密文。
2. 点击“服务端解密到上方模板”，核对恢复的明文与参数定义。
3. 若原源停用、不在下拉中，可在“恢复旧源编号”填写原数据源 ID。该字段只用于解密恢复。
4. 根据需要修改模板，在数据源管理页调试修改后的查询。
5. 选择实际使用的数据源重新加密，将新密文替换到相关控件或公共数据池，并保存项目。

“绑定有效”说明当前绑定检查通过，不代表数据库执行成功。提示连接身份变化、数据源停用或 ES 模式/索引不一致时，应先核对配置再重新生成密文。

加密与解密权限独立；只有加密按钮不代表可以解密已有模板。