Esquema de gráficos de propiedades

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

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:

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 explícitamente un cálculo de esquema asincrónico mediante una llamada, que devuelve inmediatamente. neptune.graph.pg_schema.compute() El cálculo se ejecuta en segundo plano mientras se sondea para completarlo con. neptune.graph.pg_schema() Una vez calculado, Neptune conserva el esquema y lo devuelve instantáneamente en las lecturas posteriores sin necesidad de volver a calcularlo. Los resultados parciales también están disponibles mientras el cálculo aún 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 del gráfico de propiedades llena este vacío. Los triples de etiquetas muestran los patrones de relación específicos de la gráfica. Por ejemplo, a Person se conecta a Company través de un worksAt borde. 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 de gráficos 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 de esquema:

Las stop() operaciones compute() y requieren permisos de escritura porque modifican el estado interno utilizado para almacenar en caché y mantener el 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 Only. neptune-db:ReadDataViaQuery

Instancias de escritor y lector

Puede activar el cálculo del esquema solo en la instancia de escritura. 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

Lea el esquema

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

Sintaxis:

Comportamiento: regresa 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:

Objeto de esquema:

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

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

Esquema de cálculo

Activa un cálculo de esquema en segundo plano.

Sintaxis:

Acciones de IAM requeridas: y neptune-db:ReadDataViaQuery neptune-db:WriteDataViaQuery

Parámetros:

Comportamiento:

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

Detener el cálculo del esquema

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

Sintaxis:

Acciones de IAM necesarias: y neptune-db:ReadDataViaQuery neptune-db:WriteDataViaQuery

Comportamiento:

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

Uso de YIELD con los resultados del esquema

Puede utilizarlos YIELD para extraer los campos del 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 de cálculo del esquema

Operación asincrónica

El cálculo del esquema es una operación asincrónica. 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 hace una llamadaneptune.graph.pg_schema(), que devuelve el estado actual yprogressPercentage.

Estados

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

Comportamiento de persistencia y reinicio

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

Resultados parciales

Mientras un cálculo está en curso, pg_schema() devuelve resultados parciales. Estos incluyen cualquier esquema completado anteriormente y fusionado con las etiquetas, propiedades y triples descubiertos hasta el momento 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 sobre el esquema.

Réplicas de lectura

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

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

Prácticas recomendadas

Limitaciones

Resultado de ejemplo

El siguiente ejemplo 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"]
            }
          }
        }
      }
    }]
}