Esquema gráfico de propriedades

O neptune.graph.pg_schema() procedimento fornece uma visão geral abrangente da estrutura gráfica de sua propriedade. Ele retorna todos os rótulos de nós, rótulos de borda, propriedades com seus tipos de dados e triplos de rótulos ({~from, ~type, ~to}padrões que descrevem como os tipos de nós se conectam por meio de tipos de borda).

Atualmente, esse procedimento está disponível somente por meio do endpoint OpenCypher e descobre o esquema de todos os dados do gráfico de propriedades.

Use esse procedimento para tarefas como:

Comparação com o Neptune Analytics

No Neptune Analytics, neptune.graph.pg_schema() é síncrono. Ele calcula o esquema em cada chamada.

No Neptune Database, você aciona explicitamente uma computação de esquema assíncrono chamando, que retorna imediatamente. neptune.graph.pg_schema.compute() O cálculo é executado em segundo plano enquanto você pesquisa para conclusão usando. neptune.graph.pg_schema() Uma vez computado, o Neptune persiste o esquema e o retorna instantaneamente em leituras subsequentes sem recálculo. Os resultados parciais também estão disponíveis enquanto a computação ainda está em andamento. Você também pode interromper um cálculo em execução e retomá-lo mais tarde.

Comparação com a API Graph Summary

A API Graph Summary não fornece triplos de rótulos nem tipos de dados de propriedades. O procedimento do esquema do gráfico de propriedades preenche essa lacuna. Os triplos de rótulos mostram os padrões de relacionamento específicos em seu gráfico. Por exemplo, a Person se conecta a Company por meio de uma worksAt borda. Essas informações são essenciais para que os LLMs gerem consultas semanticamente corretas.

Pré-requisitos

Versão do mecanismo

O procedimento do esquema do gráfico de propriedades requer a versão 1.4.8.0 ou posterior do mecanismo Neptune.

Permissões do IAM

As seguintes ações do IAM são necessárias para cada operação do esquema:

As stop() operações compute() e exigem permissões de gravação porque modificam o estado interno usado para armazenar em cache e manter o 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 acesso somente para leitura ao esquema (sem a capacidade de acionar a computação), use somente. neptune-db:ReadDataViaQuery

Instâncias de escritor e leitor

Você pode acionar a computação do esquema somente na instância do gravador. As instâncias de réplica de leitura podem ler o esquema (que é replicado do gravador), mas não podem ser executadas ou. compute() stop()

Referência de API

Esquema de leitura

Recupera o esquema atual e o status de computação.

Sintaxe:

Comportamento: retorna imediatamente com o esquema e o status atuais. Sempre sem bloquear. Se nenhum esquema tiver sido calculado, retorna state: "NotStarted" com campos de esquema vazios. Se um cálculo estiver em andamento, retorna resultados parciais com state:"InProgress".

Formato de resposta:

A resposta contém um objeto de esquema com os seguintes campos:

Objeto de status:

Objeto do esquema:

Tipos de dados compatíveis: StringInt,Long,Double,Bool, Date

Se uma propriedade tiver vários tipos de dados em nós diferentes (por exemplo, alguns nós armazenam age como Int e outros comoString), todos os tipos observados serão listados na datatypes matriz.

Esquema de computação

Aciona um cálculo de esquema em segundo plano.

Sintaxe:

Ações do IAM necessárias: neptune-db:ReadDataViaQuery e neptune-db:WriteDataViaQuery

Parâmetros:

Comportamento:

Resposta: retorna o objeto de status mostrando o estado: "InProgress" com os progressPercentage campos concurrency e.

Pare a computação do esquema

Interrompe uma computação em segundo plano em execução.

Sintaxe:

Ações do IAM necessárias: neptune-db:ReadDataViaQuery e neptune-db:WriteDataViaQuery

Comportamento:

Resposta: retorna o objeto de status mostrando o estado: "Stopped" com o atualprogressPercentage.

Usando YIELD com resultados do esquema

Você pode usar YIELD para extrair campos do esquema e combiná-los com outras consultas. O exemplo a seguir recupera todos os rótulos de nós e conta o número de nós para cada rótulo. A collSort() função classifica a lista em ordem alfabética:

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

Exemplo de saída:

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

Ciclo de vida da computação do esquema

Operação assíncrona

A computação do esquema é uma operação assíncrona. Quando você liganeptune.graph.pg_schema.compute(), ele retorna imediatamente com o status atual. A computação é executada em segundo plano. Você pesquisa o progresso e a conclusão ligando paraneptune.graph.pg_schema(), que retorna o estado atual e. progressPercentage

Estados

A computação do esquema passa pelos seguintes estados:

Persistência e comportamento de reinicialização

O esquema computado persiste e sobrevive às reinicializações do mecanismo. O comportamento de reinicialização depende do estado no momento da reinicialização:

Resultados parciais

Enquanto um cálculo está em andamento, pg_schema() retorna resultados parciais. Isso inclui qualquer esquema concluído anteriormente mesclado com os rótulos, propriedades e triplos descobertos até agora na computação atual. Isso significa que você não precisa esperar que uma computação completa seja concluída antes de recuperar informações úteis do esquema.

Réplicas de leitura

As instâncias de réplica de leitura podem ler o esquema usando. CALL neptune.graph.pg_schema() O Neptune replica o esquema da instância do gravador e o disponibiliza em réplicas quase imediatamente à medida que os elementos do esquema são descobertos no gravador.

As réplicas de leitura não podem ser executadas compute() nemstop(). Essas chamadas retornam um erro:

Práticas recomendadas

Limitações

Exemplo de saída

O exemplo a seguir mostra a saída do esquema para o conjunto de dados de rotas 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"]
            }
          }
        }
      }
    }]
}