HydraDB HTTPS 查询 API 教程：JSON 与 NDJSON 接口完整实战指南

HydraDB HTTPS 查询 API 教程JSON 与 NDJSON 接口完整实战指南【免费下载链接】hydradbHydraDB - fast graph database on object storage项目地址: https://gitcode.com/gh_mirrors/hyd/hydradbHydraDB 是一个构建在对象存储之上的分布式图数据库除了兼容 Neo4j 的 Bolt 协议外还提供开箱即用的HTTPS 查询 API一条curl命令就能执行 OpenCypher 查询结果既可以用JSON一次性返回也可以用NDJSON流式逐行推送。本文带你从零跑通 HydraDB 的 JSON 与 NDJSON 接口覆盖认证、分页、参数化查询、一致性模式和错误处理的全部实战细节。三个端点一张表看懂 API 全貌HydraDB 的 HTTP 查询服务默认监听8443端口整个 API 面只有三个端点全部定义在 src/client/http.rs 的路由注册处端点方法用途/healthzGET健康检查返回{status:ok}/v1/graphs/{graph_id}/queryPOST执行 Cypher 查询JSON 或 NDJSON/v1/graphs/{graph_id}/queries/{query_id}/cancelPOST取消一个进行中的查询 除 8443HTTP 查询外节点还监听7687Bolt 协议和9090管理端口提供/readyz与 Prometheus/metrics。两个关键约定认证所有请求必须携带Authorization: Bearer token请求头否则返回 401。命名空间必须携带X-Graph-Namespace请求头如default未开启默认命名空间时缺失会直接返回 400。快速启动一条 Docker 命令拉起本地节点HTTPS 接口在生产环境默认强制 TLS本地开发需要显式开启明文模式GRAPH_ALLOW_PLAINTEXTtrue。完整步骤见 README.md 的 Getting Started 一节核心命令如下mkdir -p hydradb-data/store hydradb-data/cache printf %s\n local-development-token-32-bytes hydradb-data/auth-token docker run --rm \ --user $(id -u):$(id -g) \ -p 7687:7687 -p 8443:8443 -p 9090:9090 \ -v $PWD/hydradb-data:/data \ -e CLOUD_PROVIDERlocal \ -e LOCAL_PATH/data/store \ -e GRAPH_NAMESPACEdefault \ -e GRAPH_IDdefault \ -e GRAPH_CELL_IDcell-0 \ -e GRAPH_CELLScell-0 \ -e GRAPH_NODE_IDnode-0 \ -e GRAPH_DATA_CACHE_DIR/data/cache \ -e GRAPH_AUTH_TOKEN_FILE/data/auth-token \ -e GRAPH_ALLOW_PLAINTEXTtrue \ -e RUST_MIN_STACK33554432 \ ghcr.io/hydra-db/hydradb:latest节点会在前台持续运行——这是它在工作不是卡死。RUST_MIN_STACK不能省否则节点能响应/readyz但第一条查询就会因栈溢出而中止README.md 的故障排查表专门列了这条。第一个 JSON 查询用 curl 写入并读取图数据端口在监听不等于服务可用一次写读往返才是证明。下面通过 HTTP API 先建一条边再查回来TOKENlocal-development-token-32-bytes # 写入 curl -sS http://127.0.0.1:8443/v1/graphs/default/query \ -H Authorization: Bearer $TOKEN \ -H X-Graph-Namespace: default \ -H Content-Type: application/json \ --data {cell_id:cell-0,query:CREATE (a {id: 1})-[:FOLLOWS]-(b {id: 2})} # 查询 curl -sS http://127.0.0.1:8443/v1/graphs/default/query \ -H Authorization: Bearer $TOKEN \ -H X-Graph-Namespace: default \ -H Content-Type: application/json \ --data {cell_id:cell-0,query:MATCH (a {id: 1})-[:FOLLOWS]-(b) RETURN b.id AS id}第二条命令返回一行{type:vertex_id,value:2}——注意 HydraDB 的 JSON 值都是带类型的vertex_id、integer、float、string、list、path等统一采用{type: ..., value: ...}结构由 src/client/http.rs 中的HttpQueryValue枚举序列化而来。JSON 响应体字段速查字段说明query_id查询 ID可传入自定义值配合 cancel 端点取消查询columns列名数组rows二维数组每个元素是带类型的值read_epoch本次查询固定的存储快照序号是快照一致性读的关键next_cursor非空表示还有更多页把它的值作为下次请求的cursor续取bookmark因果读书签下次请求带上可保证读到不旧于本次的结果NDJSON 流式接口大结果集一行一条边查边读JSON 模式适合小结果集当结果有几十万行时NDJSON每行一条 JSON 记录模式更合适只需把请求头的Accept换成application/x-ndjson服务端就切换为流式响应类型协商逻辑见 src/client/http.rs 的accepts_ndjson。curl -sS http://127.0.0.1:8443/v1/graphs/default/query \ -H Authorization: Bearer $TOKEN \ -H X-Graph-Namespace: default \ -H Accept: application/x-ndjson \ -H Content-Type: application/json \ --data {cell_id:cell-0,query:MATCH (n) RETURN n.id AS id}响应是一连串独立的 JSON 行四种消息类型由type字段区分{type:header,query_id:http-query-1,columns:[id],read_epoch:11} {type:row,values:[{type:integer,value:1}]} {type:row,values:[{type:integer,value:2}]} {type:summary,bookmark:sgk:1:42,has_more:false}它有三个对新手很友好的特性服务端游标自动翻页流内部按页拉取数据客户端不需要手动传cursor首行 header 之后就是连续的行数据单一快照整个流固定在同一存储快照上读行与行之间不会漂移相关测试见 src/client/http/tests.rs错误也走流中途出错时推送一行{type:error,code:...,message:...}再收尾而不是粗暴断开连接。参数化查询、分页与一致性模式参数化在请求体的parameters字段传值查询里用$name引用避免拼字符串注入{ cell_id: cell-0, query: MATCH (a {id: $id})-[:FOLLOWS]-(b) RETURN b.id AS id, parameters: {id: 1}, timeout_ms: 5000, page_size: 100, consistency: causal }完整请求体字段一览字段必填说明cell_id✅目标分片单元 IDquery✅OpenCypher 查询文本query_id⬜自定义查询 ID便于取消parameters⬜查询参数映射bookmark⬜因果读书签保证读到更新的数据timeout_ms⬜查询超时毫秒page_size⬜每页行数默认 256cursor⬜上一页返回的next_cursorconsistency⬜causal默认热路径或strong每次从对象存储刷新一致性怎么选causal使用节点当前持久的读者视图是默认热路径strong会先从对象存储刷新 SlateDB 读者再固定快照付出一次对象存储的新鲜度成本。需要绝对最新的读时才用strong对照 README.md 的 Read Consistency 一节。读懂 HTTP 状态码一张表排查所有常见错误HydraDB 把底层图错误精确映射到语义化状态码实现见 src/client/http.rs 的HttpApiError统一返回{error:{code,message}}信封状态码code含义与处理401unauthenticated缺少或错误的 Bearer token400invalid_request/missing_namespace/invalid_parameter查询语法、参数或命名空间头有误403permission_denied无该图的作用域权限408query_timeout超过timeout_ms或运行时限制加大超时或拆分查询421not_cell_writer写请求打到了非当前写入者节点响应体里附owner提示真正归属节点429resource_exhausted触发准入限流退避重试503routing_unavailable该节点暂时无法路由稍后重试所有响应都带Cache-Control: no-store查询结果不会被中间层缓存。动手验证与延伸阅读想跑一个自动化的 Bolt HTTP 双通道冒烟测试仓库自带 scripts/runtime_smoke.sh成功时输出runtime-smoke-ok查询语义细节OpenCypher 子集、路径过程见 cypher-compat.md端到端架构快照、写入者租约、索引生命周期见 architecture.mdKubernetes 部署与 TLS、认证配置参考 charts/hydradb/README.md。 小结记住8443 端口 Bearer 认证 X-Graph-Namespace三件套你就能用 JSON 模式做交互式查询用 NDJSON 模式扛住大结果集——这正是 HydraDB 作为对象存储原生图数据库给应用侧提供的最轻量集成路径。【免费下载链接】hydradbHydraDB - fast graph database on object storage项目地址: https://gitcode.com/gh_mirrors/hyd/hydradb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考