Comparación con Neptune Analytics Comparación con la API Graph Summary Requisitos previos Referencia de la API Usando YIELD Ciclo de vida de la computación Prácticas recomendadas Limitaciones Resultado de ejemplo

Esquema de gráficos de propiedades

El neptune.graph.pg_schema() procedimiento proporciona una visión general completa de la estructura del gráfico de propiedades. Devuelve todas las etiquetas de nodos, etiquetas de borde, propiedades con sus tipos de datos y triples de etiquetas ({~from, ~type, ~to}patrones que describen cómo se conectan los tipos de nodos a través de los tipos de bordes).

Actualmente, este procedimiento solo está disponible a través del punto final de OpenCypher y descubre el esquema de todos los datos del gráfico de propiedades.

Utilice este procedimiento para tareas como:

Generación de consultas de IA y LLM: proporciona a los LLM la estructura gráfica que necesitan para generar consultas Cypher válidas a partir de lenguaje natural (Text-to-Cypheraplicaciones GraphRag).
Visualización y exploración de gráficos: herramientas como Graph Explorer utilizan la información del esquema para renderizar representaciones visuales interactivas de los datos de los gráficos sin necesidad de escanear toda la base de datos.
Descubrimiento de esquemas de aplicaciones: aplicaciones que necesitan comprender la estructura de gráficos al inicio, como los generadores de esquemas GraphQL o las herramientas de validación de datos.

Comparación con Neptune Analytics

En Neptune Analytics, neptune.graph.pg_schema()es sincrónico. Calcula el esquema de cada llamada.

En Neptune Database, se activa de forma explícita un cálculo de esquema asíncrono mediante una llamada, que se devuelve inmediatamente. neptune.graph.pg_schema.compute() El cálculo se ejecuta en segundo plano mientras se realiza el sondeo para completarlo. neptune.graph.pg_schema() Una vez calculado, Neptune conserva el esquema y lo devuelve instantáneamente en las lecturas posteriores sin tener que volver a calcularlo. Los resultados parciales también están disponibles mientras el cálculo está en curso. También puede detener un cálculo en ejecución y reanudarlo más adelante.

Comparación con la API Graph Summary

La API Graph Summary no proporciona triples de etiquetas ni tipos de datos de propiedades. El procedimiento del esquema de gráficos de propiedades llena este vacío. Los triples de etiquetas muestran los patrones de relación específicos del gráfico. Por ejemplo, a Person se conecta a a Company través de una worksAt arista. Esta información es fundamental para que los LLM generen consultas semánticamente correctas.

Requisitos previos

Engine version (Versión del motor)

El procedimiento del esquema del gráfico de propiedades requiere la versión 1.4.8.0 o posterior del motor Neptune.

Permisos de IAM

Se requieren las siguientes acciones de IAM para cada operación del esquema:

CALL neptune.graph.pg_schema()— requiereneptune-db:ReadDataViaQuery.
CALL neptune.graph.pg_schema.compute()— requiere neptune-db:ReadDataViaQuery yneptune-db:WriteDataViaQuery.
CALL neptune.graph.pg_schema.stop()— requiere neptune-db:ReadDataViaQuery yneptune-db:WriteDataViaQuery.

Las stop() operaciones compute() y requieren permisos de escritura porque modifican el estado interno utilizado para almacenar en caché y conservar el esquema.

ejemplo Política de IAM de ejemplo

La siguiente política otorga los permisos mínimos necesarios para todas las operaciones del esquema:


{
  "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/*"
  }]
}

Para conceder acceso de solo lectura al esquema (sin la posibilidad de activar el cálculo), utilice solo. neptune-db:ReadDataViaQuery

Instancias de escritor y lector

Puede activar el cálculo del esquema solo en la instancia de escritor. Las instancias de réplica de lectura pueden leer el esquema (que se replica desde el escritor) pero no pueden ejecutarse compute() o. stop()

Referencia de la API

Lee el esquema

Recupera el esquema actual y el estado del cálculo.

Sintaxis:

Comportamiento: retorna inmediatamente con el esquema y el estado actuales. Siempre sin bloqueos. Si no se ha calculado ningún esquema, devuelve el estado: "NotStarted" con campos de esquema vacíos. Si hay un cálculo en curso, devuelve resultados parciales con el estado:"InProgress".

Formato de respuesta:

La respuesta contiene un objeto de esquema con los siguientes campos:

Objeto de estado:

state(String) — Estado actual del ciclo de vida: NotStartedInProgress,Completed,Stopped, Failed
concurrency(Cadena): número de subprocesos utilizados para el cálculo. 0 significa auto (determinado en función del hardware). Rango: de 1 (más bajo) a 16 (más alto).
lastComputedTimestamp(Cadena): fecha y hora ISO-8601 UTC del último cálculo realizado correctamente (por ejemplo,) 2026-05-29T08:00:00Z
progressPercentage(String) — Progreso del cálculo: 0 cuando no se ha iniciado, 0—99 durante el cálculo y 100 cuando se ha completado
errorMessage(Cadena): solo está presente cuando se rechaza una solicitud o se produce un error en el cálculo. Explica el motivo.

Objeto de esquema:

nodeLabels— Matriz de todas las etiquetas de nodo únicas del gráfico
edgeLabels— Matriz de todas las etiquetas de arista únicas del gráfico
nodeLabelDetails— Para cada etiqueta de nodo: propiedades y sus tipos de datos
edgeLabelDetails— Para cada etiqueta de borde: propiedades y sus tipos de datos
labelTriples— Matriz de patrones de relación: {~from, ~type, ~to} describe qué tipos de nodos se conectan a través de qué tipos de bordes

Tipos de datos compatibles: StringInt,Long,Double,Bool, Date

Si una propiedad tiene varios tipos de datos en distintos nodos (por ejemplo, algunos nodos almacenan age como Int y otros comoString), todos los tipos observados se muestran en la datatypes matriz.

Esquema de cálculo

Activa un cálculo del esquema en segundo plano.

Sintaxis:

Se requieren acciones de IAM: y neptune-db:ReadDataViaQuery neptune-db:WriteDataViaQuery

Parámetros:

concurrency(Entero, opcional): número de subprocesos para el cálculo en segundo plano. 0 (predeterminado) = se determina automáticamente en función del hardware. Rango: de 1 (más bajo) a 16 (más alto). Usa valores más bajos en instancias más pequeñas para reducir el impacto en los recursos.

Comportamiento:

Regresa inmediatamente con el estado actual. El cálculo se ejecuta de forma asíncrona en segundo plano.
Si se llama cuando el estado esStopped, el cálculo se reanuda desde donde lo dejó.
Si se llama cuando el estado esCompleted, inicia un nuevo cálculo. El esquema anterior sigue publicando lecturas hasta que se complete el nuevo cálculo.
Si se llama cuando ya hay un cálculoInProgress, Neptune rechaza la solicitud con un mensaje de error.
Si se llama durante una carga masiva activa, Neptune rechaza la solicitud con un mensaje de error.

Respuesta: devuelve el objeto de estado que muestra el estado: "InProgress" con los progressPercentage campos concurrency y.

Detenga el cálculo del esquema

Detiene un cálculo en segundo plano en ejecución.

Sintaxis:

Se requieren acciones de IAM: y neptune-db:ReadDataViaQuery neptune-db:WriteDataViaQuery

Comportamiento:

Detiene el cálculo en ejecución. El progreso se guarda para que pueda reanudarse desde donde lo dejó cuando compute() vuelva a llamar.
Un cálculo detenido no se reanuda automáticamente al reiniciarse el motor. Debe llamar compute() de forma explícita.

Respuesta: Devuelve el objeto de estado que muestra el estado: "Stopped" con el actualprogressPercentage.

Uso de YIELD con los resultados del esquema

Se puede utilizar YIELD para extraer campos de esquema y combinarlos con otras consultas. En el siguiente ejemplo, se recuperan todas las etiquetas de los nodos y se cuenta el número de nodos de cada etiqueta. La collSort() función ordena la lista alfabéticamente:


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

Código de salida de ejemplo:


{
  "results": [{
      "label": "airport",
      "count": 3503
    }, {
      "label": "continent",
      "count": 7
    }, {
      "label": "country",
      "count": 237
    }, {
      "label": "version",
      "count": 1
    }]
}

Ciclo de vida del cálculo del esquema

Operación asíncrona

El cálculo de esquemas es una operación asíncrona. Cuando llamasneptune.graph.pg_schema.compute(), vuelve inmediatamente con el estado actual. El cálculo se ejecuta en segundo plano. Para comprobar el progreso y la finalización, se realiza una llamadaneptune.graph.pg_schema(), que devuelve el estado actual yprogressPercentage.

Estados

El cálculo del esquema pasa por los siguientes estados:

NotStarted— Aún no se ha calculado ningún esquema. pg_schema()devuelve un esquema vacío.
InProgress— Se está ejecutando un cálculo en segundo plano. pg_schema()devuelve resultados parciales (una unión del último esquema completo y los descubrimientos del cálculo actual).
Completed— El cálculo ha finalizado correctamente. El esquema completo está disponible.
Stopped— El cálculo se detuvo, ya sea por una llamada stop() o porque un reinicio del motor lo interrumpió. Los resultados parciales están disponibles. El progreso se guarda para que el cálculo pueda reanudarse desde donde lo dejó al llamarcompute().
Failed— Se ha producido un error en el cálculo. El último esquema calculado correctamente (si lo hay) permanece disponible.

Comportamiento de persistencia y reinicio

El esquema calculado se mantiene y sobrevive a los reinicios del motor. El comportamiento del reinicio depende del estado en el momento del reinicio:

InProgress— Si el motor se reinicia durante el cálculo, el cálculo pasa a. Stopped La llamada compute() se reanudará desde donde la dejó. El progreso se mantiene y el cálculo continúa desde su último punto de control.
Stopped— El cálculo no se reanuda automáticamente. Debe llamar compute() para continuar desde donde lo dejó.
Completed— El esquema se carga y está disponible inmediatamente.

Resultados parciales

Mientras se está realizando un cálculo, pg_schema() devuelve resultados parciales. Estos incluyen cualquier esquema previamente completado que se haya combinado con las etiquetas, propiedades y triples descubiertas hasta ahora en el cálculo actual. Esto significa que no tiene que esperar a que se complete un cálculo completo para recuperar información útil del esquema.

Réplicas de lectura

Las instancias de réplica de lectura pueden leer el esquema utilizando. CALL neptune.graph.pg_schema() Neptune replica el esquema de la instancia del escritor y lo hace disponible en las réplicas casi inmediatamente a medida que los elementos del esquema se descubren en el escritor.

Las réplicas de lectura no se pueden ejecutar o. compute() stop() Estas llamadas devuelven un error:

compute() – "Schema cannot be computed on read replica"
stop() – "Schema compute cannot be stopped on read replica"

Prácticas recomendadas

Volver a calcular después de las mutaciones: el esquema no se actualiza automáticamente cuando cambian los datos. Vuelva a calcular el esquema después de cargas masivas o mutaciones de datos importantes. Utilice el lastComputedTimestamp campo para determinar si el esquema está desactualizado en relación con los cambios recientes en el gráfico.
Simultaneidad: el valor de simultaneidad predeterminado (0) se adapta automáticamente al hardware de la instancia. Para la mayoría de las cargas de trabajo, esta es la configuración recomendada. Si el cálculo en segundo plano afecta a la carga de trabajo de la consulta, especifique un valor inferior (por ejemplo, 1 o 2) para reducir el uso de recursos.
Detener y reanudar: si el cálculo en segundo plano afecta a la carga de trabajo de las consultas, deténgalo stop() y reanude más tarde, durante un período de menor tráfico, volviendo a llamar. compute() El cálculo continúa desde donde lo dejó.
Handle se reinicia correctamente: si el motor se reinicia mientras se está realizando un cálculo de esquema, el cálculo pasa a. Stopped La llamada compute() se reanudará desde donde la dejó. El progreso se preserva.
Bases de datos grandes: en el caso de las bases de datos con grandes volúmenes de almacenamiento (varios TB), el cálculo del esquema completo puede llevar más tiempo. Puede iniciar un proceso, dejarlo funcionar hasta que avance entre un 10 y un 20% y, a continuación, detenerlo. Los resultados parciales recopilados durante esta ventana proporcionan un útil ejemplo de esquema en el que ya se han descubierto muchas etiquetas, propiedades y triples. Lea el esquema parcial pg_schema() mientras el cálculo está en curso o después de detenerlo. Continúe más adelante, cuando su carga de trabajo lo permita.

Limitaciones

Las eliminaciones requieren volver a calcularse: las etiquetas, propiedades y triples eliminadas solo se eliminan del esquema después del siguiente recálculo completo. Hasta entonces, es posible que los elementos eliminados sigan apareciendo en los resultados del esquema.
OpenCypher solo: solo puede llamar a este procedimiento a través del punto final de la consulta OpenCypher.
No se puede realizar el cálculo durante la carga masiva: Neptune rechaza el cálculo del esquema mientras haya una operación de carga masiva activa. Active el cálculo una vez que se complete la carga masiva.

Resultado de ejemplo

En el siguiente ejemplo, se muestra el resultado del esquema para el conjunto de datos de rutas aéreas:


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

API de resumen de gráficos

Estadísticas del DFE