Bulk-Loader-APIs der Neptune-Datenebene

Bulk-Load-Aktionen:

• StartLoaderJob (Aktion)

• GetLoaderJobStatus (Aktion)

• ListLoaderJobs (Aktion)

• CancelLoaderJob (Aktion)

Bulk-Load-Struktur:

• LoaderIdResult (Struktur)

StartLoaderJob (Aktion)

        Der AWS CLI-Name für diese API lautet: start-loader-job.

Startet einen Neptune-Bulk-Loader-Auftrag, um Daten aus einem Amazon-S3-Bucket in eine Neptune-DB-Instance zu laden. Weitere Informationen finden Sie unter Verwenden des Amazon-Neptune-Massen-Loaders für die Aufnahme von Daten.

Wenn diese Operation in einem Neptune-Cluster mit aktivierter IAM-Authentifizierung aufgerufen wird, muss mit dem IAM-Benutzer oder der Rolle, die die Anforderung gestellt hat, eine Richtlinie verknüpft sein, die die IAM-Aktion neptune-db:StartLoaderJob in diesem Cluster zulässt.

Anforderung

• dependencies   (in der CLI: --dependencies) – eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Dies ist ein optionaler Parameter, mit dem eine Ladeanforderung in der Warteschlange vom erfolgreichen Abschluss eines oder mehrerer früherer Aufträge in der Warteschlange abhängig gemacht werden kann.

  Neptune kann bis zu 64 Ladeanforderungen gleichzeitig in die Warteschlange einreihen, wenn die queueRequest-Parameter auf "TRUE" festgelegt sind. Mit dem Parameter dependencies können Sie die Ausführung einer solchen Anforderung in der Warteschlange vom erfolgreichen Abschluss einer oder mehrerer spezifizierter früherer Anforderungen in der Warteschlange abhängig machen.

  Wenn Ladung Job-A und Job-B beispielsweise unabhängig voneinander sind, mit Ladung Job-C aber erst nach Abschluss von Job-A und Job-B begonnen werden kann, gehen Sie wie folgt vor:

  1. Senden Sie load-job-A und load-job-B nacheinander in beliebiger Reihenfolge, und speichern Sie ihre Ladekennungen.

  2. Senden Sie load-job-C mit den Ladekennungen der beiden Aufträge in seinem dependencies-Feld:

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

  Aufgrund des Parameters dependencies startet der Bulk-Loader Job-C erst dann, nachdem Job-A und Job-B erfolgreich abgeschlossen wurden. Wenn einer von ihnen fehlschlägt, wird Job-C nicht ausgeführt und sein Status wird auf LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED gesetzt.

  Auf diese Weise können Sie mehrere Abhängigkeitsebenen einrichten, sodass das Fehlschlagen eines Auftrags dazu führt, dass alle Anforderungen, die direkt oder indirekt davon abhängig sind, abgebrochen werden.

• failOnError  (in der CLI: --fail-on-error) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  failOnError   –   Ein Flag für vollständiges Anhalten bei einem Fehler.

  Zulässige Werte: "TRUE", "FALSE".

  Standardwert: "TRUE".

  Wenn dieser Parameter auf "FALSE" gesetzt ist, versucht der Loader, alle Daten am angegebenen Speicherort zu laden, wobei alle Einträge mit Fehlern übersprungen werden.

  Wenn dieser Parameter auf "TRUE" eingestellt ist, stoppt der Loader, sobald ein Fehler auftritt. Bis zu diesem Punkt geladene Daten bleiben bestehen.

• format  (in der CLI: --format) –  Erforderlich: ein Format vom Typ string (UTF-8-kodierte Zeichenfolge).

  Das Format der Daten. Weitere Informationen zu Datenformaten für den Neptune-Befehl Loader finden Sie unter Datenformate zum Laden.

  Zulässige Werte

  • csv für das Gremlin-CSV-Datenformat.

  • opencypher für das openCypher-CSV-Datenformat.

  • ntriples für das N-Triples-RDF-Datenformat.

  • nquads für das N-Quads-RDF-Datenformat.

  • rdfxml für das RDF\XML-RDF-Datenformat.

  • turtle für das Turtle-RDF-Datenformat.

• iamRoleArn  (in der CLI: --iam-role-arn) –  Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der Amazon-Ressourcenname (ARN) für eine IAM-Rolle, die von der Neptune-DB-Instance für den Zugriff auf den S3-Bucket angenommen wird. Der hier angegebene ARN für die IAM-Rolle muss an den DB-Cluster angehängt werden (siehe Hinzufügen der IAM-Rolle zu einem Amazon-Neptune-Cluster).

• mode   (in der CLI: --mode) – ein Modus vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der Ladeauftragsmodus.

  Zulässige Werte: RESUME, NEW, AUTO.

  Standardwert: AUTO.

  • RESUME   –   Im Modus RESUME sucht der Loader nach einem vorherigen Ladevorgang aus dieser Quelle. Wenn der Loader einen vorherigen Ladevorgang findet, setzt er diesen Ladeauftrag fort. Wenn kein vorheriger Ladeauftrag gefunden wird, stoppt der Loader.

    Der Loader vermeidet das erneute Laden von Dateien, die in einem früheren Auftrag erfolgreich geladen wurden. Er versucht nur, fehlgeschlagene Dateien zu verarbeiten. Wenn Sie zuvor geladene Daten aus dem Neptune-Cluster gelöscht haben, werden diese Daten in diesem Modus nicht neu geladen. Wenn ein vorheriger Ladeauftrag alle Dateien aus derselben Quelle erfolgreich geladen hat, wird nichts neu geladen und der Loader gibt eine Erfolgsmeldung zurück.

  • NEW   –   Der Modus NEW erstellt eine neue Ladeanforderung unabhängig von vorherigen Ladevorgängen. Sie können diesen Modus verwenden, um alle Daten aus einer Quelle erneut zu laden, nachdem die zuvor aus Ihrem Neptune-Cluster geladenen Daten abgelegt wurden, oder um neue Daten zu laden, die in derselben Quelle verfügbar sind.

  • AUTO   –   Im Modus AUTO sucht der Loader nach einem vorherigen Ladeauftrag aus derselben Quelle. Wenn er einen Ladeauftrag findet, setzt er diesen Auftrag wie im Modus RESUME fort.

    Wenn der Loader keinen vorherigen Ladeauftrag aus derselben Quelle findet, lädt er alle Daten aus der Quelle, genau wie im Modus NEW.

• parallelism   (in der CLI: --parallelism) – eine Parallelität vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der optionale Parameter parallelism kann so eingestellt werden, dass die Anzahl der vom Massen-Ladeprozess verwendeten Threads reduziert wird.

  Zulässige Werte:

  • LOW –   Die Anzahl der verwendeten Threads entspricht der Anzahl der verfügbaren vCPUs dividiert durch 8.

  • MEDIUM –   Die Anzahl der verwendeten Threads entspricht der Anzahl der verfügbaren vCPUs dividiert durch 2.

  • HIGH –   Die Anzahl der verwendeten Threads entspricht der Anzahl der verfügbaren vCPUs.

  • OVERSUBSCRIBE –   Die Anzahl der verwendeten Threads entspricht der Anzahl der verfügbaren vCPUs multipliziert mit 2. Wenn dieser Wert verwendet wird, nimmt der Massen-Loader alle verfügbaren Ressourcen in Anspruch.

    Das bedeutet jedoch nicht, dass die Einstellung OVERSUBSCRIBE zu einer CPU-Auslastung von 100 % führt. Da der Ladevorgang E/A-gebunden ist, liegt die höchste zu erwartende CPU-Auslastung im Bereich von 60 bis 70 %.

  Standardwert: HIGH

  Die Einstellung parallelism kann manchmal beim Laden von openCypher-Daten zu einem Deadlock zwischen Threads führen. In diesem Fall gibt Neptune den Fehler LOAD_DATA_DEADLOCK zurück. Sie können das Problem im Allgemeinen beheben, indem Sie parallelism auf einen niedrigeren Wert festlegen und den Ladebefehl wiederholen.

• parserConfiguration   (in der CLI: --parser-configuration) – Ein Map-Array von Schlüssel-Wert-Paaren, wobei Folgendes gilt:

      Jeder Schlüssel ist eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

      Jeder Wert ist eine Zeichenfolge vom Typ string (eine UTF-8-kodierte Zeichenfolge).

  parserConfiguration   –   Ein optionales Objekt mit zusätzlichen Parser-Konfigurationswerten. Jeder der untergeordneten Parameter ist ebenfalls optional:

  • namedGraphUri  –   Das Standarddiagramm für alle RDF-Formate, wenn kein Graph angegeben ist (für nicht-Quads-Formate und NQUAD-Einträge ohne Graph).

    Der Standardwert ist https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph.

  • baseUri   –   Der Basis-URI für RDF/XML und Turtle-Formate.

    Der Standardwert ist https://aws.amazon.com/neptune/default.

  • allowEmptyStrings   –   Gremlin-Benutzer müssen beim Laden von CSV-Daten leere Zeichenfolgenwerte ("") als Knoten- und Kanteneigenschaften übergeben können. Wenn allowEmptyStrings auf false (Standard) festgelegt ist, werden diese leeren Zeichenfolgen als Nullen behandelt und nicht geladen.

    Wenn allowEmptyStrings auf true festgelegt ist, behandelt der Loader leere Zeichenfolgen als gültige Eigenschaftswerte und lädt sie entsprechend.

• queueRequest  (in der CLI: --queue-request) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  Dies ist ein optionaler Flag-Parameter, der angibt, ob die Ladeanforderung in die Warteschlange gestellt werden kann oder ob nicht.

  Sie müssen mit dem nächsten Ladeauftrag nicht warten, bis ein Ladeauftrag abgeschlossen ist, da Neptune bis zu 64 Aufträge gleichzeitig in die Warteschlange einreihen kann, wenn alle queueRequest-Parameter auf "TRUE" festgelegt sind. Die Aufträge werden nach dem First-In-First-Out (FIFO)-Prinzip eingereiht.

  Wenn der Parameter queueRequest weggelassen oder auf "FALSE" gesetzt wird, schlägt die Ladeanforderung fehl, wenn bereits ein anderer Ladeauftrag ausgeführt wird.

  Zulässige Werte: "TRUE", "FALSE".

  Standardwert: "FALSE".

• s3BucketRegion  (in der CLI: --s-3-bucket-region) –  Erforderlich: S3BucketRegion vom Typ string (UTF-8-kodierte Zeichenfolge).

  Die Amazon-Region Ihres S3-Buckets. Diese muss mit der Amazon-Region des DB-Clusters übereinstimmen.

• source  (in der CLI: --source) –  Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der Parameter source akzeptiert S3-URIs, die eine einzelne Datei, mehrere Dateien, einen Ordner oder mehrere Ordner angeben. Neptune lädt jede Datendatei in den Ordner, der angegeben ist.

  Der URI kann in einem der folgenden Formate angegeben sein.

  • 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)

  Das object-key-name-Element des URI entspricht dem Präfixparameter in einem ListObjects-API-Aufruf in S3. Es gibt alle Objekte im angegebenen S3-Bucket an, deren Namen mit diesem Präfix beginnen. Dabei kann es sich um eine einzelne Datei oder einen einzelnen Ordner oder mehrere Dateien und/oder Ordner handeln.

  Die angegebenen Ordner können mehrere Eckpunkt- und Kantendateien enthalten.

• updateSingleCardinalityProperties  (in der CLI: --update-single-cardinality-properties) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  updateSingleCardinalityProperties ist ein optionaler Parameter, der steuert, wie der Massen-Loader einen neuen Wert für Einzel-Kardinalität-Vertex- oder Edge-Eigenschaften behandelt. Dies wird für das Laden von openCypher-Daten nicht unterstützt.

  Zulässige Werte: "TRUE", "FALSE".

  Standardwert: "FALSE".

  Standardmäßig oder wenn updateSingleCardinalityProperties explizit als "FALSE" festgelegt ist, behandelt der Loader einen neuen Wert als Fehler, da er gegen die Einzel-Kardinalität verstößt.

  Wenn updateSingleCardinalityProperties als "TRUE" festgelegt ist, ersetzt der Massen-Loader auf der anderen Seite den vorhandenen Wert durch den neuen. Wenn in den Quelldateien, die geladen werden, mehrere Edge- oder Einzel-Kardinalität-Vertex-Eigenschaftswerte angegeben werden, kann der endgültige Wert am Ende des Massenladevorgangs jeder dieser neuen Werte sein. Der Loader stellt nur sicher, dass der vorhandene Wert durch einen der neuen ersetzt wurde.

• userProvidedEdgeIds  (in der CLI: --user-provided-edge-ids) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  Dieser Parameter ist nur erforderlich, wenn openCypher-Daten geladen werden, die Beziehungs-IDs enthalten. Er muss enthalten und auf True festgelegt sein, wenn openCypher-Beziehungs-IDs explizit in den Ladedaten angegeben werden (empfohlen).

  Wenn userProvidedEdgeIds fehlt oder auf True festgelegt ist, muss in jeder Beziehungsdatei im Ladevorgang die Spalte :ID vorhanden sein.

  Wenn userProvidedEdgeIds vorhanden und auf False festgelegt ist, dürfen Beziehungsdateien im Ladevorgang die Spalte :ID nicht enthalten. Stattdessen generiert der Neptune-Loader automatisch eine ID für jede Beziehung.

  Wenn Beziehungs-IDs explizit angegeben sind, kann der Loader den Ladevorgang nach der Behebung eines Fehlers in den CSV-Daten fortsetzen, ohne bereits geladene Beziehungen erneut laden zu müssen. Wenn Beziehungs-IDs nicht explizit angegeben sind, kann der Loader einen fehlgeschlagenen Ladevorgang nach der Korrektur einer Beziehungsdatei nicht fortsetzen und muss stattdessen alle Beziehungen erneut laden.

Antwort

• payload   – Erforderlich: Es handelt sich um ein Map-Array von Schlüssel-Wert-Paaren, wobei Folgendes gilt:

      Jeder Schlüssel ist eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

      Jeder Wert ist eine Zeichenfolge vom Typ string (eine UTF-8-kodierte Zeichenfolge).

  Enthält ein loadId-Name-Wert-Paar, das einen Bezeichner für den Ladevorgang bereitstellt.

• status   – Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der HTTP-Rückgabecode, der den Status des Ladeauftrags angibt.

Fehler

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• S3Exception

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

GetLoaderJobStatus (Aktion)

        Der AWS CLI-Name für diese API lautet: get-loader-job-status.

Ruft Statusinformationen zu einem angegebenen Ladeauftratg ab. Neptune verfolgt die letzten 1.024 Massenladeaufgaben und speichert pro Auftrag die letzten 10.000 Fehlerdetails.

Weitere Informationen finden Sie unter Neptune-Loader-Get-Status-API.

Wenn diese Operation in einem Neptune-Cluster mit aktivierter IAM-Authentifizierung aufgerufen wird, muss mit dem IAM-Benutzer oder der Rolle, die die Anforderung gestellt hat, eine Richtlinie verknüpft sein, die die IAM-Aktion neptune-db:GetLoaderJobStatus in diesem Cluster zulässt.

Anforderung

• details  (in der CLI: --details) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  Flag, das angibt, ob neben dem Gesamtstatus weitere Details einbezogen werden sollen (TRUEoder FALSE; die Standardeinstellung lautet FALSE).

• errors  (in der CLI: --errors) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  Flag, das angibt, ob eine Liste der aufgetretenen Fehler einbezogen werden soll (TRUEoderFALSE; die Standardeinstellung lautet FALSE).

  Die Fehlerliste ist segmentiert. Die Parameter page und errorsPerPage erlauben Ihnen das seitenweise Durchlaufen aller Fehler.

• errorsPerPage   (in der CLI: --errors-per-page) – PositiveInteger vom Typ integer (eine 32-Bit-Ganzzahl mit Vorzeichen), mindestens 1 ?st?.

  Die Anzahl der auf jeder Seite zurückgegebenen Fehler (eine positive Ganzzahl; die Standardeinstellung lautet 10). Dieser Wert ist nur gültig, wenn der errors-Parameter auf TRUE eingestellt ist.

• loadId  (in der CLI: --load-id) –  Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Die Lade-ID des Ladeauftrags, dessen Status abgerufen werden soll.

• page   (in der CLI: --page) – PositiveInteger vom Typ integer (eine 32-Bit-Ganzzahl mit Vorzeichen), mindestens 1 ?st?.

  Die Fehlerseitenzahl (eine positive Ganzzahl; die Standardeinstellung lautet 1). Dieser Wert ist nur gültig, wenn der errors-Parameter auf TRUE eingestellt ist.

Antwort

• payload   – Erforderlich Dokument vom Typ document (protokollunabhängiger offener Inhalt, der durch ein JSON-ähnliches Datenmodell repräsentiert wird).

  Statusinformationen über den Ladeauftrag in einem Layout, das wie folgt aussehen könnte:

  {
            "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   – Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Den HTTP-Statuscode für die Antwort der Anforderung.

Fehler

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

ListLoaderJobs (Aktion)

        Der AWS CLI-Name für diese API lautet: list-loader-jobs.

Ruft eine Liste der loadIds für alle aktiven Ladeaufträge ab.

Wenn diese Operation in einem Neptune-Cluster mit aktivierter IAM-Authentifizierung aufgerufen wird, muss mit dem IAM-Benutzer oder der Rolle, die die Anforderung gestellt hat, eine Richtlinie verknüpft sein, die die IAM-Aktion neptune-db:ListLoaderJobs in diesem Cluster zulässt.

Anforderung

• includeQueuedLoads  (in der CLI: --include-queued-loads) – boolescher Wert vom Typ boolean (boolescher Wert (wahr oder falsch)).

  Ein optionaler Parameter, mit dem die Ladekennungen von Ladeanforderungen in der Warteschlange ausgeschlossen werden können, wenn eine Liste von Ladekennungen angefordert wird, indem der Parameter auf FALSE festgelegt wird. Der Standardwert ist TRUE.

• limit  (in der CLI: --limit) –  ein ListLoaderJobsInputLimitInteger vom Typ integer (eine 32-Bit-Ganzzahl mit Vorzeichen), zwischen 1 und 100 ?st?s.

  Die Anzahl der Lade-IDs, die aufgelistet werden sollen. Muss eine positive Ganzzahl sein, die größer als Null und kleiner als 100 (Standardeinstellung) ist.

Antwort

• payload – Erforderlich: Ein LoaderIdResult-Objekt.

  Die angeforderte Liste der Auftrags-IDs.

• status   – Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Gibt den Status der Anforderung der Auftragsliste zurück.

Fehler

• UnsupportedOperationException

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• InternalFailureException

• ClientTimeoutException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

CancelLoaderJob (Aktion)

        Der AWS CLI-Name für diese API lautet: cancel-loader-job.

Bricht einen angegebenen Ladeauftrag ab. Dies ist eine HTTP-DELETE-Anforderung. Weitere Informationen finden Sie unter Neptune-Loader-Get-Status-API.

Wenn diese Operation in einem Neptune-Cluster mit aktivierter IAM-Authentifizierung aufgerufen wird, muss mit dem IAM-Benutzer oder der Rolle, die die Anforderung gestellt hat, eine Richtlinie verknüpft sein, die die IAM-Aktion neptune-db:CancelLoaderJob in diesem Cluster zulässt.

Anforderung

• loadId  (in der CLI: --load-id) –  Erforderlich: eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Die ID des zu löschenden Ladeauftrags.

Antwort

• status   – eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Der Abbruchstatus.

Fehler

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

Bulk-Load-Struktur:

LoaderIdResult (Struktur)

Enthält eine Liste von Lade-IDs.

Felder

• loadIds – Dies ist eine Zeichenfolge vom Typ string (UTF-8-kodierte Zeichenfolge).

  Eine Liste von Lade-IDs.