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 提供从自然语言(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 参考

读取架构

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

语法:

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()'

行为:立即返回当前架构和状态。始终处于非阻塞状态。如果未计算任何架构,则返回 state:"NotStarted",架构字段为空。如果计算正在进行中,则返回状态为:"InProgress"的部分结果。

响应格式:

响应包含一个包含以下字段的架构对象:

状态对象:

  • state(字符串)-当前生命周期状态:NotStarted、InProgress、Completed、Stopped、Failed

  • concurrency(String)-用于计算的线程数。0 表示 auto(根据硬件确定)。范围:1(最低)到 16(最高)。

  • lastComputedTimestamp(字符串)— 上次成功计算的 ISO-8601 UTC 时间戳(例如)2026-05-29T08:00:00Z

  • progressPercentage(字符串)-计算进度:未启动时为 0,计算期间为 0—99,完成时为 100

  • errorMessage(字符串)-仅在请求被拒绝或计算失败时显示。解释原因。

架构对象:

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

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

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

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

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

支持的数据类型:StringInt、Long、Double、Bool、Date

如果一个属性具有跨不同节点的多种数据类型(例如,有些节点存储为,另一些节点存储age为 IntString),则所有观察到的类型都将在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(最高)。在较小的实例上使用较低的值以减少资源影响。

行为:

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

  • 如果在 state 为时调用Stopped,则计算将从上次停下来的地方恢复。

  • 如果在状态为时调用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()时中断的地方继续进行。

  • 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" \ --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"] } } } } }] }