Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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 ](visualization-graph-explorer.md) 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()`](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/custom-algorithms-property-graph-schema.html) 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 ](neptune-graph-summary.md) 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()`— richiede`neptune-db:ReadDataViaQuery`. + `CALL neptune.graph.pg_schema.compute()`— richiede `neptune-db:ReadDataViaQuery` e`neptune-db:WriteDataViaQuery`. + `CALL neptune.graph.pg_schema.stop()`— richiede `neptune-db:ReadDataViaQuery` e`neptune-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. **Example 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:** ------ #### [ 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: ** 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 come`String`), tutti i tipi osservati vengono elencati nell'`datatypes`array. ### Schema di calcolo Attiva un calcolo dello schema in background. **Sintassi:** ------ #### [ AWS CLI ] ``` aws neptunedata execute-open-cypher-query \ --endpoint-url https://{{your-neptune-endpoint}}:{{port}} \ --open-cypher-query "CALL neptune.graph.pg_schema.compute()" ``` Con parametro di concorrenza opzionale: ``` 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()' ``` Con parametro di concorrenza opzionale: ``` 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})' ``` ------ **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 calcolo`InProgress`, 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:** ------ #### [ 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()' ``` ------ **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 corrente`progressPercentage`. ## 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 chiama`neptune.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 chiamata`neptune.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 chiama`compute()`. + `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"] } } } } }] } ```