与海王星分析的比较与图表摘要 API 的比较先决条件 API 参考使用 YIELD 计算生命周期最佳实践限制示例输出

属性图架构

该neptune.graph.pg_schema()过程全面概述了您的属性图结构。它返回所有节点标签、边缘标签、属性及其数据类型以及标签三元组（描述节点类型如何通过边缘类型连接的{~from, ~type, ~to}模式）。

此过程目前仅可通过 OpenCypher 端点使用，可发现所有属性图数据的架构。

使用此过程执行以下任务：

AI 和 LLM 查询生成 — 为 LLM 提供从自然语言（Text-to-CypherGraphRag 应用程序）生成有效的 Cypher 查询所需的图形结构。
图表可视化和探索 — Graph Explorer 等工具使用架构信息来呈现图形数据的交互式可视化表示，而无需扫描整个数据库。
应用程序架构发现 — 启动时需要了解图形结构的应用程序，例如 GraphQL 架构生成器或数据验证工具。

与海王星分析的比较

在 Neptune Analytics 中，neptune.graph.pg_schema()是同步的。它在每次调用时计算架构。

在 Neptune 数据库中，您可以通过调用显式触发异步架构计算neptune.graph.pg_schema.compute()，该计算会立即返回。当您使用轮询完成情况时，计算在后台运行neptune.graph.pg_schema()。计算完成后，Neptune 会保留该架构，并在后续读取时立即将其返回，无需重新计算。在计算仍在进行时，也可以获得部分结果。您也可以停止正在运行的计算，稍后再恢复。

与图表摘要 API 的比较

图表摘要 API 不提供标签三元组或属性数据类型。属性图架构过程填补了这一空白。标签三元组显示图表中的特定关系模式。例如，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、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数组中列出。

计算架构

触发后台架构计算。

语法：

所需的 IAM 操作：neptune-db:ReadDataViaQuery以及 neptune-db:WriteDataViaQuery

参数：

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

行为：

立即以当前状态返回。计算在后台异步运行。
如果在状态为时调用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— 如果引擎在计算期间重新启动，则计算将转换为。Stoppedcompute()致电从中断的地方继续。进度会被保留，计算从最后一个检查点开始继续。
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()再次调用，稍后再继续。计算从中断的地方继续进行。
句柄正常重启 — 如果在架构计算进行时引擎重新启动，则计算将转换为。Stoppedcompute()致电从中断的地方继续。进度得以保留。
大型数据库 — 对于存储容量大（多 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"]
            }
          }
        }
      }
    }]
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

图形摘要 API

DFE 统计数据