DataWave REST API参考手册：query、plan、lookup、predict等核心接口使用指南

DataWave REST API参考手册：query、plan、lookup、predict等核心接口使用指南

【免费下载链接】datawaveDataWave is an ingest/query framework that leverages Apache Accumulo to provide fast, secure data access.项目地址: https://gitcode.com/gh_mirrors/da/datawave

DataWave 是基于 Apache Accumulo 的开源数据摄取与查询框架，它的 Web 服务通过一套简洁的 REST API 暴露了强大的查询能力。本指南将带你快速掌握 DataWave REST API 中最常用的核心接口——query（创建分页查询）、plan（查询计划预览）、lookup（原始数据回溯）和 predict（查询预测），帮助新手在 10 分钟内跑通第一个查询。

📌 先了解 DataWave 是什么

DataWave 将海量事件数据高效写入 Apache Accumulo，并提供一套完整的 REST 查询接口。你可以把它理解为一个"带安全属性的搜索引擎"：查询时不仅要写查询语法，还要声明你的权限（auths），系统会自动根据安全标签过滤结果。

它的 REST 服务整体架构位于 web-services/ 模块下，查询执行的核心逻辑在 BasicQueryBean.java 和 QueryExecutorBean.java 中实现，微服务版的查询接口定义则见 Query.java。

🧩 核心接口全景速览

项目内置了一套可直接运行的调用脚本，位于 docker/scripts/ 目录，例如 query.sh、plan.sh、lookup.sh、predict.sh，配合公共函数 common/query.sh 演示了标准的调用流程。

🔍 query 接口：创建查询并分页拉取

query 是 DataWave 使用频率最高的接口，采用"先创建、后翻页"的两步式模式：

第一步：创建查询（POST/{queryLogic}/create）

核心参数包括：

• query：查询语句（默认支持 LUCENE 语法，通过query.syntax指定）
• begin/end：时间范围，格式如19660908 000000.000
• columnVisibility与auths：安全属性声明
• pagesize：每页返回条数
• systemFrom/queryName：调用来源与查询名称（用于审计）

第二步：分页获取（GET/{queryId}/next）

创建成功后响应中会返回一个queryId，之后每次调用next接口获取下一页，直到查询结束自动销毁。官方脚本中的标准调用方式可以这样理解：

携带 mTLS 证书（-E ${TMP_PEM}）向/EventQuery/create提交参数 → 解析createResponse.xml拿到 queryId → 循环调用/{queryId}/next直到返回非 200 状态码。

完整流程可参考 common/query.sh 中的runQuery函数。

📊 plan 接口：查询前的"成本预估"

在大数据场景下，直接执行一个代价高昂的查询可能拖垮系统。plan 接口允许你只查看执行计划而不真正执行，响应中会列出查询要扫描的索引、预估代价等信息。它最适合在以下场景使用：

• 上线新查询前验证语法是否正确
• 排查某个查询为什么慢
• 确认查询会命中哪些字段索引

调用脚本见 docker/scripts/plan.sh。

🔎 lookup 接口：回溯命中的原始数据

query 返回的是索引层面的结果，如果你需要看到原始记录内容，就用 lookup 接口。它支持按 UID、UUID 等条件回溯，例如按 UUID 查询、获取下一条内容（next）等变体，相关工具类位于 AbstractUUIDLookupCriteria.java 等文件中。

典型用法：query 命中的某条记录 → 用其 UUID 调用 lookup → 获取该事件的全部原始字段。

🔮 predict 接口：预测查询命中范围

predict 接口与 plan 类似，但它聚焦于预测结果集：不返回数据本身，而是告诉你这个查询"会匹配到什么"。对于新手来说，它是调试查询的利器——当你不确定一个 Lucene 查询是否会命中数据时，先 predict 一下，能帮你快速定位是语法问题、索引缺失还是权限不足。

调用示例见 docker/scripts/predict.sh。

🚀 快速上手：三步跑通第一个查询

1. 准备环境：项目提供 Docker Compose 一键栈，配置文件在 docker/docker-compose.yml，启动后服务会生成 mTLS 证书（PKI 材料见 docker/pki/）。
2. 复制脚本改参数：打开 docker/scripts/query.sh，修改QUERY（如GENRES:[Action to Western]）、时间范围BEGIN/END和权限AUTHS。
3. 执行并翻页：脚本会依次调用 create 和 next 接口，把每页响应保存为nextResponse_1.xml等文件，方便你检查 JSON/XML 返回结构。

⚠️ 注意：DataWave 的 REST API 默认启用mTLS 双向认证，curl 调用时务必带上-k -E client.pem之类的客户端证书参数。

📚 更多接口与进阶玩法

• 统计类：count.sh（命中计数）、hitHighlights.sh（命中摘要）、termFrequency.sh（词频统计）
• 图分析：edge.sh 调用 edge 接口做实体关系挖掘
• 异步/批量：streamingQuery.sh（流式查询）、mapReduceQuery.sh（MapReduce 分布式查询，服务实现见 mapreduce-query/）、cachedResultsQuery.sh（缓存结果复用）
• Web 查询界面：浏览器端交互入口由 query-websocket/ 提供

🗂️ 相关资源导航

小结：掌握 query（检索）+ plan（预览）+ predict（预测）+ lookup（回溯）这四大核心接口，就覆盖了 DataWave REST API 90% 的日常使用场景。建议从 docker/scripts/ 目录下的示例脚本入手，它们是最直观的"活文档"。

【免费下载链接】datawaveDataWave is an ingest/query framework that leverages Apache Accumulo to provide fast, secure data access.项目地址: https://gitcode.com/gh_mirrors/da/datawave