API dello strumento di caricamento in blocco per il piano dati Neptune

• StartLoaderJob (azione)

• GetLoaderJobStatus (azione)

• ListLoaderJobs (azione)

• CancelLoaderJob (azione)

• LoaderIdResult (struttura)

• dependencies (nella CLI: --dependencies): una stringa di tipo string (una stringa con codifica UTF-8).

  Si tratta di un parametro facoltativo che può rendere subordinata una richiesta di caricamento in coda al completamento di una o più attività precedenti nella coda.

  Neptune può accodare fino a 64 richieste di caricamento alla volta, se i relativi parametri queueRequest sono impostati su "TRUE". Il parametro dependencies consente di rendere l'esecuzione di tale richiesta in coda dipendente dal completamento corretto di una o più richieste precedenti specificate nella coda.

  Ad esempio, se Job-A e Job-B del caricamento sono indipendenti l'una dall'altra, ma Job-C richiede che Job-A e Job-B siano completate prima del suo avvio, procedere come segue:

  1. Inviare load-job-A e load-job-B una dopo l'altra in qualsiasi ordine e salvare i loro id di caricamento.

  2. Inviare load-job-C con gli id di caricamento delle due attività nel campo dependencies:

    "dependencies" : ["(job_A_load_id)", "(job_B_load_id)"]

  A causa del parametro dependencies, lo strumento di caricamento in blocco non avvia Job-C fino a quando Job-A e Job-B non sono state completate correttamente. Se una di queste attività non riesce, l'attività non verrà eseguita e il suo stato sarà impostato su LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

  È possibile impostare più livelli di dipendenza in questo modo, in modo che l'errore di un'attività causi l'annullamento di tutte le richieste direttamente o indirettamente dipendenti da essa.

• failOnError (nella CLI: --fail-on-error): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  failOnError: un flag per attivare un arresto completo in caso di errore.

  Valori consentiti: "TRUE", "FALSE".

  Valore predefinito: "TRUE".

  Quando questo parametro è impostato su "FALSE", lo strumento di caricamento tenta di caricare tutti i dati nella posizione specificata, saltando eventuali voci con errori.

  Quando questo parametro è impostato su "TRUE", lo dello strumento di caricamento si arresta non appena rileva un errore. I dati caricati fino a quel punto persistono.

• format (nella CLI: --format): Obbligatorio: un formato di tipo string (una stringa con codifica UTF-8).

  Il formato dei dati. Per ulteriori informazioni sui formati di dati per il comando Loader di Neptune, consulta Formati dei dati da caricare.

  Valori consentiti

  • csv per il formato dei dati CSV Gremlin.

  • opencypher per il formato dei dati CSV openCypher.

  • ntriples per il formato dei dati N-Triples RDF.

  • nquads per il formato dei dati N-Quads RDF.

  • rdfxml per il formato dei dati RDF\XML RDF.

  • turtle per il formato dei dati Turtle RDF.

• iamRoleArn (nella CLI: --iam-role-arn): Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  Il nome della risorsa Amazon (ARN) per un ruolo IAM che deve essere assunto dall'istanza database Neptune per l'accesso al bucket S3. L'ARN del ruolo IAM fornito qui deve essere collegato al cluster database (vedi Aggiunta del ruolo IAM a un cluster Amazon Neptune).

• mode (nella CLI: --mode): una modalità di tipo string (una stringa con codifica UTF-8).

  Modalità del processo di caricamento

  Valori consentiti: RESUME, NEW, AUTO.

  Valore predefinito: AUTO.

  • RESUME: in modalità RESUME, lo strumento di caricamento cerca un caricamento precedente da questa origine e, se ne trova uno, riprende l'attività di caricamento. Se non viene trovata alcuna attività di caricamento precedente, lo strumento di caricamento si arresta.

    Lo strumento di caricamento evita di ricaricare i file caricati correttamente in un'attività precedente. Tenta di elaborare solo i file non caricati. Se sono stati eliminati i dati caricati in precedenza dal cluster Neptune, tali dati non vengono ricaricati in questa modalità. Se un processo di caricamento precedente ha caricato correttamente tutti i file dalla stessa origine, nulla viene ricaricato e lo strumento di caricamento restituisce un risultato positivo.

  • NEW: in modalità NEW viene creata una nuova richiesta di caricamento, indipendentemente da eventuali caricamenti precedenti. Questa modalità può essere utilizzata per ricaricare tutti i dati provenienti da un'origine dopo che sono stati eliminati dati caricati precedentemente dal cluster Neptune o per caricare nuovi dati disponibili nella stessa origine.

  • AUTO: in modalità AUTO, lo strumento di caricamento cerca un'attività di caricamento precedente dalla stessa origine e, se ne trova una, riprende tale attività, proprio come in modalità RESUME.

    Se lo strumento di caricamento non trova un'attività di caricamento precedente dalla stessa origine, carica tutti i dati dall'origine, proprio come in modalità NEW.

• parallelism (nella CLI: --parallelism): un parallelismo di tipo string (una stringa con codifica UTF-8).

  Il parametro facoltativo parallelism può essere impostato per ridurre il numero di thread utilizzati dall'attività di caricamento in blocco.

  Valori consentiti:

  • LOW: il numero di thread utilizzati è il numero di vCPU disponibili diviso per 8.

  • MEDIUM: il numero di thread utilizzati è il numero di vCPU disponibili diviso per 2.

  • HIGH: il numero di thread utilizzati corrisponde al numero di vCPU disponibili.

  • OVERSUBSCRIBE: il numero di thread utilizzati è il numero di vCPU disponibili moltiplicato per 2. Se viene utilizzato questo valore, lo strumento di caricamento in blocco occupa tutte le risorse disponibili.

    Ciò non significa, tuttavia, che l'impostazione OVERSUBSCRIBE comporti un utilizzo della CPU al 100%. Poiché l'operazione di caricamento è limitata dalle attività di I/O, l'utilizzo massimo della CPU previsto è compreso tra il 60% e il 70%.

  Valore predefinito: HIGH

  L'impostazione parallelism a volte può causare un deadlock tra i thread durante il caricamento dei dati openCypher. Quando ciò accade, Neptune restituisce l'errore LOAD_DATA_DEADLOCK. Di solito è possibile risolvere il problema impostando parallelism su un valore inferiore e riprovando il comando di caricamento.

• parserConfiguration  (nella CLI: --parser-configuration): un array di mappa con coppie chiave-valore in cui:

      Ogni chiave è una stringa di tipo string (una stringa con codifica UTF-8).

      Ogni valore è una stringa di tipo string (una stringa con codifica UTF-8).

  parserConfiguration: un oggetto opzionale con valori di configurazione del parser aggiuntivi. Ciascuno dei parametri figlio è anche facoltativo:

  • namedGraphUri: il grafo predefinito per tutti i formati RDF quando non viene specificato alcun grafo (per formati non quads e voci NQUAD senza grafo).

    Il valore predefinito è https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph.

  • baseUri: l'URI di base per i formati RDF/XML e Turtle.

    Il valore predefinito è https://aws.amazon.com/neptune/default.

  • allowEmptyStrings: gli utenti di Gremlin devono essere in grado di passare valori di stringa vuoti ("") come proprietà dei nodi e degli archi durante il caricamento di dati CSV. Se allowEmptyStrings è impostato su false (valore predefinito), le stringhe vuote vengono trattate come valori null e non vengono caricate.

    Se allowEmptyStrings è impostato su true, lo strumento di caricamento considera le stringhe vuote come valori di proprietà validi e le carica di conseguenza.

• queueRequest (nella CLI: --queue-request): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  Si tratta di un parametro flag opzionale che indica se la richiesta di caricamento può essere accodata o meno.

  Non è necessario attendere il completamento di un processo di caricamento prima di emettere quello successivo, perché Neptune può accodare fino a 64 processi alla volta, a condizione che i relativi parametri queueRequest siano tutti impostati su "TRUE". L'ordine di accodamento dei processi sarà first-in-first-out (FIFO).

  Se il parametro queueRequest viene omesso o impostato su "FALSE", la richiesta di caricamento avrà esito negativo se un'altra attività di caricamento è già in esecuzione.

  Valori consentiti: "TRUE", "FALSE".

  Valore predefinito: "FALSE".

• s3BucketRegion (nella CLI: --s-3-bucket-region): Obbligatorio: un valore S3BucketRegion di tipo string (una stringa con codifica UTF-8).

  La regione Amazon del bucket S3. Deve corrispondere alla regione Amazon del cluster database.

• source (nella CLI: --source): Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  Il parametro source accetta un URI S3 che identifica un singolo file, più file, una cartella o più cartelle. Neptune carica ogni file di dati in qualsiasi cartella specificata.

  l'URI può essere in uno dei seguenti formati.

  • s3://(bucket_name)/(object-key-name)

  • https://s3.amazonaws.com/(bucket_name)/(object-key-name)

  • https://s3.us-east-1.amazonaws.com/(bucket_name)/(object-key-name)

  L'elemento object-key-name dell'URI è equivalente al parametro prefix in una chiamata API ListObjects di S3. Identifica tutti gli oggetti nel bucket S3 specificato i cui nomi iniziano con il prefisso specificato. Può trattarsi di un singolo file o una singola cartella oppure di più file e/o cartelle.

  La cartella o le cartelle specificate possono contenere più file di vertici e più file di archi.

• updateSingleCardinalityProperties (nella CLI: --update-single-cardinality-properties): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  updateSingleCardinalityProperties è un parametro facoltativo che controlla il modo in cui lo strumento di caricamento in blocco tratta un nuovo valore per le proprietà di vertici o archi a cardinalità singola. Non è supportato per il caricamento di dati openCypher.

  Valori consentiti: "TRUE", "FALSE".

  Valore predefinito: "FALSE".

  Come impostazione predefinita o quando updateSingleCardinalityProperties è impostato esplicitamente su "FALSE", lo strumento di caricamento considera un nuovo valore come un errore, perché viola la cardinalità singola.

  Quando updateSingleCardinalityProperties è impostato invece su "TRUE", lo strumento di caricamento in blocco sostituisce il valore esistente con quello nuovo. Se valori di proprietà multipli edge o vertice a cardinalità singola vengono forniti nei file di origine caricati, il valore finale alla fine del caricamento in blocco potrebbe essere uno qualsiasi di questi nuovi valori. Lo strumento di caricamento garantisce solo che il valore esistente è stato sostituito da uno di quelli nuovi.

• userProvidedEdgeIds (nella CLI: --user-provided-edge-ids): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  Questo parametro è richiesto solo quando si caricano dati openCypher che contengono ID di relazione. Deve essere incluso e impostato su True se gli ID delle relazioni openCypher vengono forniti esplicitamente nei dati da caricare (consigliato).

  Se userProvidedEdgeIds è assente o è impostato su True, in ogni file delle relazioni all'interno del caricamento deve esistere una colonna :ID.

  Se userProvidedEdgeIds è presente ed è impostato su False, i file delle relazioni all'interno del caricamento non devono contenere una colonna :ID. Lo strumento di caricamento Neptune genera automaticamente un ID per ogni relazione.

  È utile fornire in modo esplicito gli ID delle relazioni in modo che lo strumento di caricamento possa riprendere il caricamento dopo la correzione dell'errore nei dati CSV, senza dover ricaricare le relazioni già caricate. Se gli ID delle relazioni non sono stati assegnati in modo esplicito, lo strumento di caricamento non può riprendere un caricamento non riuscito se è stato necessario correggere un file delle relazioni, perciò dovrà ricaricare tutte le relazioni.

• payload: Obbligatorio: un array di mappa con coppie chiave-valore in cui:

      Ogni chiave è una stringa di tipo string (una stringa con codifica UTF-8).

      Ogni valore è una stringa di tipo string (una stringa con codifica UTF-8).

  Contiene una coppia nome-valore loadId che fornisce un identificatore per l'operazione di caricamento.

• status: Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  Il codice HTTP restituito che indica lo stato del processo di caricamento.

Errori

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• S3Exception

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• details (nella CLI: --details): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  Flag che indica se includere o meno i dettagli oltre allo stato generale (TRUE o FALSE, l'impostazione predefinita è FALSE).

• errors (nella CLI: --errors): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  Flag che indica se includere o meno un elenco di errori riscontrati (TRUE o FALSE, l'impostazione predefinita è FALSE).

  L'elenco degli errori è paginato. I parametri page ed errorsPerPage consentono di esaminare tutti gli errori.

• errorsPerPage (nella CLI: --errors-per-page): un valore PositiveInteger di tipo integer (numero intero a 32 bit con segno), almeno 1 ?st?.

  Il numero di errori restituiti in ogni pagina (un numero intero positivo; l'impostazione predefinita è 10). È valido solo se il parametro errors è impostato su TRUE.

• loadId (nella CLI: --load-id): Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  L'ID del processo di caricamento di cui ottenere lo stato.

• page (nella CLI: --page): un valore PositiveInteger di tipo integer (numero intero a 32 bit con segno), almeno 1 ?st?.

  Il numero della pagina di errore (un numero intero positivo; l'impostazione predefinita è 1). È valido solo se il parametro errors è impostato su TRUE.

• payload: Obbligatorio: un documento di tipo document (un contenuto aperto indipendente dal protocollo rappresentato da un modello di dati simile a JSON).

  Informazioni sullo stato del processo di caricamento, con un layout simile al seguente:

  {
            "status" : "200 OK",
            "payload" : {
              "feedCount" : [
                {
                  "LOAD_FAILED" : (number)
                }
              ],
              "overallStatus" : {
                "fullUri" : "s3://(bucket)/(key)",
                "runNumber" : (number),
                "retryNumber" : (number),
                "status" : "(string)",
                "totalTimeSpent" : (number),
                "startTime" : (number),
                "totalRecords" : (number),
                "totalDuplicates" : (number),
                "parsingErrors" : (number),
                "datatypeMismatchErrors" : (number),
                "insertErrors" : (number),
              },
              "failedFeeds" : [
                {
                  "fullUri" : "s3://(bucket)/(key)",
                  "runNumber" : (number),
                  "retryNumber" : (number),
                  "status" : "(string)",
                  "totalTimeSpent" : (number),
                  "startTime" : (number),
                  "totalRecords" : (number),
                  "totalDuplicates" : (number),
                  "parsingErrors" : (number),
                  "datatypeMismatchErrors" : (number),
                  "insertErrors" : (number),
                }
              ],
              "errors" : {
                "startIndex" : (number),
                "endIndex" : (number),
                "loadId" : "(string),
                "errorLogs" : [ ]
              }
            }
          }

• status: Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  Il codice di risposta HTTP per la richiesta.

Errori

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• includeQueuedLoads (nella CLI: --include-queued-loads): un valore booleano di tipo boolean [un valore booleano (vero o falso)].

  Un parametro facoltativo che può essere utilizzato per escludere gli ID di caricamento delle richieste di caricamento in coda quando viene richiesto un elenco di ID di caricamento mediante l'impostazione del parametro su FALSE. Il valore predefinito è TRUE.

• limit (nella CLI: --limit): un valore ListLoaderJobsInputLimitInteger di tipo integer (numero intero a 32 bit con segno), non meno di 1 o più di 100 ?st?s.

  Il numero di ID di caricamento da elencare. Deve essere un numero intero positivo maggiore di zero e non superiore a 100 (valore predefinito).

• payload: obbligatorio: un oggetto LoaderIdResult.

  L'elenco richiesto di ID dei processi.

• status: Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  Restituisce lo stato della richiesta di elenco dei processi.

Errori

• UnsupportedOperationException

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• InternalFailureException

• ClientTimeoutException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• loadId (nella CLI: --load-id): Obbligatorio: una stringa di tipo string (una stringa con codifica UTF-8).

  L'ID del processo di caricamento da eliminare.

• status: una stringa di tipo string (una stringa con codifica UTF-8).

  Lo stato di annullamento.

Errori

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

Campi

• loadIds: questa è una stringa di tipo string (una stringa con codifica UTF-8).

  Un elenco di ID di caricamento.