API de chargeur en bloc du plan de données Neptune

• StartLoaderJob (action)

• GetLoaderJobStatus (action)

• ListLoaderJobs (action)

• CancelLoaderJob (action)

• LoaderIDResult (structure)

• dependencies (dans la CLI : --dependencies) : chaîne de type : string (chaîne encodée en UTF-8).

  Il s'agit d'un paramètre facultatif qui peut subordonner une demande de chargement en file d'attente à la réussite d'une ou de plusieurs tâches précédentes dans la file d'attente.

  Neptune peut mettre en file d'attente jusqu'à 64 requêtes de chargement à la fois, si leurs paramètres queueRequest sont définis sur "TRUE". Le paramètre dependencies vous permet de rendre l'exécution d'une telle requête en file d'attente dépendante de la réussite d'une ou de plusieurs requêtes précédentes spécifiées dans la file d'attente.

  Par exemple, si les charges Job-A et Job-B sont indépendantes l'une de l'autre, mais que la charge Job-C a besoin que Job-A et Job-B soient terminées avant de commencer, procédez comme suit :

  1. Soumettez load-job-A et load-job-B l'une après l'autre dans n'importe quel ordre, et enregistrez leurs ID de chargement.

  2. Soumettez load-job-C avec les ID de chargement des deux tâches dans son domaine dependencies :

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

  En raison du paramètre dependencies, le chargeur en bloc ne démarrera pas Job-C avant que Job-A et Job-B soient terminées avec succès. Si l'une des d'eux échoue, Job-C ne sera pas exécuté et son statut sera défini sur LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

  Vous pouvez configurer plusieurs niveaux de dépendance de cette façon, de sorte que l'échec d'une tâche entraîne l'annulation de toutes les demandes qui en dépendent directement ou indirectement.

• failOnError (dans la CLI : --fail-on-error) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  failOnError : indicateur permettant d'activer un arrêt complet au niveau d'une erreur.

  Valeurs autorisées : "TRUE", "FALSE".

  Valeur par défaut : "TRUE".

  Lorsque ce paramètre est défini sur "FALSE", le chargeur essaie de charger toutes les données à l'emplacement spécifié, en ignorant les entrées contenant des erreurs.

  Lorsque ce paramètre est défini sur "TRUE", le chargeur s'arrête dès qu'il rencontre une erreur. Les données chargées jusqu'à ce point persistent.

• format (dans la CLI : --format) : obligatoire : format de type : string (chaîne encodée en UTF-8).

  Format des données. Pour plus d'informations sur les formats de données pour la commande Loader Neptune, consultez Formats de chargement de données.

  Valeurs autorisées

  • csv pour le format de données CSV Gremlin.

  • opencypher pour le format de données CSV openCypher.

  • ntriples pour le format de données N-Triples RDF.

  • nquads pour le format de données N-Quads RDF.

  • rdfxml pour le format de données RDF/XML RDF.

  • turtle pour le format de données Turtle RDF.

• iamRoleArn (dans la CLI : --iam-role-arn) : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  Amazon Resource Name (ARN) d'un rôle IAM qui doit être endossé par l'instance de base de données Neptune pour accéder au compartiment S3. L'ARN du rôle IAM fourni ici doit être attaché au cluster de bases de données (consultez Ajout du rôle IAM à un cluster Amazon Neptune).

• mode (dans la CLI : --mode) : mode de type : string (chaîne encodée en UTF-8).

  Mode de tâche de chargement.

  Valeurs autorisées : RESUME, NEW, AUTO

  Valeur par défaut : AUTO.

  • RESUME : en mode REPRISE, le chargeur recherche un chargement précédent à partir de cette source et, s'il en trouve un, reprend cette tâche de chargement. Si aucune tâche de chargement précédente n'est trouvée, le chargeur s'arrête.

    Le chargeur évite de recharger les fichiers qui ont été chargés avec succès lors d'une tâche précédente. Il essaie uniquement de traiter les fichiers ayant échoué. Si vous aviez supprimé des données précédemment chargées à partir de votre cluster Neptune, ces données ne sont pas rechargées dans ce mode. Si une tâche de chargement précédente a chargé tous les fichiers de la même source avec succès, rien n'est rechargé, et le chargeur renvoie une réussite.

  • NEW : le mode NOUVEAU crée une autre demande de chargement sans tenir compte des chargements précédents. Vous pouvez utiliser ce mode pour recharger toutes les données d'une source après la suppression de données précédemment chargées à partir de votre cluster Neptune ou pour charger de nouvelles données disponibles sur la même source.

  • AUTO : en mode AUTO, le chargeur recherche une tâche de chargement précédente à partir de la même source, et s'il en trouve une, reprend cette tâche, exactement comme en mode RESUME.

    Si le chargeur ne trouve pas de tâche de chargement précédente à partir de la même source, il charge toutes les données de la source, exactement comme en mode NEW.

• parallelism (dans la CLI : --parallelism) : parallélisme de type : string (chaîne encodée en UTF-8).

  Le paramètre facultatif parallelism peut être défini de façon à réduire le nombre de threads utilisés par le processus de chargement en bloc.

  Valeurs autorisées :

  • LOW : le nombre de threads utilisés est le nombre de vCPU disponibles divisé par huit.

  • MEDIUM : le nombre de threads utilisés est le nombre de vCPU disponibles divisé par deux.

  • HIGH : le nombre de threads utilisés est le même que le nombre de vCPU disponibles.

  • OVERSUBSCRIBE : le nombre de threads utilisés est le nombre de vCPU disponibles multiplié par deux. Si cette valeur est utilisée, le chargeur en bloc accepte toutes les ressources disponibles.

    Cela ne signifie toutefois pas que le paramètre OVERSUBSCRIBE entraîne une utilisation du CPU à 100 %. L'opération de chargement étant liée aux E/S, le taux d'utilisation du CPU le plus élevé possible se situe dans une plage de 60 % à 70 %.

  Valeur par défaut : HIGH

  Le paramètre parallelism peut parfois entraîner un blocage entre les threads lors du chargement des données openCypher. Lorsque cela se produit, Neptune renvoie le message d'erreur LOAD_DATA_DEADLOCK. Vous pouvez généralement résoudre le problème en définissant un paramètre parallelism inférieur et en soumettant la commande de chargement à une nouvelle tentative.

• parserConfiguration (dans la CLI : --parser-configuration)  : tableau de mappage de paires clé-valeur où :

      Chaque clé est une chaîne de type : string (chaîne encodée en UTF-8).

      Chaque valeur est une chaîne de type : string (chaîne encodée en UTF-8).

  parserConfiguration : objet facultatif avec des valeurs de configuration d'analyseur supplémentaires. Chacun des paramètres enfants est également facultatif :

  • namedGraphUri : graphe par défaut pour tous les formats RDF quand aucun graphe n'est spécifié (pour les formats autres que quadruplets et les entrées NQUAD sans graphe).

    La valeur par défaut est https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph.

  • baseUri : URI de base pour les formats RDF/XML et Turtle.

    La valeur par défaut est https://aws.amazon.com/neptune/default.

  • allowEmptyStrings : les utilisateurs de Gremlin doivent être en mesure de transmettre des valeurs de chaîne vides ("") en tant que propriétés de nœud et d'arête lors du chargement de données CSV. Si la valeur allowEmptyStrings est définie sur false (valeur par défaut), ces chaînes vides sont traitées comme des valeurs nulles et ne sont pas chargées.

    Si la valeur allowEmptyStrings est définie sur true, le chargeur traite les chaînes vides comme des valeurs de propriété valides et les charge en conséquence.

• queueRequest (dans la CLI : --queue-request) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  Il s'agit d'un paramètre d'indicateur facultatif qui indique si la demande de chargement peut être mise en file d'attente ou non.

  Vous n'avez pas besoin d'attendre qu'une tâche de chargement soit terminée avant d'émettre la suivante, car Neptune peut mettre en file d'attente jusqu'à 64 tâches à la fois, si leurs paramètres queueRequest sont tous définis sur "TRUE". L'ordre des tâches en file d'attente repose sur une structure FIFO (premier entré, premier sorti).

  Si le paramètre queueRequest est omis ou défini sur "FALSE", la demande de chargement échouera si une autre tâche de chargement est déjà en cours d'exécution.

  Valeurs autorisées : "TRUE", "FALSE".

  Valeur par défaut : "FALSE".

• s3BucketRegion (dans la CLI : --s-3-bucket-region) : obligatoire : élément S3BucketRegion de type : string (chaîne encodée en UTF-8).

  Région Amazon du compartiment S3. Elle doit correspondre à la région Amazon du cluster de bases de données.

• source (dans la CLI : --source) : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  Le paramètre source accepte un URI S3 qui identifie un seul fichier, plusieurs fichiers, un dossier ou plusieurs dossiers. Neptune charge tous les fichiers de données dans n'importe quel dossier spécifié.

  L'URI peut être à l'un des formats suivants.

  • 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'élément object-key-name de l'URI est équivalent au paramètre prefix dans un appel d'API ListObjects S3. Il identifie tous les objets du compartiment S3 spécifié dont le nom commence par ce préfixe. Il peut s'agir d'un seul fichier, d'un seul dossier, de plusieurs fichiers et/ou de plusieurs dossiers.

  Le dossier spécifié peut contenir plusieurs fichiers de sommet et plusieurs fichiers d'arête.

• updateSingleCardinalityProperties (dans la CLI : --update-single-cardinality-properties) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  updateSingleCardinalityProperties est un paramètre facultatif qui contrôle la façon dont le chargeur en bloc traite une nouvelle valeur pour les propriétés de sommet ou d'arête à cardinalité unique. Il n'est pas pris en charge pour le chargement de données openCypher.

  Valeurs autorisées : "TRUE", "FALSE".

  Valeur par défaut : "FALSE".

  Par défaut, ou lorsque updateSingleCardinalityProperties est explicitement défini sur "FALSE", le chargeur traite une nouvelle valeur comme une erreur, car elle ne respecte pas la cardinalité unique.

  En revanche, lorsque updateSingleCardinalityProperties est défini sur "TRUE", le chargeur en bloc remplace la valeur existante par la nouvelle. Si plusieurs valeurs de propriété de sommet à cardinalité unique ou d'arête sont fournies dans le ou les fichiers source en cours de chargement, la valeur finale à l'issue du chargement en bloc peut être une de ces nouvelles valeurs. Le chargeur garantit uniquement que la valeur existante a été remplacée par une des nouvelles.

• userProvidedEdgeIds (dans la CLI : --user-provided-edge-ids) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  Ce paramètre n'est obligatoire que lors du chargement de données openCypher contenant des ID de relation. Il doit être inclus et défini sur True lorsque les ID de relation openCypher sont explicitement fournis dans les données de chargement (recommandé).

  Quand userProvidedEdgeIds est absent ou défini sur True, une colonne :ID doit être présente dans chaque fichier de relations inclus dans le chargement.

  Quand userProvidedEdgeIds est présent et défini sur False, les fichiers de relations inclus dans le chargement ne doivent pas contenir de colonne :ID. Au lieu de cela, le chargeur Neptune génère automatiquement un ID pour chaque relation.

  Il est utile de fournir des ID de relation de manière explicite afin que le chargeur puisse reprendre le chargement après correction d'une erreur dans les données CSV, sans avoir à recharger les relations déjà chargées. Si aucun ID de relation n'a été attribué explicitement, le chargeur ne peut pas reprendre un chargement défaillant si un fichier de relation a dû être corrigé, et doit à la place recharger toutes les relations.

• payload : obligatoire : tableau de mappage de paires clé-valeur où :

      Chaque clé est une chaîne de type : string (chaîne encodée en UTF-8).

      Chaque valeur est une chaîne de type : string (chaîne encodée en UTF-8).

  Contient une paire nom-valeur loadId qui fournit un identifiant pour l'opération de chargement.

• status : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  Code de retour HTTP indiquant le statut de la tâche de chargement.

Erreurs

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• S3Exception

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• details (dans la CLI : --details) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  Indicateur signalant s'il faut ou non inclure des détails autres que le statut général (TRUE ou FALSE ; la valeur par défaut est FALSE).

• errors (dans la CLI : --errors) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  Indicateur signalant s'il faut ou non inclure une liste des erreurs rencontrées (TRUE ou FALSE ; la valeur par défaut est FALSE).

  La liste d'erreurs est paginée. Les paramètres page et errorsPerPage vous permettent de parcourir toutes les erreurs.

• errorsPerPage (dans la CLI :--errors-per-page) : élément PositiveInteger de type : integer (entier signé de 32 bits), au moins 1 ?st?.

  Nombre d'erreurs renvoyées sur chaque page (entier positif ; la valeur par défaut est 10). Valide uniquement si le paramètre errors est défini sur TRUE.

• loadId (dans la CLI : --load-id) : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  ID de chargement de la tâche de chargement dont vous souhaitez obtenir le statut.

• page (dans la CLI :--page) : élément PositiveInteger de type : integer (entier signé de 32 bits), au moins 1 ?st?.

  Numéro de la page d'erreur (entier positif ; la valeur par défaut est 1). Valide uniquement lorsque le paramètre errors est défini sur TRUE.

• payload : obligatoire : document de type : document (contenu ouvert indépendant du protocole représenté par un modèle de données de type JSON).

  Informations sur le statut de la tâche de chargement, dans une mise en page qui pourrait ressembler à ceci :

  {
            "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 : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  Code de réponse HTTP de la demande.

Erreurs

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• includeQueuedLoads (dans la CLI : --include-queued-loads) : valeur booléenne de type : boolean (valeur booléenne : true ou false).

  Paramètre facultatif qui peut être utilisé pour exclure les ID de chargement des demandes de chargement en file d'attente lorsqu'une liste d'ID de chargement est demandée en définissant ce paramètre sur FALSE. La valeur par défaut est TRUE.

• limit (dans la CLI :--limit) : élément ListLoaderJobsInputLimitInteger de type : integer (entier signé de 32 bits), compris entre 1 et 100 ?st?s.

  Nombre d'ID de chargement à répertorier. Doit être un entier positif supérieur à zéro et inférieur ou égal à 100 (valeur par défaut).

• payload : obligatoire : objet LoaderIdResult.

  Liste des ID de tâche demandés.

• status : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  Renvoie le statut de la demande d'affichage des tâches.

Erreurs

• UnsupportedOperationException

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• InternalFailureException

• ClientTimeoutException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• loadId (dans la CLI : --load-id) : obligatoire : chaîne de type : string (chaîne encodée en UTF-8).

  ID de la tâche à supprimer.

• status : chaîne de type : string (chaîne encodée en UTF-8).

  Statut de l'annulation.

Erreurs

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

Champs

• loadIds : chaîne de type : string (chaîne encodée en UTF-8).

  Liste des ID de chargement.