As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# 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:
+ **Geração de consultas AI e LLM ** — Dê aos LLMs a estrutura gráfica de que precisam para gerar consultas Cypher válidas a partir de linguagem natural (Text-to-Cypheraplicativos GraphRag).
+ **Visualização e exploração de gráficos ** — Ferramentas como o [ Graph Explorer ](visualization-graph-explorer.md) usam informações de esquema para renderizar representações visuais interativas de dados gráficos sem escanear todo o banco de dados.
+ **Descoberta de esquemas de aplicativos ** — Aplicativos que precisam entender a estrutura gráfica na inicialização, como geradores de esquema GraphQL ou ferramentas de validação de dados.
## Comparação com o Neptune Analytics
No Neptune Analytics, [`neptune.graph.pg_schema()`](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/custom-algorithms-property-graph-schema.html) é 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 ](neptune-graph-summary.md) 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:
+ `CALL neptune.graph.pg_schema()`— exige`neptune-db:ReadDataViaQuery`.
+ `CALL neptune.graph.pg_schema.compute()`— requer `neptune-db:ReadDataViaQuery` `neptune-db:WriteDataViaQuery` e.
+ `CALL neptune.graph.pg_schema.stop()`— requer `neptune-db:ReadDataViaQuery` `neptune-db:WriteDataViaQuery` e.
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.
**Example Exemplo de política do IAM**
A política a seguir concede as permissões mínimas necessárias para todas as operações do 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:**
------
#### [ AWS 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()'
```
------
**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: **
+ `state`(String) — Estado atual do ciclo de vida:`NotStarted`,,,`InProgress`, `Completed` `Stopped` `Failed`
+ `concurrency`(String) — Número de threads usados para o cálculo. 0 significa automático (determinado com base no hardware). Intervalo: 1 (menor) a 16 (maior).
+ `lastComputedTimestamp`(String) — Timestamp ISO-8601 UTC da última computação bem-sucedida (por exemplo,) `2026-05-29T08:00:00Z`
+ `progressPercentage`(String) — Progresso da computação: 0 quando não iniciado, 0—99 durante o cálculo, 100 quando concluído
+ `errorMessage`(String) — Presente somente quando uma solicitação é rejeitada ou o cálculo falha. Explica o motivo.
**Objeto do esquema: **
+ `nodeLabels`— Matriz de todos os rótulos de nós exclusivos no gráfico
+ `edgeLabels`— Matriz de todos os rótulos de borda exclusivos no gráfico
+ `nodeLabelDetails`— Para cada rótulo de nó: propriedades e seus tipos de dados
+ `edgeLabelDetails`— Para cada etiqueta de borda: propriedades e seus tipos de dados
+ `labelTriples`— Matriz de padrões de relacionamento: `{~from, ~type, ~to}` descrevendo quais tipos de nós se conectam por meio de quais tipos de arestas
**Tipos de dados compatíveis: ** `String``Int`,`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 como`String`), todos os tipos observados serão listados na `datatypes` matriz.
### Esquema de computação
Aciona um cálculo de esquema em segundo plano.
**Sintaxe:**
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://{{your-neptune-endpoint}}:{{port}} \
--open-cypher-query "CALL neptune.graph.pg_schema.compute()"
```
Com parâmetro de simultaneidade opcional:
```
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()'
```
Com parâmetro de simultaneidade opcional:
```
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})'
```
------
**Ações do IAM necessárias: ** `neptune-db:ReadDataViaQuery` e `neptune-db:WriteDataViaQuery`
**Parâmetros:**
+ `concurrency`(Inteiro, opcional) — Número de segmentos para o cálculo em segundo plano. 0 (padrão) = determinado automaticamente com base no hardware. Intervalo: 1 (menor) a 16 (maior). Use valores mais baixos em instâncias menores para reduzir o impacto sobre os recursos.
**Comportamento: **
+ Retorna imediatamente com o status atual. A computação é executada de forma assíncrona em segundo plano.
+ Se chamado quando o estado é`Stopped`, o cálculo é retomado de onde parou.
+ Se chamado quando o estado é`Completed`, inicia um novo recálculo. O esquema anterior continua servindo leituras até que a nova computação seja concluída.
+ Se chamado quando um cálculo já está pronto`InProgress`, o Neptune rejeita a solicitação com uma mensagem de erro.
+ Se chamado durante um carregamento em massa ativo, o Neptune rejeita a solicitação com uma mensagem de erro.
**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:**
------
#### [ AWS 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()'
```
------
**Ações do IAM necessárias: ** `neptune-db:ReadDataViaQuery` e `neptune-db:WriteDataViaQuery`
**Comportamento: **
+ Interrompe a computação em execução. O progresso é salvo para que possa ser retomado de onde parou quando você ligar `compute()` novamente.
+ Uma computação interrompida * não é retomada * automaticamente na reinicialização do motor. Você deve ligar `compute()` explicitamente.
**Resposta: ** retorna o objeto de status mostrando o estado: `"Stopped"` com o atual`progressPercentage`.
## 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ê liga`neptune.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 para`neptune.graph.pg_schema()`, que retorna o estado atual e. `progressPercentage`
### Estados
A computação do esquema passa pelos seguintes estados:
+ `NotStarted`— Nenhum esquema foi computado ainda. `pg_schema()`retorna um esquema vazio.
+ `InProgress`— Uma computação em segundo plano está sendo executada. `pg_schema()`retorna resultados parciais (uma união do último esquema completo e descobertas da computação atual).
+ `Completed`— O cálculo foi concluído com sucesso. O esquema completo está disponível.
+ `Stopped`— A computação foi interrompida, seja por chamada `stop()` ou porque uma reinicialização do motor a interrompeu. Resultados parciais estão disponíveis. O progresso é salvo para que a computação possa ser retomada de onde parou quando você liga`compute()`.
+ `Failed`— O cálculo encontrou um erro. O último esquema computado com sucesso (se houver) permanece disponível.
### 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:
+ `InProgress`— Se o mecanismo for reiniciado durante a computação, a computação passa para. `Stopped` Ligue `compute()` para retomar de onde parou. O progresso é preservado e o cálculo continua a partir do último ponto de verificação.
+ `Stopped`— A computação * não é retomada * automaticamente. Você deve ligar `compute()` para continuar de onde parou.
+ `Completed`— O esquema é carregado e está disponível imediatamente.
### 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()` nem`stop()`. Essas chamadas retornam um erro:
+ `compute()` – `"Schema cannot be computed on read replica"`
+ `stop()` – `"Schema compute cannot be stopped on read replica"`
## Práticas recomendadas
+ **Recalcular após mutações ** — O esquema não é atualizado automaticamente quando os dados são alterados. Recalcule o esquema após carregamentos em massa ou mutações significativas nos dados. Use o `lastComputedTimestamp` campo para determinar se o esquema está desatualizado em relação às mudanças recentes em seu gráfico.
+ **Simultaneidade ** — O valor de simultaneidade padrão (0) se adapta automaticamente ao hardware da sua instância. Para a maioria das cargas de trabalho, essa é a configuração recomendada. Se a computação em segundo plano afetar sua carga de trabalho de consulta, especifique um valor menor (por exemplo, 1 ou 2) para reduzir o uso de recursos.
+ **Interrompa e retome ** — Se a computação em segundo plano afetar sua carga de trabalho de consulta, pare-a `stop()` e retome mais tarde, durante um período de menor tráfego, ligando novamente. `compute()` O cálculo continua de onde parou.
+ **Gerencie reinicializações normalmente ** — Se o mecanismo for reiniciado enquanto a computação do esquema estiver em andamento, a computação fará a transição para. `Stopped` Ligue `compute()` para retomar de onde parou. O progresso é preservado.
+ **Bancos de dados grandes ** — Para bancos de dados com grandes volumes de armazenamento (vários TB), a computação completa do esquema pode levar muito tempo. Você pode iniciar uma computação, deixá-la funcionar até 10— 20% de progresso e depois parar. Os resultados parciais coletados durante essa janela fornecem uma amostra útil de esquema com muitos rótulos, propriedades e triplos já descobertos. Leia o esquema parcial `pg_schema()` enquanto a computação está em andamento ou após a interrupção. Continue mais tarde, quando sua carga de trabalho permitir.
## Limitações
+ **As exclusões exigem recalculação ** — rótulos, propriedades e triplos excluídos só são removidos do esquema após a próxima recalculação completa. Até lá, os elementos excluídos ainda podem aparecer nos resultados do esquema.
+ **OpenCypher somente ** — Você pode chamar esse procedimento somente por meio do endpoint de consulta OpenCypher.
+ **Não é possível computar durante o carregamento em massa ** — o Neptune rejeita o cálculo do esquema enquanto uma operação de carregamento em massa está ativa. Acione a computação após a conclusão do carregamento em massa.
## 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"]
}
}
}
}
}]
}
```