View a markdown version of this page

属性图架构 - Amazon Neptune
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

属性图架构

这个 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 参考

读取架构

检索当前架构和计算状态。

语法:

Amazon CLI
aws neptunedata execute-open-cypher-query \ --endpoint-url https://your-neptune-endpoint:port \ --open-cypher-query "CALL neptune.graph.pg_schema()"
SDK
import boto3 from botocore.config import Config client = boto3.client( 'neptunedata', endpoint_url='https://your-neptune-endpoint:port', config=Config(read_timeout=None, retries={'total_max_attempts': 1}) ) response = client.execute_open_cypher_query( openCypherQuery='CALL neptune.graph.pg_schema()' ) print(response)
awscurl
awscurl -X POST https://your-neptune-endpoint:port/openCypher \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 --service neptune-db \ -d 'query=CALL neptune.graph.pg_schema()'

行为: 立即返回当前架构和状态。始终保持非阻塞状态。如果尚未计算出任何架构,则返回状态: "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,完成时为 100

  • errorMessage (字符串)-请求被拒绝或计算的原因是 Paused 要么 Failed。例如,重启或故障转移中断了计算,或者计算失败。

架构对象:

  • nodeLabels — 图表中所有唯一节点标签的数组

  • edgeLabels — 图表中所有唯一边缘标签的数组

  • nodeLabelDetails — 对于每个节点标签:属性及其数据类型

  • edgeLabelDetails — 对于每个边缘标签:属性及其数据类型

  • labelTriples — 关系模式数组: {~from, ~type, ~to} 描述哪些节点类型通过哪些边缘类型进行连接

支持的数据类型: String, Int, Long, Double, Bool, Date

如果一个属性在不同的节点上有多种数据类型(例如,某些节点存储 age 如同 Int 以及其他人如 String),所有观测到的类型都列在 datatypes 数组。

计算架构

触发后台架构计算。

语法:

Amazon CLI
aws neptunedata execute-open-cypher-query \ --endpoint-url https://your-neptune-endpoint:port \ --open-cypher-query "CALL neptune.graph.pg_schema.compute()"

使用可选的并发参数:

aws neptunedata execute-open-cypher-query \ --endpoint-url https://your-neptune-endpoint:port \ --open-cypher-query "CALL neptune.graph.pg_schema.compute({concurrency: 2})"
SDK
import boto3 from botocore.config import Config client = boto3.client( 'neptunedata', endpoint_url='https://your-neptune-endpoint:port', config=Config(read_timeout=None, retries={'total_max_attempts': 1}) ) response = client.execute_open_cypher_query( openCypherQuery='CALL neptune.graph.pg_schema.compute()' ) print(response)
awscurl
awscurl -X POST https://your-neptune-endpoint:port/openCypher \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 --service neptune-db \ -d 'query=CALL neptune.graph.pg_schema.compute()'

使用可选的并发参数:

awscurl -X POST https://your-neptune-endpoint:port/openCypher \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 --service neptune-db \ -d 'query=CALL neptune.graph.pg_schema.compute({concurrency: 2})'

所需的 IAM 操作: neptune-db:ReadDataViaQuery 和 neptune-db:WriteDataViaQuery

参数:

  • concurrency (整数,可选)-用于后台计算的线程数。0(默认)= 根据硬件自动确定。范围:1(最低)到 16(最高)。在较小的实例上使用较低的值以减少资源影响。

行为:

  • 立即以当前状态返回。计算在后台异步运行。

  • 如果在状态为时调用 Stopped 要么 Paused,计算从中断的地方恢复。有关这些状态的详细信息,请参见 国家。

  • 如果在状态为时调用 Completed,开始新的重新计算。先前的架构继续提供读取服务,直到新的计算完成。

  • 如果在计算已经完成时调用 InProgress,Neptune 使用错误消息拒绝了该请求。

  • 如果在主动批量加载期间调用,Neptune 会拒绝该请求,并显示错误消息。

回应: 返回显示状态的状态对象: "InProgress" 和 concurrency 和 progressPercentage 字段。

停止架构计算

停止正在运行的后台计算。

语法:

Amazon CLI
aws neptunedata execute-open-cypher-query \ --endpoint-url https://your-neptune-endpoint:port \ --open-cypher-query "CALL neptune.graph.pg_schema.stop()"
SDK
import boto3 from botocore.config import Config client = boto3.client( 'neptunedata', endpoint_url='https://your-neptune-endpoint:port', config=Config(read_timeout=None, retries={'total_max_attempts': 1}) ) response = client.execute_open_cypher_query( openCypherQuery='CALL neptune.graph.pg_schema.stop()' ) print(response)
awscurl
awscurl -X POST https://your-neptune-endpoint:port/openCypher \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 --service neptune-db \ -d 'query=CALL neptune.graph.pg_schema.stop()'

所需的 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" \ --region us-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"] } } } } }] }