原生查询

信息

Apache Druid 支持两种查询语言：Druid SQL 和 原生查询。本文档介绍原生查询语言。关于 Druid SQL 在运行 SQL 查询时如何选择使用哪些原生查询类型的信息，请参阅 SQL 文档。

Druid 中的原生查询是 JSON 对象，通常发送给 Broker 或 Router 进程。查询可以这样提交：

curl -X POST '<queryable_host>:<port>/druid/v2/?pretty' -H 'Content-Type:application/json' -H 'Accept:application/json' -d @<query_json_file>

信息

将 <queryable_host>:<port> 替换为您系统相应的地址和端口。例如，如果运行的是快速入门配置，请将 <queryable_host>:<port> 替换为 localhost:8888。

您也可以直接在 Web 控制台的“查询”（Query）视图中输入它们。只需将原生查询粘贴到控制台，编辑器就会自动切换到 JSON 模式。

Druid 的原生查询语言是基于 HTTP 的 JSON，尽管社区成员已经贡献了许多不同语言的 客户端库 来查询 Druid。

Content-Type/Accept 请求头也可以接受 'application/x-jackson-smile'。

curl -X POST '<queryable_host>:<port>/druid/v2/?pretty' -H 'Content-Type:application/json' -H 'Accept:application/x-jackson-smile' -d @<query_json_file>

信息

如果未提供 Accept 请求头，则默认为 'Content-Type' 请求头的值。

Druid 的原生查询相对底层，与内部执行计算的方式紧密对应。Druid 查询旨在轻量级且快速完成。这意味着对于更复杂的分析或构建更复杂的可视化效果，可能需要执行多个 Druid 查询。

尽管查询通常发送给 Broker 或 Router，但它们也可以被 Historical 进程以及运行流式摄取任务的 Peons（任务 JVM） 接受。如果您想针对由特定进程提供服务的特定分片（segments）查询结果，这可能很有价值。

可用查询

Druid 有许多针对不同用例的查询类型。查询由各种 JSON 属性组成，Druid 为不同的用例提供了不同类型的查询。各种查询类型的文档描述了所有可以设置的 JSON 属性。

聚合查询

• Timeseries（时间序列）
• TopN
• GroupBy（分组）

元数据查询

• TimeBoundary（时间边界）
• SegmentMetadata（分片元数据）
• DatasourceMetadata（数据源元数据）

其他查询

• Scan（扫描）
• Search（搜索）

我应该使用哪种查询类型？

对于聚合查询，如果多种类型都能满足您的需求，我们通常建议尽可能使用 Timeseries 或 TopN，因为它们针对各自的用例进行了专门优化。如果两者都不适用，您应该使用 GroupBy 查询，它是最灵活的。

查询取消

可以使用查询的唯一标识符显式取消查询。如果在查询时设置了查询标识符，或者已知该标识符，则可以在 Broker 或 Router 上使用以下端点来取消查询。

DELETE /druid/v2/{queryId}

例如，如果查询 ID 为 abc123，则可以按如下方式取消查询：

curl -X DELETE "http://host:port/druid/v2/abc123"

查询错误

身份验证和授权失败

对于 已启用安全功能 的 Druid 集群，如果身份验证失败，查询请求将返回 HTTP 401 响应代码。如果授权失败，则返回 HTTP 403 响应代码。

查询执行失败

如果查询失败，Druid 将返回一个带有 HTTP 响应代码的响应，以及一个具有以下结构的 JSON 对象：

{
  "error" : "Query timeout",
  "errorMessage" : "Timeout waiting for task.",
  "errorClass" : "java.util.concurrent.TimeoutException",
  "host" : "druid1.example.com:8083"
}

响应中的字段为：

字段	描述
error	明确定义的错误代码（见下文）。
errorMessage	关于错误的更详细的自由格式消息。可能为空。
errorClass	导致此错误的异常类。可能为空。
host	发生此错误的主机。可能为空。

error 字段可能的 Druid 错误代码包括：

错误代码	HTTP 响应代码	描述
SQL parse failed (SQL 解析失败)	400	仅适用于 SQL 查询。SQL 查询解析失败。
Plan validation failed (计划验证失败)	400	仅适用于 SQL 查询。SQL 查询验证失败。
Resource limit exceeded (资源限制超限)	400	查询超出了配置的资源限制（例如 groupBy 的 maxResults）。
Query capacity exceeded (查询容量超限)	429	查询执行失败，原因是提交查询时缺乏可用资源。这些资源可以是任何运行时资源，例如 查询调度程序通道容量、合并缓冲区等。错误消息应包含有关失败的更多详细信息。
Unsupported operation (不支持的操作)	501	查询尝试执行不支持的操作。这可能在使用未记录的功能或使用未完全实现的扩展时发生。
Query timeout (查询超时)	504	查询超时。
Query interrupted (查询被中断)	500	查询被中断，可能是由于 JVM 关闭。
Query cancelled (查询被取消)	500	查询通过查询取消 API 被取消。
Truncated response context (响应上下文被截断)	500	查询的中间响应上下文超过了 7KiB 的内置限制。 响应上下文是 Druid 服务器在相互发送查询结果时用于共享带外（out-of-band）信息的内部数据结构。它序列化在 HTTP 请求头中，最大长度为 7KiB。当数据服务器（如 Historical）发送到 Broker 的中间响应上下文超过此限制时，就会发生此错误。 响应上下文用于多种用途，但最可能生成大上下文的是共享在查询期间移动的分片详细信息。这意味着该错误可能表明在 Broker 发出查询到 Historical 节点处理查询的时间间隔内，有大量分片发生了移动。这在正常操作中极少发生，如果发生，也应非常罕见。
Unknown exception (未知异常)	500	发生了其他异常。请查看 errorMessage 和 errorClass 获取详细信息，但请记住，这些字段的内容是自由格式的，可能会随版本发布而变化。

了解更多

要了解如何使用查询上下文参数，请参阅 设置查询上下文。