本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 属性图架构 该`neptune.graph.pg_schema()`过程全面概述了您的属性图结构。它返回所有节点标签、边缘标签、属性及其数据类型以及标签三元组（描述节点类型如何通过边缘类型连接的`{~from, ~type, ~to}`模式）。 此过程目前仅可通过 OpenCypher 端点使用，可发现所有属性图数据的架构。 使用此过程执行以下任务： + **AI 和 LLM 查询生成 ** — 为 LLM 提供从自然语言（Text-to-CypherGraphRag 应用程序）生成有效的 Cypher 查询所需的图形结构。 + **图表可视化和探索 ** — [ Graph Explorer 等工具](visualization-graph-explorer.md)使用架构信息来呈现图形数据的交互式可视化表示，而无需扫描整个数据库。 + **应用程序架构发现 ** — 启动时需要了解图形结构的应用程序，例如 GraphQL 架构生成器或数据验证工具。 ## 与海王星分析的比较 在 Neptune Analytics 中，[`neptune.graph.pg_schema()`](https://docs.amazonaws.cn/neptune-analytics/latest/userguide/custom-algorithms-property-graph-schema.html)是同步的。它在每次调用时计算架构。 在 Neptune 数据库中，您可以通过调用显式触发异步架构计算`neptune.graph.pg_schema.compute()`，该计算会立即返回。当您使用轮询完成情况时，计算在后台运行`neptune.graph.pg_schema()`。计算完成后，Neptune 会保留该架构，并在后续读取时立即将其返回，无需重新计算。在计算仍在进行时，也可以获得部分结果。您也可以停止正在运行的计算，稍后再恢复。 ## 与图表摘要 API 的比较 [图表摘要 API ](neptune-graph-summary.md) 不提供标签三元组或属性数据类型。属性图架构过程填补了这一空白。标签三元组显示图表中的特定关系模式。例如，`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()`操作需要写入权限，因为它们修改了用于缓存和保存架构的内部状态。 **Example 示例 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`（字符串）-用于计算的线程数。0 表示自动（根据硬件确定）。范围：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}`描述哪些节点类型通过哪些边缘类型进行连接 **支持的数据类型：**`String`、`Int`、`Long`、`Double`、`Bool`、`Date` 如果一个属性在不同的节点上有多种数据类型（例如，一些节点存储为，`Int`而另一些节点存储`age`为`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`，则计算将从中断的地方恢复。 + 如果在状态为时调用`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 onl ** y — 只能通过 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"] } } } } }] } ```