QueryHub 查询与应用¶
在集成 > 外部数据源中完成 QueryHub 配置并确认生效后，可以在指标分析或仪表板图表中选择该数据源。当前用户需要具有对应的查询权限，可用查询模式以所选实例实际开放的模式为准。
在指标分析中查询¶
- 进入指标 > 指标分析。
- 点击查询区域下方的 + 添加数据源，增加一行数据源查询。
- 在该行的数据源下拉框中，按连接名称选择已配置的 QueryHub 数据源。
- 在数据源右侧选择原生查询或 DQL Like，在输入框中手写对应的查询语句或表达式。
- 点击页面右上角的刷新按钮，在下方查看查询结果，并选择适合结果结构的展示方式。
这里的 + 添加数据源用于添加一行查询。新增或修改连接信息仍在集成 > 外部数据源中操作。
在仪表板图表中查询¶
- 进入场景 > 仪表板，打开目标仪表板。
- 新增图表，或在已有图表的菜单中选择修改，进入图表编辑页。
- 在支持外部数据源的图表查询区域，点击添加数据源，选择已配置的 QueryHub 数据源。
- 选择原生查询或 DQL Like，填写查询内容，查看预览结果。
- 根据结果设置图表的维度、数值等展示项，确认后保存图表。
保存后，图表会保留所选数据源和查询配置；后续刷新仍需满足该数据源的查询权限。图表的通用操作见添加图表。
选择查询方式¶
原生查询¶
选择原生查询后，按数据源类型在输入框中填写 SQL 或完整查询 JSON：
| 数据源 | 原生查询编辑器内容 | 来源与字段查看方式 |
|---|---|---|
| MySQL | SQL 语句，每次一条 | 手动执行 SHOW TABLES、SHOW COLUMNS |
| PostgreSQL | SQL 语句，使用配置的 Schema | 手动查询 information_schema 中的表、列信息 |
| Prometheus | 完整 JSON：operation 为 query 或 query_range，PromQL 放在 statement 中 |
通过限定范围的查询查看当前样本的序列名称和标签 |
| Elasticsearch | 完整 JSON：operation 为 search，请求正文放在 arguments.body 中 |
索引范围看实例配置，字段看命中文档样本；完整 mapping 到数据源侧查看 |
| MongoDB | 完整 JSON：operation 为 find，筛选、投影等参数放在 arguments 中 |
数据库、集合看实例配置，字段看样本文档 |
原生查询和来源、字段查看示例都在上述对应类型的章节中。将示例中的查询对象、字段替换为实际值后填入输入框，再点击右上角刷新。
DQL Like¶
选择 DQL Like 后，在输入框中手写完整的表达式，指定查询对象、返回字段和筛选条件。
- 选中数据源后，切换到 DQL Like。
- 在输入框中填写完整的 DQL Like 表达式。
- 将
source填为对应的数据源类型，将datasource替换为当前选中实例的 ID，再按实际数据修改查询对象、字段和条件。实例 ID 可在集成 > 外部数据源的列表或详情中查看、复制。 - 点击页面右上角刷新，查看结果。
使用排序、聚合或分组时，按 DQL Like 语法编写，并确认查询对象与字段符合所选数据源的要求。
DQL Like 是 QueryHub 的查询语法，与工作空间内查询日志、指标时使用的普通 DQL 不同。表达式中的 source、datasource 必须与页面选中的数据源类型和实例一致。
所有示例均为只读。数据库账号本身也需要具有所查询对象的读取权限。
时间范围如何生效¶
- MySQL、PostgreSQL 等原生查询按语句中的条件执行。需要限定时间时，使用实际时间字段编写过滤条件。
- Prometheus 范围查询通过 JSON 中的
arguments.start、arguments.end引用#{startTime}、#{endTime}，前端自动将图表时间转换为秒；arguments.step也以秒为单位。即时查询与范围查询的结果含义不同。 - DQL Like 查询按表达式中指定的时间条件执行。
Prometheus 范围查询引用上述图表时间变量后，会随页面时间范围变化。MySQL、PostgreSQL 的 SQL 仍需编写相应的时间过滤条件。
查询结果如何展示¶
| 返回内容 | 查看方式 |
|---|---|
| MySQL、PostgreSQL 的普通行列 | 按服务端返回的列、类型和行序展示，可先用表格检查明细 |
| Prometheus 样本 | Studio 表格的“名称”“标签”来自序列的 name、tags；时间列为 time，接口使用 Unix 毫秒，页面格式化显示；数值列名随指标名或表达式变化 |
| Elasticsearch、MongoDB 文档 | 使用表格图，展开 document JSON 查看；JSON 字段保持嵌套，不因投影字段选择而自动成为独立列 |
| 空结果 | 查询可能已成功，但没有匹配记录；检查时间、筛选条件及配置范围 |
| 截断结果 | 只返回了部分数据，按页面提示缩小范围、降低返回量后重试，不当作完整结果统计 |
| 查询失败 | 保留输入并根据脱敏错误修改、重试；中断或未完整结束的返回不当作成功结果 |
展示时保留服务端返回的类型和 NULL 含义，不把 NULL 自动替换为 0，也不把高精度数值随意转成低精度数字。
选择图表时，应先确认结果结构：明细可先用表格查看；趋势图需要可识别的时间和数值；分组统计结果再按实际维度和数值配置展示。可选图表范围以当前查询入口为准。
常见问题¶
找不到实例或无法查询怎么办？¶
确认当前工作空间、配置生效状态及查询权限。
提示实例不匹配怎么办？¶
检查 DQL Like 表达式中的 datasource 和 source，确保它们分别与页面选中的实例 ID、数据源类型一致。切换数据源后，也需要同步修改表达式中的对应值。
为什么看不到表、索引或集合？¶
检查实例配置范围和数据源账号权限。查看来源的查询也受这些限制。
查询返回的文档中没有某个字段怎么办？¶
确认样本文档是否包含该字段，必要时读取有限的更多样本。
查询太慢或结果受限怎么办？¶
缩小查询范围，增加过滤条件，并使用 SQL LIMIT、Elasticsearch size 或 MongoDB limit 控制返回量。