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à. # neptune.read () Neptune supporta `CALL` una `neptune.read` procedura per leggere i dati da Amazon S3 e quindi eseguire una query OpenCypher (lettura, inserimento, aggiornamento) utilizzando i dati. La procedura restituisce ogni riga del file come riga di variabile di risultato dichiarata. Utilizza le credenziali IAM del chiamante per accedere ai dati in Amazon S3. Vedi [Gestione delle autorizzazioni per neptune.read ()](access-graph-opencypher-21-extensions-s3-read-permissions.md) per configurare le autorizzazioni. La AWS regione del bucket Amazon S3 deve trovarsi nella stessa regione in cui si trova l'istanza. Attualmente, le letture tra regioni non sono supportate. **Sintassi** ``` CALL neptune.read( { source: "string", format: "parquet/csv", concurrency: 10 } ) YIELD row ... ``` **Input** + **source** (obbligatorio): URI Amazon S3 per un **singolo** oggetto. Il prefisso Amazon S3 per più oggetti non è supportato. + **formato** (obbligatorio) - `parquet` e `csv` sono supportati. + Maggiori dettagli sul formato Parquet supportato sono disponibili in[Tipi di colonne Parquet supportati](access-graph-opencypher-21-extensions-s3-read-parquet.md#access-graph-opencypher-21-extensions-s3-read-parquet-column-types). + Per ulteriori informazioni sul formato csv supportato, consulta[Formato di caricamento dei dati openCypher](bulk-load-tutorial-format-opencypher.md). + **concurrency** (opzionale): digitare un numero intero pari o superiore a 0. Impostazione predefinita: 0. Speciifica il numero di thread da utilizzare per leggere il file. Se il valore è 0, verrà utilizzato il numero massimo di thread consentito dalla risorsa. Per Parquet, si consiglia di impostare un numero di gruppi di righe. **Output** Il neptune.read restituisce: + **riga** - Tipo:map + Ogni riga del file, dove le chiavi sono le colonne e i valori sono i dati trovati in ogni colonna. + Puoi accedere ai dati di ogni colonna come una proprietà access (`row.col`). ## Le migliori pratiche per neptune.read () Le operazioni di lettura di Neptune S3 possono richiedere molta memoria. Utilizza tipi di istanze adatti ai carichi di lavoro di produzione, come indicato in [Scelta dei tipi di istanze per Amazon Neptune](instance-types.md). L'utilizzo della memoria e le prestazioni delle `neptune.read()` richieste sono influenzati da una serie di fattori come la dimensione del file, il numero di colonne, il numero di righe e il formato del file. A seconda della struttura, i file di piccole dimensioni (ad esempio, file CSV di dimensioni pari o inferiori a 100 MB, file Parquet di dimensioni pari o inferiori a 20 MB) possono funzionare in modo affidabile sulla maggior parte dei tipi di istanze adatti alla produzione, mentre i file più grandi possono richiedere una notevole quantità di memoria che i tipi di istanze più piccoli non sono in grado di fornire. Durante il test di questa funzionalità, si consiglia di iniziare con file di piccole dimensioni e di ridimensionarla gradualmente per garantire che il carico di lavoro di lettura possa essere adattato alle dimensioni dell'istanza. Se notate che `neptune.read()` le richieste portano a out-of-memory eccezioni o al riavvio dell'istanza, prendete in considerazione la possibilità di suddividere i file in blocchi più piccoli, ridurre la complessità dei file o passare a tipi di istanze più grandi. # Esempi di query che utilizzano il parquet La seguente query di esempio restituisce il numero di righe in un determinato file Parquet: ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row RETURN count(row) ``` È possibile eseguire l'esempio di query utilizzando l'`execute-open-cypher-query`operazione in AWS CLI eseguendo il codice seguente: ``` aws neptunedata execute-open-cypher-query \ --open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN count(row)" \ --endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182 ``` Una query può essere flessibile nelle operazioni eseguite con le righe lette da un file Parquet. Ad esempio, la seguente query crea un nodo con un campo impostato sui dati trovati nel file Parquet: ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **avvertimento** Non è considerata buona prassi utilizzare una clausola di grandi dimensioni che produca risultati come quella `MATCH(n)` precedente a una clausola. `CALL` Ciò comporterebbe una query di lunga durata, dovuta al prodotto incrociato tra le soluzioni in entrata delle clausole precedenti e le righe lette da neptune.read. Si consiglia di avviare la query con neptune.read. `CALL` ## Tipi di colonne Parquet supportati **Tipi di dati Parquet:** + NULL + BOOLEAN + FLOAT + DOUBLE + STRING + NUMERO INTERO CON SEGNO: UINT8, UINT16, UINT32 UINT64 + MAP: supporta solo un livello. Non supporta nidificato. + LIST: supporta solo un livello. Non supporta nidificato. **Tipi di dati specifici per Neptune:** A differenza delle intestazioni delle colonne delle proprietà del formato CSV, le intestazioni delle colonne delle proprietà del formato Parquet devono avere solo i nomi delle proprietà, quindi non è necessario avere i nomi dei tipi né la cardinalità. Esistono tuttavia alcuni tipi di colonna speciali nel formato Parquet che richiedono l'annotazione nei metadati, tra cui il tipo Any, il tipo Date, il tipo DateTime e il tipo Geometry. L'oggetto seguente è un esempio dell'annotazione dei metadati richiesta per i file contenenti colonne di questi tipi speciali: ``` "metadata": { "anyTypeColumns": ["UserCol1"], "dateTypeColumns": ["UserCol2"], "dateTimeTypeColumns": ["UserCol3"], "geometryTypeColumns": ["UserCol4"] } ``` Di seguito sono riportati i dettagli sul payload previsto associato a questi tipi: + Nelle colonne utente è supportato un tipo di colonna Any. Un tipo Any è un tipo «zucchero sintattico» per tutti gli altri tipi che supportiamo. È estremamente utile se una colonna utente contiene più tipi. Il payload di un valore Any type è un elenco di stringhe json come segue:`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, che ha un campo di valore e un campo di tipo in ogni singola stringa json. Il valore di cardinalità di una colonna Any è impostato, il che significa che la colonna può accettare più valori. + Neptune supporta i seguenti tipi in qualsiasi tipo: Bool (o Boolean), Byte, Short, Int, Long,,,, Float, Double, Date UnsignedByte UnsignedShort UnsignedInt, UnsignedLong DateTime, String e Geometry. + Il tipo vettoriale non è supportato in nessun tipo. + Nidato Qualsiasi tipo non è supportato. Ad esempio, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`. + Le colonne di tipo Date e DateTime sono supportate nelle colonne utente. Il payload di queste colonne deve essere fornito come stringhe secondo il formato XSD o uno dei formati seguenti: + yyyy-MM-dd + YYYY-MM-DTHH:mm + aaaa-mm-ggh: mm: ss + aaaa-mm-ggH:mm:ssz + aaaa-mm-ggH:mm:ss.ssz + aaaa-MM-GGTHH:mm:ss [\$1\$1-] hhmm + YYYY-MM-GGTHH:mm:ss.sss [\$1\$1-] hhmm + Nelle colonne utente è supportato un tipo di colonna Geometry. Il payload di queste colonne deve contenere solo primitive Geometry di tipo Point, fornite come stringhe nel formato Wekonful text (WKT). Ad esempio, POINT (30 10) sarebbe un valore Geometry valido. ## Esempio di output del parquet Dato un file Parquet come questo: ``` Parquet Type: int8 int16 int32 int64 float double string +--------+---------+-------------+----------------------+------------+------------+----------+ | Byte | Short | Int | Long | Float | Double | String | |--------+---------+-------------+----------------------+------------+------------+----------| | -128 | -32768 | -2147483648 | -9223372036854775808 | 1.23456 | 1.23457 | first | | 127 | 32767 | 2147483647 | 9223372036854775807 | nan | nan | second | | 0 | 0 | 0 | 0 | -inf | -inf | third | | 0 | 0 | 0 | 0 | inf | inf | fourth | +--------+---------+-------------+----------------------+------------+------------+----------+ ``` Ecco un esempio dell'output restituito da neptune.read utilizzando la seguente query: ``` aws neptunedata execute-open-cypher-query \ --open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN row" \ --endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182 ``` ``` { "results": [{ "row": { "Float": 1.23456, "Byte": -128, "Int": -2147483648, "Long": -9223372036854775808, "String": "first", "Short": -32768, "Double": 1.2345678899999999 } }, { "row": { "Float": "NaN", "Byte": 127, "Int": 2147483647, "Long": 9223372036854775807, "String": "second", "Short": 32767, "Double": "NaN" } }, { "row": { "Float": "-INF", "Byte": 0, "Int": 0, "Long": 0, "String": "third", "Short": 0, "Double": "-INF" } }, { "row": { "Float": "INF", "Byte": 0, "Int": 0, "Long": 0, "String": "fourth", "Short": 0, "Double": "INF" } }] } ``` Attualmente, non è possibile impostare un'etichetta di nodo o di spigolo su un campo di dati proveniente da un file Parquet. Si consiglia di suddividere le interrogazioni in più interrogazioni, una per ogni etichetta/tipo. ``` CALL neptune.read({source: '', format: 'parquet'}) YIELD row WHERE row.`~label` = 'airport' CREATE (n:airport) CALL neptune.read({source: '', format: 'parquet'}) YIELD row WHERE row.`~label` = 'country' CREATE (n:country) ``` # Esempi di query utilizzando CSV In questo esempio, la query restituisce il numero di righe in un determinato file CSV: ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row RETURN count(row) ``` È possibile eseguire l'esempio di query utilizzando l' execute-open-cypher-queryoperazione in AWS CLI eseguendo il codice seguente: ``` aws neptunedata execute-open-cypher-query \ --open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN count(row)" \ --endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182 ``` Una query può essere flessibile nelle operazioni eseguite con le righe lette da un file CSV. Ad esempio, la seguente query crea un nodo con un campo impostato sui dati di un file CSV: ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **avvertimento** Non è considerata buona prassi utilizzare una clausola di grandi dimensioni che produca risultati come MATCH (n) prima di una clausola CALL. Ciò comporterebbe una query di lunga durata a causa del prodotto incrociato tra le soluzioni in entrata delle clausole precedenti e le righe lette da neptune.read. Si consiglia di avviare la query con CALL neptune.read. ## Intestazioni di colonna di proprietà È possibile specificare una colonna (`:`) per una proprietà utilizzando la sintassi seguente. Per i nomi dei tipi non viene fatta distinzione tra maiuscole e minuscole. Se all'interno del nome di una proprietà sono presenti due punti, è necessario evitarlo facendola precedere da una barra rovesciata:. `\:` ``` propertyname:type ``` **Nota** Lo spazio, la virgola, i caratteri di ritorno e di nuova riga non sono consentiti nelle intestazioni delle colonne, quindi i nomi delle proprietà non possono includere questi caratteri. È possibile specificare una colonna per un tipo di matrice aggiungendo `[]` al tipo: ``` propertyname:type[] ``` Le proprietà edge possono avere solo un singolo valore e verrà generato un errore se viene specificato un tipo di array o un secondo valore. L'esempio seguente mostra l'intestazione di colonna per una proprietà denominata age di tipo Int: ``` age:Int ``` Ogni riga del file dovrà avere un valore intero in quella posizione o essere lasciata vuota. Le matrici di stringhe sono consentite, ma le stringhe di un array non possono includere il carattere punto e virgola (`;`) a meno che non venga eliminato utilizzando una barra rovesciata (). `\;` ## Tipi di colonne CSV supportati + **BOOL (o BOOLEAN)** - Valori consentiti: true, false. Indica un campo Booleano. Qualsiasi valore diverso da true verrà considerato falso. + **FLOAT** - Intervallo: virgola mobile IEEE 754 a 32 bit, inclusi Infinity, INF, -Infinity, -INF e NaN (). not-a-number + **DOUBLE** - Intervallo: virgola mobile IEEE 754 a 64 bit, inclusi Infinity, INF, -Infinity, -INF e NaN (). not-a-number + **STRINGA -** + Le virgolette sono facoltative. I caratteri restituiti da virgole, newline e carriage vengono automaticamente eliminati se sono inclusi in una stringa racchiusa tra virgolette doppie («). Esempio: «Hello, World». + Per includere le virgolette in una stringa tra virgolette, puoi evitare le virgolette usandone due di seguito: Esempio: «Hello «" World" "». + Le matrici di stringhe sono consentite, ma le stringhe di una matrice non possono includere il carattere punto e virgola (;) a meno che non venga eliminato utilizzando una barra rovesciata (\$1;). + Se desideri racchiudere le stringhe in una matrice con le virgolette, devi racchiudere l'intera matrice con una serie di virgolette. Esempio: «String one; String 2; String 3". + **DATE, DATETIME** - I valori datetime possono essere forniti nel formato XSD o in uno dei seguenti formati: + yyyy-MM-dd + YYYY-MM-DTHH:mm + aaaa-mm-ggh: mm: ss + aaaa-mm-ggH:mm:ssz + aaaa-mm-ggH:mm:ss.ssz + aaaa-MM-GGTHH:mm:ss [\$1\$1-] hhmm + YYYY-MM-GGTHH:mm:ss.sss [\$1\$1-] hhmm + **NUMERO INTERO CON SEGNO -** + Byte: da -128 a 127 + Breve: da -32768 a 32767 + Int: da -2^31 a 2^31-1 + Lungo: da -2^63 a 2^63-1 **Tipi di colonne specifici per Nettuno:** + Un tipo di colonna Any è supportato nelle colonne utente. Un tipo Any è un tipo «zucchero sintattico» per tutti gli altri tipi che supportiamo. È estremamente utile se una colonna utente contiene più tipi. Il payload di un valore Any type è un elenco di stringhe json come segue:`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, che ha un campo di valore e un campo di tipo in ogni singola stringa json. L'intestazione di colonna di un tipo Any è PropertyName:Any. Il valore di cardinalità di una colonna Any è impostato, il che significa che la colonna può accettare più valori. + Neptune supporta i seguenti tipi in qualsiasi tipo: Bool (o Boolean), Byte, Short, Int, Long,,,, Float, Double, Date UnsignedByte UnsignedShort UnsignedInt, UnsignedLong DateTime, String e Geometry. + Il tipo vettoriale non è supportato in nessun tipo. + Nidato Qualsiasi tipo non è supportato. Ad esempio, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`. + Nelle colonne utente è supportato un tipo di colonna Geometry. Il payload di queste colonne deve contenere solo primitive Geometry di tipo Point, fornite come stringhe nel formato Wekonful text (WKT). Ad esempio, POINT (30 10) sarebbe un valore Geometry valido. ## Esempio di output CSV Dato il seguente file CSV: ``` colA:byte,colB:short,colC:int,colD:long,colE:float,colF:double,colG:string -128,-32768,-2147483648,-9223372036854775808,1.23456,1.23457,first 127,32767,2147483647,9223372036854775807,nan,nan,second 0,0,0,0,-inf,-inf,third 0,0,0,0,inf,inf,fourth ``` Questo esempio mostra l'output restituito da neptune.read utilizzando la seguente query: ``` aws neptunedata execute-open-cypher-query \ --open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN row" \ --endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182 ``` ``` { "results": [{ "row": { "colD": -9223372036854775808, "colC": -2147483648, "colE": 1.23456, "colB": -32768, "colF": 1.2345699999999999, "colG": "first", "colA": -128 } }, { "row": { "colD": 9223372036854775807, "colC": 2147483647, "colE": "NaN", "colB": 32767, "colF": "NaN", "colG": "second", "colA": 127 } }, { "row": { "colD": 0, "colC": 0, "colE": "-INF", "colB": 0, "colF": "-INF", "colG": "third", "colA": 0 } }, { "row": { "colD": 0, "colC": 0, "colE": "INF", "colB": 0, "colF": "INF", "colG": "fourth", "colA": 0 } }] } ``` Attualmente, non è possibile impostare un'etichetta di nodo o di bordo su un campo di dati proveniente da un file CSV. Si consiglia di suddividere le interrogazioni in più interrogazioni, una per ogni etichetta/tipo. ``` CALL neptune.read({source: '', format: 'csv'}) YIELD row WHERE row.`~label` = 'airport' CREATE (n:airport) CALL neptune.read({source: '', format: 'csv'}) YIELD row WHERE row.`~label` = 'country' CREATE (n:country) ``` # Gestione delle autorizzazioni per neptune.read () ## Politiche IAM richieste Per eseguire le query OpenCypher che utilizzano`neptune.read()`, è necessario disporre delle autorizzazioni appropriate per accedere ai dati nel database Neptune. Le `ReadDataViaQuery` interrogazioni di sola lettura richiedono l'azione. Le interrogazioni che modificano i dati richiedono l'inserimento o `WriteDataViaQuery` l'eliminazione. `DeleteDataViaQuery` L'esempio seguente concede tutte e tre le azioni sul cluster specificato. Inoltre, sono necessarie le autorizzazioni per accedere al bucket S3 contenente i file di dati. L'informativa sulla politica di Neptunes3Access concede le autorizzazioni S3 richieste: + **`s3:ListBucket`**: necessario per verificare l'esistenza del bucket e il contenuto dell'elenco. + **`s3:GetObject`**: necessario per accedere all'oggetto specificato in modo che il suo contenuto possa essere letto per l'integrazione nelle query OpenCypher. Se il tuo bucket S3 utilizza la crittografia lato server con, devi anche concedere le autorizzazioni KMS. AWS KMS L'KMSAccess informativa sulla politica di Neptunes3 consente a Neptune di decrittografare i dati e generare chiavi dati quando si accede a oggetti S3 crittografati. La condizione limita le operazioni KMS alle richieste provenienti dai servizi S3 e RDS nella tua regione. + **`kms:Decrypt`**: necessario per eseguire la decrittografia dell'oggetto crittografato in modo che i relativi dati possano essere letti da Neptune. + **`kms:GenerateDataKey`**: Richiesto anche dall'API S3 utilizzata per recuperare gli oggetti da leggere. ``` { "Sid": "NeptuneQueryAccess", "Effect": "Allow", "Action": [ "neptune-db:ReadDataViaQuery", "neptune-db:WriteDataViaQuery", "neptune-db:DeleteDataViaQuery" ], "Resource": "arn:aws:neptune-db:::/*" }, { "Sid": "NeptuneS3Access", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::neptune-read-bucket", "arn:aws:s3:::neptune-read-bucket/*" ] }, { "Sid": "NeptuneS3KMSAccess", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": "arn:aws:kms:::key/", "Condition": { "StringEquals": { "kms:ViaService": [ "s3..amazonaws.com", "rds..amazonaws.com" ] } } } ``` ## Prerequisiti importanti Queste autorizzazioni e prerequisiti garantiscono l'integrazione sicura e affidabile dei dati S3 nelle query OpenCypher, mantenendo al contempo controlli di accesso e misure di protezione dei dati adeguati. + **Autenticazione IAM**: questa funzionalità è supportata solo per i cluster Neptune con autenticazione IAM abilitata. Consulta [la sezione Protezione del database Amazon Neptune](security.md) per istruzioni dettagliate su come creare e connettersi a cluster abilitati all'autenticazione IAM. + **Endpoint VPC**: + È necessario un endpoint VPC di tipo gateway per Amazon S3 per consentire a Neptune di comunicare con Amazon S3. + Per utilizzare la AWS KMS crittografia personalizzata nella query, AWS KMS è necessario un endpoint VPC di tipo interfaccia per cui consentire a Neptune di comunicare con. AWS KMS + Per istruzioni dettagliate su come configurare questo endpoint, consulta [Creazione dell'endpoint VPC Amazon S3](bulk-load-tutorial-IAM.md).