新闻详情

新闻详情

首页 / 资讯中心 / 详情

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

发布时间:2026/11/16 17:48:36来源:尧图网络
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),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/15 4:54:16

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/15 2:04:12

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/14 10:11:15

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/16 6:47:19

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/14 16:35:50

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/16 17:28:18

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉