本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
属性图架构
这个 neptune.graph.pg_schema() 过程全面概述了您的属性图结构。它返回所有节点标签、边缘标签、属性及其数据类型以及标签三元组({~from, ~type, ~to} 描述节点类型如何通过边缘类型连接的模式)。
此过程目前仅可通过 OpenCypher 端点使用,可发现所有属性图数据的架构。
使用此过程执行以下任务:
AI 和 LLM 查询生成 — 为 LLM 提供从自然语言生成有效的 Cypher 查询所需的图形结构 (Text-to-Cypher,GraphRag 应用程序)。
图形可视化和探索 — 诸如此类的工具 图表浏览器 使用架构信息来呈现图形数据的交互式可视化表示,而无需扫描整个数据库。
应用程序架构发现 — 启动时需要了解图形结构的应用程序,例如 GraphQL 架构生成器或数据验证工具。
与海王星分析的比较
在海王星分析中, neptune.graph.pg_schema() 是同步的。它在每次调用时计算架构。
在 Neptune 数据库中,您可以通过调用显式触发异步架构计算 neptune.graph.pg_schema.compute(),它会立即返回。当您使用轮询完成情况时,计算在后台运行 neptune.graph.pg_schema()。计算完成后,Neptune 会保留该架构,并在后续读取时立即将其返回,无需重新计算。在计算仍在进行时,也可以获得部分结果。您也可以停止正在运行的计算,稍后再恢复。
与图表摘要 API 的比较
这个 图表摘要 API 不提供标签三元组或属性数据类型。属性图架构过程填补了这一空白。标签三元组显示图表中的特定关系模式。例如,一个 Person 连接到 Company 通过 worksAt 边缘。这些信息对于 LLM 生成语义正确的查询至关重要。
先决条件
引擎版本
属性图架构过程需要海王星引擎版本 1.4.8.0 或更高版本。
IAM 权限
每个架构操作都需要以下 IAM 操作:
CALL neptune.graph.pg_schema()— 需要neptune-db:ReadDataViaQuery。CALL neptune.graph.pg_schema.compute()— 需要neptune-db:ReadDataViaQuery和neptune-db:WriteDataViaQuery。CALL neptune.graph.pg_schema.stop()— 需要neptune-db:ReadDataViaQuery和neptune-db:WriteDataViaQuery。
这个 compute() 和 stop() 操作需要写入权限,因为它们会修改用于缓存和保存架构的内部状态。
例示例 IAM 策略
以下策略授予所有架构操作所需的最低权限:
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "neptune-db:ReadDataViaQuery", "neptune-db:WriteDataViaQuery" ], "Resource": "arn:aws:neptune-db:us-east-1:123456789012:cluster-resource-id/*" }] }
要授予对架构的只读访问权限(无法触发计算),请仅使用 neptune-db:ReadDataViaQuery。
作者和读者实例
您只能在编写器实例上触发架构计算。只读副本实例可以读取架构(从写入器复制)但无法运行 compute() 要么 stop()。
API 参考
读取架构
检索当前架构和计算状态。
语法:
行为: 立即返回当前架构和状态。始终保持非阻塞状态。如果尚未计算出任何架构,则返回状态: "NotStarted" 带有空的架构字段。如果计算正在进行中,则返回带有状态的部分结果: "InProgress"。
响应格式:
响应包含具有以下字段的架构对象:
状态对象:
state(字符串)-当前生命周期状态:NotStarted,InProgress,Completed,Stopped,Failed。从海王星引擎版本 1.5.0.0 开始,中断的计算也可以报告Paused。有关更多信息,请参阅 国家。concurrency(字符串)-用于计算的线程数。0 表示自动(根据硬件确定)。范围:1(最低)到 16(最高)。lastComputedTimestamp(字符串)— ISO-8601 上次成功计算的 UTC 时间戳(例如2026-05-29T08:00:00Z)progressPercentage(字符串)— 计算进度:未开始时为 0,计算期间为 0—99,完成时为 100errorMessage(字符串)-请求被拒绝或计算的原因是Paused要么Failed。例如,重启或故障转移中断了计算,或者计算失败。
架构对象:
nodeLabels— 图表中所有唯一节点标签的数组edgeLabels— 图表中所有唯一边缘标签的数组nodeLabelDetails— 对于每个节点标签:属性及其数据类型edgeLabelDetails— 对于每个边缘标签:属性及其数据类型labelTriples— 关系模式数组:{~from, ~type, ~to}描述哪些节点类型通过哪些边缘类型进行连接
支持的数据类型: String, Int, Long, Double, Bool, Date
如果一个属性在不同的节点上有多种数据类型(例如,某些节点存储 age 如同 Int 以及其他人如 String),所有观测到的类型都列在 datatypes 数组。
计算架构
触发后台架构计算。
语法:
所需的 IAM 操作: neptune-db:ReadDataViaQuery 和 neptune-db:WriteDataViaQuery
参数:
concurrency(整数,可选)-用于后台计算的线程数。0(默认)= 根据硬件自动确定。范围:1(最低)到 16(最高)。在较小的实例上使用较低的值以减少资源影响。
行为:
立即以当前状态返回。计算在后台异步运行。
如果在状态为时调用
Stopped要么Paused,计算从中断的地方恢复。有关这些状态的详细信息,请参见 国家。如果在状态为时调用
Completed,开始新的重新计算。先前的架构继续提供读取服务,直到新的计算完成。如果在计算已经完成时调用
InProgress,Neptune 使用错误消息拒绝了该请求。如果在主动批量加载期间调用,Neptune 会拒绝该请求,并显示错误消息。
回应: 返回显示状态的状态对象: "InProgress" 和 concurrency 和 progressPercentage 字段。
停止架构计算
停止正在运行的后台计算。
语法:
所需的 IAM 操作: neptune-db:ReadDataViaQuery 和 neptune-db:WriteDataViaQuery
行为:
停止正在运行的计算。进度已保存,因此可以从通话时中断的地方恢复
compute()再次。停止计算确实如此 不 引擎重启时自动恢复。你必须明确地调用
compute()。
回应: 返回显示状态的状态对象: "Stopped" 用电流 progressPercentage。
将 YIELD 与架构结果一起使用
你可以使用 YIELD 提取架构字段并将其与其他查询相结合。以下示例检索所有节点标签并计算每个标签的节点数。这个 collSort() 函数按字母顺序对列表进行排序:
CALL neptune.graph.pg_schema() YIELD schema WITH schema.nodeLabels as nl UNWIND collSort(nl) as label MATCH (n) WHERE label in labels(n) RETURN label, COUNT(n) as count
示例输出:
{ "results": [{ "label": "airport", "count": 3503 }, { "label": "continent", "count": 7 }, { "label": "country", "count": 237 }, { "label": "version", "count": 1 }] }
架构计算生命周期
异步操作
架构计算是一种异步操作。当你打电话时 neptune.graph.pg_schema.compute(),它会立即以当前状态返回。计算在后台运行。你可以通过致电来投票了解进度和完成情况 neptune.graph.pg_schema(),它返回当前状态和 progressPercentage。
状态
架构计算会经历以下状态:
NotStarted— 尚未计算出任何架构。pg_schema()返回空架构。InProgress— 正在运行后台计算。pg_schema()返回部分结果(最后一个完整架构和当前计算发现的并集)。Completed— 计算成功完成。完整架构可用。Stopped— 计算因显式调用而停止stop()。部分结果可用。进度已保存,因此计算可以从你调用时中断的地方恢复compute()。停止的计算不带有errorMessage。Paused— 从 Neptune 引擎版本 1.5.0.0 开始,引擎重启或故障转移过渡为InProgress计算到Paused而不是Stopped。部分结果可用,计算会保存进度。要从上次停下来的地方继续,请致电compute()。恢复计算将返回到InProgress然后Completed。Failed— 计算遇到错误。最后成功计算的架构(如果有)仍然可用。状态对象包括errorMessage解释失败。
持久化和重启行为
计算出的架构会被保留,并且在引擎重启后仍能生存。重启行为取决于重启时的状态:
InProgress— 如果引擎在计算期间重新启动或发生故障,则计算中断。从海王星引擎版本 1.5.0.0 开始,计算过渡到Paused; 在早期版本中,它过渡到Stopped。打电话compute()从上次停下来的地方恢复。计算会保留进度,并从最后一个检查点开始继续计算。Paused— 计算确实如此 不 自动恢复。你必须打电话compute()从上次停下来的地方继续。Stopped— 计算确实如此 不 自动恢复。你必须打电话compute()从上次停下来的地方继续。Completed— 架构已加载并立即可用。
部分结果
在计算过程中, pg_schema() 返回部分结果。其中包括任何先前完成的架构与迄今为止在当前计算中发现的标签、属性和三元组合并。这意味着在检索有用的架构信息之前,您不必等待完整计算完成。
只读副本
只读副本实例可以使用读取架构 CALL neptune.graph.pg_schema()。Neptune 从编写器实例中复制架构,并在编写器上发现架构元素后几乎立即使其在副本上可用。
只读副本无法运行 compute() 要么 stop()。这些调用会返回错误:
compute()–"Schema cannot be computed on read replica"stop()–"Schema compute cannot be stopped on read replica"
最佳实践
突变后重新计算 — 数据更改时,架构不会自动更新。在批量加载或重大数据突变后重新计算架构。使用
lastComputedTimestamp字段来确定该架构相对于图表中的最近更改是否已过时。并发性 — 默认并发值 (0) 会自动适应您的实例硬件。对于大多数工作负载,这是推荐的设置。如果后台计算影响您的查询工作负载,请指定较低的值(例如 1 或 2)以减少资源使用量。
停止并恢复 — 如果后台计算影响您的查询工作负载,请使用以下命令停止
stop()然后在流量较低的时段通过致电恢复compute()再次。计算从中断的地方继续进行。手柄正常重启 — 如果在架构计算过程中引擎重新启动或发生故障,则计算会中断。从海王星引擎版本 1.5.0.0 开始,它过渡到
Paused。打电话compute()从上次停下来的地方恢复。进度得以保留。大型数据库 — 对于存储容量大(多 TB)的数据库,完整的架构计算可能需要更长的时间。你可以启动计算,让它运行直到 10-20% 的进度,然后停止。在此窗口中收集的部分结果提供了一个有用的架构示例,其中包含已发现的许多标签、属性和三元组。使用以下方式读取部分架构
pg_schema()计算正在进行时或停止之后。待工作量允许时稍后恢复。
限制
删除需要重新计算 — 删除的标签、属性和三元组仅在下次全面重新计算后才会从架构中移除。在此之前,已删除的元素可能仍会出现在架构结果中。
OpenCypher 只有 — 您只能通过 OpenCypher 查询端点调用此过程。
批量加载期间无法计算 — 当批量加载操作处于活动状态时,海王星拒绝架构计算。批量加载完成后触发计算。
示例输出
以下示例显示了空中路线数据集的架构输出:
awscurl -X POST https://your-neptune-endpoint:port/openCypher \ -H "Content-Type: application/x-www-form-urlencoded" \ --regionus-east-1--service neptune-db \ -d 'query=CALL neptune.graph.pg_schema()'
{ "results": [{ "schema": { "edgeLabelDetails": { "route": { "properties": { "dist": ["Int"] } }, "contains": { "properties": {} } }, "edgeLabels": ["route", "contains"], "status": { "concurrency": "16", "lastComputedTimestamp": "2026-06-04T23:58:17Z", "state": "Completed", "progressPercentage": "100" }, "nodeLabels": ["version", "continent", "airport", "country"], "labelTriples": [{ "~type": "route", "~from": "airport", "~to": "airport" }, { "~type": "contains", "~from": "country", "~to": "airport" }, { "~type": "contains", "~from": "continent", "~to": "airport" }], "nodeLabelDetails": { "continent": { "properties": { "type": ["String"], "code": ["String"], "desc": ["String"] } }, "airport": { "properties": { "type": ["String"], "city": ["String"], "icao": ["String"], "code": ["String"], "country": ["String"], "lat": ["Double"], "longest": ["Int"], "runways": ["Int"], "desc": ["String"], "lon": ["Double"], "region": ["String"], "elev": ["Int"] } }, "country": { "properties": { "type": ["String"], "code": ["String"], "desc": ["String"] } }, "version": { "properties": { "date": ["String"], "desc": ["String"], "author": ["String"], "type": ["String"], "code": ["String"] } } } } }] }