本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
属性图架构
该neptune.graph.pg_schema()过程全面概述了您的属性图结构。它返回所有节点标签、边标签、属性及其数据类型以及标签三元组(描述节点类型如何通过边类型连接的{~from, ~type, ~to}模式)。
此过程目前仅可通过 OpenCypher 端点使用,它会发现所有属性图数据的架构。
使用此过程执行诸如以下的任务:
AI 和 LLM 查询生成 — 为 LLM 提供从自然语言(Text-to-CypherGraphRag 应用程序)生成有效的 Cypher 查询所需的图形结构。
图形可视化和探索 — 像 Graph Explorer 这样的工具使用架构信息来呈现图形数据的交互式可视化表示,而无需扫描整个数据库。
应用程序架构发现 — 启动时需要了解图形结构的应用程序,例如 GraphQL 架构生成器或数据验证工具。
与 Neptune 分析的比较
在 Neptune Analytics 中,neptune.graph.pg_schema()是同步的。它会在每次调用时计算架构。
在 Neptune 数据库中,您可以通过调用来显式触发异步架构计算neptune.graph.pg_schema.compute(),该函数会立即返回。使用neptune.graph.pg_schema()轮询完成时,计算将在后台运行。计算完成后,Neptune 会保留架构,并在后续读取时立即将其返回,无需重新计算。在计算仍在进行时,也可以获得部分结果。您也可以停止正在运行的计算,稍后再恢复。
与图表摘要 API 的比较
图表摘要 API 不提供标签三元组或属性数据类型。属性图架构过程填补了这一空白。标签三元组显示图表中的特定关系模式。例如,a Company 通过worksAt边缘Person连接到。这些信息对于 LLM 生成语义正确的查询至关重要。
先决条件
引擎版本
属性图架构过程需要 Neptune 引擎版本 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 参考
读取架构
检索当前架构和计算状态。
语法:
行为:立即返回当前架构和状态。始终处于非阻塞状态。如果未计算任何架构,则返回 state:"NotStarted",架构字段为空。如果计算正在进行中,则返回状态为:"InProgress"的部分结果。
响应格式:
响应包含一个包含以下字段的架构对象:
状态对象:
state(字符串)-当前生命周期状态:NotStarted、InProgress、Completed、Stopped、Failedconcurrency(String)-用于计算的线程数。0 表示 auto(根据硬件确定)。范围:1(最低)到 16(最高)。lastComputedTimestamp(字符串)— 上次成功计算的 ISO-8601 UTC 时间戳(例如)2026-05-29T08:00:00ZprogressPercentage(字符串)-计算进度:未启动时为 0,计算期间为 0—99,完成时为 100errorMessage(字符串)-仅在请求被拒绝或计算失败时显示。解释原因。
架构对象:
nodeLabels— 图表中所有唯一节点标签的数组edgeLabels— 图表中所有唯一边缘标签的数组nodeLabelDetails— 对于每个节点标签:属性及其数据类型edgeLabelDetails— 对于每个边缘标签:属性及其数据类型labelTriples— 关系模式数组:{~from, ~type, ~to}描述哪些节点类型通过哪些边缘类型连接
支持的数据类型:StringInt、Long、Double、Bool、Date
如果一个属性具有跨不同节点的多种数据类型(例如,有些节点存储为,另一些节点存储age为 IntString),则所有观察到的类型都将在datatypes数组中列出。
计算架构
触发后台架构计算。
语法:
需要的 IAM 操作:neptune-db:ReadDataViaQuery以及 neptune-db:WriteDataViaQuery
参数:
concurrency(整数,可选)-后台计算的线程数。0(默认)= 根据硬件自动确定。范围:1(最低)到 16(最高)。在较小的实例上使用较低的值以减少资源影响。
行为:
立即返回当前状态。计算在后台异步运行。
如果在 state 为时调用
Stopped,则计算将从上次停下来的地方恢复。如果在状态为时调用
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()时中断的地方继续进行。Failed— 计算遇到错误。上次成功计算的架构(如果有)仍然可用。
持久性和重启行为
计算出的架构会被保留下来,并且在引擎重启后仍然存在。重启行为取决于重启时的状态:
InProgress— 如果引擎在计算期间重新启动,则计算将转换为。Stopped打电话从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()。计算从上次停下来的地方继续进行。优雅地处理重启 — 如果在架构计算进行时引擎重新启动,则计算将转换为。
Stopped打电话从compute()上次停下来的地方恢复。进展得以保留。大型数据库-对于存储容量大(多 TB)的数据库,完整的架构计算可能需要更长的时间。你可以启动计算,让它运行直到 10-20% 的进度,然后停止。在此窗口中收集的部分结果提供了一个有用的架构示例,其中包含已发现的许多标签、属性和三元组。在计算进行
pg_schema()中或停止后读取部分架构。如果工作量允许,请稍后恢复。
限制
删除需要重新计算 — 删除的标签、属性和三元组只有在下次完全重新计算后才会从架构中删除。在此之前,已删除的元素可能仍会出现在架构结果中。
OpenCypher 仅限 — 您只能通过 OpenCypher 查询端点调用此过程。
在批量加载期间无法计算 — 当批量加载操作处于活动状态时,Neptune 拒绝架构计算。批量加载完成后触发计算。
示例输出
以下示例显示了航空路线数据集的架构输出:
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"] } } } } }] }