Confronto con Neptune Analytics Confronto con l'API Graph Summary Prerequisiti Guida di riferimento alle API Utilizzando YIELD Ciclo di vita del calcolo Best practice Limitazioni Output di esempio

Schema del grafico delle proprietà

La procedura fornisce una panoramica completa della struttura del grafico delle proprietà. neptune.graph.pg_schema() Restituisce tutte le etichette dei nodi, le etichette dei bordi, le proprietà con i relativi tipi di dati e le triple di etichette ({~from, ~type, ~to}schemi che descrivono il modo in cui i tipi di nodo si connettono tramite i tipi di bordi).

Questa procedura è attualmente disponibile solo tramite l'endpoint OpenCypher e rileva lo schema per tutti i dati del grafico delle proprietà.

Utilizzate questa procedura per attività come:

Generazione di query AI e LLM: fornisci agli LLM la struttura grafica di cui hanno bisogno per generare query Cypher valide dal linguaggio naturale (Text-to-Cypherapplicazioni GraphRag).
Visualizzazione ed esplorazione dei grafici: strumenti come Graph Explorer utilizzano le informazioni sullo schema per rendere rappresentazioni visive interattive dei dati del grafico senza scansionare l'intero database.
Individuazione dello schema delle applicazioni: applicazioni che devono comprendere la struttura dei grafi all'avvio, come i generatori di schemi GraphQL o gli strumenti di convalida dei dati.

Confronto con Neptune Analytics

In Neptune Analytics, è sincrono. neptune.graph.pg_schema() Calcola lo schema per ogni chiamata.

In Neptune Database, si attiva esplicitamente un calcolo asincrono dello schema chiamando, che ritorna immediatamente. neptune.graph.pg_schema.compute() Il calcolo viene eseguito in background mentre si esegue il polling per il completamento utilizzando. neptune.graph.pg_schema() Una volta calcolato, Neptune mantiene lo schema e lo restituisce istantaneamente nelle letture successive senza ricalcolo. I risultati parziali sono disponibili anche mentre il calcolo è ancora in corso. È inoltre possibile interrompere un calcolo in esecuzione e riprenderlo in un secondo momento.

Confronto con l'API Graph Summary

L'API Graph Summary non fornisce triple di etichette o tipi di dati sulle proprietà. La procedura dello schema del grafico delle proprietà colma questa lacuna. Le triple delle etichette mostrano i modelli di relazione specifici nel grafico. Ad esempio, a Person si connette a a Company tramite un worksAt bordo. Queste informazioni sono fondamentali per gli LLM per generare query semanticamente corrette.

Prerequisiti

Versione del motore

La procedura dello schema del grafico delle proprietà richiede la versione 1.4.8.0 o successiva del motore Neptune.

autorizzazioni IAM

Le seguenti azioni IAM sono necessarie per ogni operazione dello schema:

CALL neptune.graph.pg_schema()— richiedeneptune-db:ReadDataViaQuery.
CALL neptune.graph.pg_schema.compute()— richiede neptune-db:ReadDataViaQuery eneptune-db:WriteDataViaQuery.
CALL neptune.graph.pg_schema.stop()— richiede neptune-db:ReadDataViaQuery eneptune-db:WriteDataViaQuery.

Le stop() operazioni compute() and richiedono autorizzazioni di scrittura perché modificano lo stato interno utilizzato per memorizzare nella cache e rendere persistente lo schema.

Esempio Policy IAM di esempio

La seguente politica concede le autorizzazioni minime necessarie per tutte le operazioni sullo schema:


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

Per concedere l'accesso in sola lettura allo schema (senza la possibilità di attivare il calcolo), usa only. neptune-db:ReadDataViaQuery

Istanze di Writer e Reader

È possibile attivare il calcolo dello schema solo sull'istanza del writer. Le istanze di replica di lettura possono leggere lo schema (che viene replicato dal writer) ma non possono eseguire o. compute() stop()

Guida di riferimento alle API

Leggi lo schema

Recupera lo schema e lo stato di calcolo correnti.

Sintassi:

Comportamento: restituisce immediatamente lo schema e lo stato correnti. Sempre non bloccante. Se non è stato calcolato alcuno schema, restituisce state: "NotStarted" con campi di schema vuoti. Se è in corso un calcolo, restituisce risultati parziali con stato:. "InProgress"

Formato di risposta:

La risposta contiene un oggetto schema con i seguenti campi:

Oggetto di stato:

state(String) — Stato attuale del ciclo di vita:NotStarted,,InProgress, Completed Stopped Failed
concurrency(String) — Numero di thread utilizzati per il calcolo. 0 significa automatico (determinato in base all'hardware). Intervallo: da 1 (minimo) a 16 (massimo).
lastComputedTimestamp(String) — Timestamp ISO-8601 UTC dell'ultimo calcolo riuscito (ad esempio,) 2026-05-29T08:00:00Z
progressPercentage(String) — Avanzamento del calcolo: 0 quando non viene avviato, 0—99 durante il calcolo, 100 quando è completato
errorMessage(String) — Presente solo quando una richiesta viene rifiutata o il calcolo non riesce. Spiega il motivo.

Oggetto dello schema:

nodeLabels— Matrice di tutte le etichette univoche dei nodi nel grafico
edgeLabels— Matrice di tutte le etichette dei bordi univoche nel grafico
nodeLabelDetails— Etichetta per ogni nodo: proprietà e relativi tipi di dati
edgeLabelDetails— Per ogni etichetta laterale: proprietà e relativi tipi di dati
labelTriples— Serie di modelli di relazione: {~from, ~type, ~to} descrizione dei tipi di nodi che si connettono attraverso quali tipi di spigoli

Tipi di dati supportati: String,Int,Long,Double, Bool Date

Se una proprietà ha più tipi di dati su nodi diversi (ad esempio, alcuni nodi vengono archiviati age come Int e altri comeString), tutti i tipi osservati vengono elencati nell'datatypesarray.

Schema di calcolo

Attiva un calcolo dello schema in background.

Sintassi:

Azioni IAM richieste: neptune-db:ReadDataViaQuery e neptune-db:WriteDataViaQuery

Parametri:

concurrency(Numero intero, opzionale): numero di thread per il calcolo in background. 0 (impostazione predefinita) = determinato automaticamente in base all'hardware. Intervallo: da 1 (minimo) a 16 (massimo). Utilizza valori più bassi su istanze più piccole per ridurre l'impatto sulle risorse.

Comportamento:

Ritorna immediatamente con lo stato attuale. Il calcolo viene eseguito in modo asincrono in background.
Se viene chiamato quando lo stato èStopped, il calcolo riprende da dove era stato interrotto.
Se chiamato quando lo stato èCompleted, avvia un nuovo ricalcolo. Lo schema precedente continua a fornire le letture fino al completamento del nuovo calcolo.
Se viene chiamato quando è già in corso un calcoloInProgress, Neptune rifiuta la richiesta con un messaggio di errore.
Se viene chiamato durante un caricamento di massa attivo, Neptune rifiuta la richiesta con un messaggio di errore.

Risposta: restituisce l'oggetto di stato che mostra state: "InProgress" con i concurrency campi and. progressPercentage

Interrompi il calcolo dello schema

Interrompe un calcolo in background in esecuzione.

Sintassi:

Azioni IAM richieste: neptune-db:ReadDataViaQuery e neptune-db:WriteDataViaQuery

Comportamento:

Interrompe il calcolo in esecuzione. I progressi vengono salvati in modo che possano riprendere da dove erano stati interrotti quando chiami compute() nuovamente.
Un calcolo interrotto non viene ripreso automaticamente al riavvio del motore. È necessario chiamare esplicitamente. compute()

Risposta: restituisce l'oggetto di stato che mostra lo stato: "Stopped" con quello correnteprogressPercentage.

Utilizzo di YIELD con i risultati dello schema

È possibile YIELD utilizzarlo per estrarre i campi dello schema e combinarli con altre query. L'esempio seguente recupera tutte le etichette dei nodi e conta il numero di nodi per ciascuna etichetta. La collSort() funzione ordina l'elenco alfabeticamente:


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

Output di esempio:


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

Ciclo di vita del calcolo dello schema

Funzionamento asincrono

Il calcolo dello schema è un'operazione asincrona. Quando si chiamaneptune.graph.pg_schema.compute(), ritorna immediatamente con lo stato corrente. Il calcolo viene eseguito in background. Si esegue il polling per verificare l'avanzamento e il completamento tramite una chiamataneptune.graph.pg_schema(), che restituisce lo stato corrente e. progressPercentage

Stati

Il calcolo dello schema passa attraverso i seguenti stati:

NotStarted— Nessuno schema è stato ancora calcolato. pg_schema()restituisce uno schema vuoto.
InProgress— È in esecuzione un calcolo in background. pg_schema()restituisce risultati parziali (un'unione dell'ultimo schema completo e delle scoperte del calcolo corrente).
Completed— Il calcolo è stato completato con successo. Lo schema completo è disponibile.
Stopped— Il calcolo è stato interrotto, chiamando stop() o perché un riavvio del motore lo ha interrotto. Sono disponibili risultati parziali. I progressi vengono salvati in modo che il calcolo possa riprendere da dove era stato interrotto quando si chiamacompute().
Failed— Il calcolo ha rilevato un errore. L'ultimo schema calcolato correttamente (se presente) rimane disponibile.

Persistenza e comportamento di riavvio

Lo schema calcolato viene mantenuto e sopravvive ai riavvii del motore. Il comportamento di riavvio dipende dallo stato al momento del riavvio:

InProgress— Se il motore si riavvia durante il calcolo, il calcolo passa a. Stopped Chiama compute() per riprendere da dove era stata interrotta. L'avanzamento viene mantenuto e il calcolo continua dall'ultimo checkpoint.
Stopped— Il calcolo non viene ripreso automaticamente. È necessario chiamare compute() per continuare da dove era stato interrotto.
Completed— Lo schema viene caricato e disponibile immediatamente.

Risultati parziali

Mentre è in corso un calcolo, pg_schema() restituisce risultati parziali. Questi includono qualsiasi schema precedentemente completato unito alle etichette, alle proprietà e alle triple scoperte finora nel calcolo corrente. Ciò significa che non è necessario attendere il completamento di un calcolo completo prima di recuperare informazioni utili sullo schema.

Repliche di lettura

Le istanze di replica di lettura possono leggere lo schema utilizzando. CALL neptune.graph.pg_schema() Neptune replica lo schema dall'istanza del writer e lo rende disponibile nelle repliche quasi immediatamente non appena gli elementi dello schema vengono scoperti sul writer.

Le repliche lette non possono essere eseguite o. compute() stop() Queste chiamate restituiscono un errore:

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

Best practice

Ricalcola dopo le mutazioni: lo schema non si aggiorna automaticamente quando i dati cambiano. Ricalcola lo schema dopo caricamenti di massa o mutazioni significative dei dati. Usa il lastComputedTimestamp campo per determinare se lo schema è obsoleto rispetto alle modifiche recenti nel grafico.
Concorrenza: il valore di concorrenza predefinito (0) si adatta automaticamente all'hardware dell'istanza. Per la maggior parte dei carichi di lavoro questa è l'impostazione consigliata. Se il calcolo in background influisce sul carico di lavoro delle query, specifica un valore inferiore (ad esempio, 1 o 2) per ridurre l'utilizzo delle risorse.
Interrompi e riprendi: se il calcolo in background influisce sul carico di lavoro delle query, interrompilo stop() e riprendilo in un secondo momento, durante un periodo di minore traffico, chiamando nuovamente. compute() Il calcolo continua da dove era stato interrotto.
Gestisci i riavvii correttamente: se il motore si riavvia mentre è in corso un calcolo dello schema, il calcolo passa a. Stopped Chiama per riprendere da dove era stata compute() interrotta. I progressi vengono preservati.
Database di grandi dimensioni: per i database con grandi volumi di archiviazione (più TB), il calcolo completo dello schema può richiedere molto tempo. È possibile avviare un calcolo, lasciarlo funzionare fino a un avanzamento del 10-20%, quindi interromperlo. I risultati parziali raccolti in questa finestra forniscono un utile esempio di schema con molte etichette, proprietà e triple già scoperte. Leggete lo schema parziale con pg_schema() mentre il calcolo è in corso o dopo l'arresto. Riprendi più tardi, quando il carico di lavoro lo consente.

Limitazioni

Le eliminazioni richiedono il ricalcolo: le etichette, le proprietà e le triple eliminate vengono rimosse dallo schema solo dopo il successivo ricalcolo completo. Fino ad allora, gli elementi eliminati potrebbero ancora apparire nei risultati dello schema.
OpenCypher solo: è possibile chiamare questa procedura solo tramite l'endpoint di query OpenCypher.
Impossibile eseguire il calcolo durante il caricamento di massa: Neptune rifiuta il calcolo dello schema mentre è attiva un'operazione di caricamento in blocco. Attiva il calcolo al termine del caricamento in blocco.

Output di esempio

L'esempio seguente mostra l'output dello schema per il set di dati air-routes:


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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

API di riepilogo del grafo

Statistiche DFE