API del programa de carga masiva de plano de datos de Neptune

• StartLoaderJob (acción)

• GetLoaderJobStatus (acción)

• ListLoaderJobs (acción)

• CancelLoaderJob (acción)

• LoaderIdResult (estructura)

• dependencies (en la CLI: --dependencies): una cadena, del tipo: string (una cadena codificada con UTF-8).

  Se trata de un parámetro opcional que puede supeditar una solicitud de carga en cola a la finalización correcta de uno o varios trabajos anteriores de la cola.

  Neptune puede poner en cola hasta 64 solicitudes de carga a la vez, si sus parámetros queueRequest están configurados en "TRUE". El parámetro dependencies le permite hacer que la ejecución de dicha solicitud en cola dependa de la finalización correcta de una o más solicitudes anteriores especificadas en la cola.

  Por ejemplo, si las cargas Job-A y Job-B son independientes entre sí, pero la carga Job-C necesita Job-A y Job-B debe terminar antes de que comience, proceda de la siguiente manera:

  1. Envíe load-job-A y load-job-B uno tras otro en cualquier orden, y guarde sus identificadores de carga.

  2. Envíe load-job-C con los identificadores de carga de los dos trabajos en su campo dependencies:

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

  Debido al parámetro dependencies, el programa de carga en bloque no iniciará Job-C hasta que Job-A y Job-B se hayan completado correctamente. Si se produce un error en alguno de ellos, Job-C no se ejecutará y su estado se establecerá en LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

  Puede configurar varios niveles de dependencia de esta manera, de modo que el error de un trabajo provoque la cancelación de todas las solicitudes que dependen directa o indirectamente de él.

• failOnError (en la CLI: --fail-on-error): un booleano, del tipo: boolean (un valor booleano [true o false]).

  failOnError: un indicador para activar la detención total al encontrar un error.

  Valores permitidos: "TRUE" y "FALSE".

  Valor predeterminado: "TRUE".

  Cuando este parámetro se establece en "FALSE", el programa de carga intenta cargar todos los datos de la ubicación especificada, omitiendo cualquier entrada con errores.

  Cuando este parámetro se establece en "TRUE", el programa de carga se detiene en cuanto encuentra un error. Los datos cargados hasta ese momento persisten.

• format (en la CLI: --format): obligatorio: un formato, del tipo: string (una cadena codificada con UTF-8).

  El formato de los datos. Para obtener más información sobre los formatos de los datos para el comando Loader de Neptune, consulte Formatos de los datos de carga.

  Valores permitidos

  • csv para el formato de datos CSV de Gremlin.

  • opencypher para el formato de datos CSV de openCypher.

  • ntriples para el formato de datos RDF N-Triples.

  • nquads para el formato de datos RDF N-Quads.

  • rdfxml para el formato de datos RDF RDF\XML.

  • turtle para el formato de datos RDF de Turtle.

• iamRoleArn (en la CLI: --iam-role-arn): obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El nombre de recurso de Amazon (ARN) para que la instancia de base de datos de Neptune asuma el rol de IAM para obtener acceso al bucket de S3. El ARN del rol de IAM que se indica aquí debe adjuntarse al clúster de base de datos (consulte Adición del rol de IAM a un clúster de Amazon Neptune).

• mode (en la CLI: --mode): un modo, del tipo: string (una cadena codificada con UTF-8).

  El modo de tarea de carga.

  Valores permitidos: RESUME, NEW, AUTO.

  Valor predeterminado: AUTO.

  • RESUME: en el modo RESUME, el programa de carga busca una carga anterior de este origen y, si encuentra una, reanuda ese trabajo de carga. Si no se encuentra ningún trabajo de carga anterior, el programa de carga se detiene.

    El programa de carga evita la recarga de archivos cargados correctamente en un trabajo anterior. Solo intenta procesar los archivos con errores. Si ha eliminado los datos cargados anteriormente del clúster de Neptune, esos datos no se vuelven a cargar en este modo. Si un trabajo de carga anterior ha cargado todos los archivos del mismo origen correctamente, no se vuelve a cargar nada y el programa de carga devuelve una operación correcta.

  • NEW: en el modo NEW, crea una solicitud de carga, independientemente de cualquier carga anterior. Puede utilizar este modo para volver a cargar todos los datos de un origen después de descartar los datos cargados anteriormente desde el clúster de Neptune o bien para cargar nuevos datos disponibles en el mismo origen.

  • AUTO: en el modo AUTO, el programa de carga busca un trabajo de carga anterior del mismo origen y, si encuentra uno, lo reanuda, igual que en el modo RESUME.

    Si el programa de carga no encuentra un trabajo de carga anterior del mismo origen, carga todos los datos del origen, al igual que en el modo NEW.

• parallelism (en la CLI: --parallelism): un paralelismo, del tipo: string (una cadena codificada con UTF-8).

  El parámetro parallelism opcional que se puede establecer para reducir el número de subprocesos utilizados por el proceso de carga masiva.

  Valores permitidos:

  • LOW: el número de subprocesos utilizados es el número de vCPU disponibles dividido entre 8.

  • MEDIUM: el número de subprocesos utilizados es el número de vCPU disponibles dividido entre 2.

  • HIGH: el número de subprocesos utilizados es el mismo número de vCPU disponibles.

  • OVERSUBSCRIBE: el número de subprocesos utilizados es el número de vCPU disponibles multiplicado por 2. Si se utiliza este valor, el programa de carga masiva absorbe todos los recursos disponibles.

    Sin embargo, esto no significa que el ajuste de OVERSUBSCRIBE dé como resultado un uso del 100 % de la CPU. Dado que la operación de carga está vinculada a la E/S, la máxima utilización de la CPU que cabe esperar se sitúa entre el 60 y el 70 %.

  Valor predeterminado: HIGH

  En ocasiones, este ajuste de parallelism puede provocar un bloqueo entre los subprocesos al cargar datos de openCypher. Cuando esto ocurre, Neptune devuelve el error LOAD_DATA_DEADLOCK. Por lo general, puede solucionar el problema configurando parallelism en un ajuste inferior y volviendo a intentar ejecutar el comando de carga.

• parserConfiguration (en la CLI: --parser-configuration): es una matriz de mapeo de pares de clave-valor donde:

      Cada clave es una cadena, del tipo: string (una cadena codificada con UTF-8).

      Cada valor es una cadena, del tipo: string (una cadena codificada con UTF-8).

  parserConfiguration: objeto opcional con valores de configuración de analizador adicionales. Cada uno de los parámetros secundarios también es opcional:

  • namedGraphUri: el gráfico predeterminado para todos los formatos RDF cuando no se especifica ningún gráfico (para formatos no QUAD y entradas NQUAD sin gráfico).

    El valor predeterminado es https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph.

  • baseUri: el URI base para los formatos RDF/XML y Turtle.

    El valor predeterminado es https://aws.amazon.com/neptune/default.

  • allowEmptyStrings: los usuarios de Gremlin deben ser capaces de pasar valores de cadenas vacías (“”) como propiedades de nodo y borde al cargar datos CSV. Si allowEmptyStrings se establece en false (el valor predeterminado), estas cadenas vacías se tratan como nulas y no se cargan.

    Si allowEmptyStrings se establece en true, el programa de carga trata las cadenas vacías como valores de propiedad válidos y las carga en consecuencia.

• queueRequest (en la CLI: --queue-request): un booleano, del tipo: boolean (un valor booleano [true o false]).

  Se trata de un parámetro de indicador opcional que indica si la solicitud de carga se puede poner en cola o no.

  No tiene que esperar a que se complete un trabajo de carga antes de emitir el siguiente, porque Neptune puede poner en cola hasta 64 trabajos a la vez, siempre que sus parámetros queueRequest estén configurados en "TRUE". El orden de cola de los trabajos será el primero en entrar es el primero en salir (FIFO).

  Si el parámetro queueRequest se omite o se establece en "FALSE", se producirá un error en la solicitud de carga si ya se está ejecutando otro trabajo de carga.

  Valores permitidos: "TRUE" y "FALSE".

  Valor predeterminado: "FALSE".

• s3BucketRegion (en la CLI: --s-3-bucket-region): obligatorio: una S3BucketRegion, del tipo: string (una cadena codificada con UTF-8).

  La región de Amazon del bucket S3. Debe coincidir con la región de Amazon del clúster de base de datos.

• source (en la CLI: --source): obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El parámetro source acepta un URI de S3 que identifica un solo archivo, varios archivos, una carpeta o varias carpetas. Neptune carga todos los archivos de datos de cualquier carpeta especificada.

  El URI puede tener cualquiera de los siguientes formatos:

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

  El elemento object-key-name del URI equivale al parámetro prefix de una llamada a la API ListObjects de S3. Identifica todos los objetos del bucket de S3 especificado cuyos nombres comienzan con ese prefijo. Puede ser un único archivo o carpeta o varios archivos o carpetas.

  La carpeta o carpetas especificadas pueden contener varios archivos de vértice y varios archivos de borde.

• updateSingleCardinalityProperties (en la CLI: --update-single-cardinality-properties): un booleano, del tipo: boolean (un valor booleano [true o false]).

  updateSingleCardinalityProperties es un parámetro opcional que controla cómo el programa de carga masiva trata un nuevo valor para las propiedades de vértice o borde de cardinalidad única. Esto no se admite para cargar datos de openCypher.

  Valores permitidos: "TRUE" y "FALSE".

  Valor predeterminado: "FALSE".

  De forma predeterminada, o cuando updateSingleCardinalityProperties está configurado explícitamente en "FALSE", el programa de carga trata un nuevo valor como un error, porque infringe la cardinalidad única.

  Por el contrario, cuando updateSingleCardinalityProperties está configurado en "TRUE", el programa de carga en bloque reemplaza el valor existente por el nuevo. Si se proporcionan varios valores de propiedades de vértices de borde o de cardinalidad única en los archivos origen que se están cargando, el valor final al terminar la carga masiva podría ser cualquiera de esos nuevos valores. El programa de carga solo garantiza que el valor existente se ha reemplazado por uno de los nuevos.

• userProvidedEdgeIds (en la CLI: --user-provided-edge-ids): un booleano, del tipo: boolean (un valor booleano [true o false]).

  Este parámetro solo es necesario cuando se cargan datos de openCypher que incluyen identificadores de relación. Debe incluirse y configurarse en True cuando los identificadores de relación de openCypher se proporcionen de forma explícita en los datos de carga (recomendado).

  Si userProvidedEdgeIds está ausente o se establece en True, debe haber una columna :ID en todos los archivos de relaciones de la carga.

  Cuando userProvidedEdgeIds está presente y se establece en False, los archivos de relaciones de la carga no deben contener ninguna columna :ID. En su lugar, el programa de carga de Neptune genera automáticamente un identificador para cada relación.

  Resulta útil proporcionar los identificadores de relación de forma explícita para que el programa de carga pueda reanudar la carga una vez que se haya corregido un error en los datos CSV, sin tener que volver a cargar ninguna relación que ya se haya cargado. Si los identificadores de relación no se han asignado de forma explícita, el programa de carga no puede reanudar una carga fallida si se ha tenido que corregir algún archivo de relación y, en su lugar, debe volver a cargar todas las relaciones.

• payload: obligatorio: es una matriz de mapeo de pares de clave-valor donde:

      Cada clave es una cadena, del tipo: string (una cadena codificada con UTF-8).

      Cada valor es una cadena, del tipo: string (una cadena codificada con UTF-8).

  Incluye un par de nombre-valor loadId que proporciona un identificador para la operación de carga.

• status: obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El código de devolución HTTP que indica el estado del trabajo de carga.

Errores

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException (Excepción de demasiadas solicitudes)

• UnsupportedOperationException

• InternalFailureException

• S3Exception

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• details (en la CLI: --details): un booleano, del tipo: boolean (un valor booleano [true o false]).

  Indicador que especifica si se deben incluir o no detalles más allá del estado general (TRUE o FALSE; el valor predeterminado es FALSE).

• errors (en la CLI: --errors): un booleano, del tipo: boolean (un valor booleano [true o false]).

  Indicador que especifica si se debe incluir o no una lista de los errores encontrados (TRUE o FALSE; el valor predeterminado es FALSE).

  Dicha lista está paginada. Los parámetros page y errorsPerPage le permiten desplazarse por todos los errores.

• errorsPerPage (en la CLI: --errors-per-page): un PositiveInteger, del tipo: integer (un valor entero firmado de 32 bits), al menos 1 ?st?.

  El número de errores devueltos en cada página (un entero positivo; el valor predeterminado es 10). Solo es válido si el parámetro errors está establecido en TRUE.

• loadId (en la CLI: --load-id): obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El ID de carga del trabajo de carga del que obtener el estado.

• page (en la CLI: --page): un PositiveInteger, del tipo: integer (un valor entero firmado de 32 bits), al menos 1 ?st?.

  El número de la página de error (un entero positivo; el valor predeterminado es 1). Solo es válido si el parámetro errors está establecido en TRUE.

• payload: obligatorio: un documento, del tipo: document (un contenido abierto independiente del protocolo representado por un modelo de datos similar a JSON).

  Información de estado sobre el trabajo de carga, en un diseño que podría tener este aspecto:

  {
            "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: obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  Código de respuesta HTTP de la solicitud.

Errores

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException (Excepción de demasiadas solicitudes)

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• includeQueuedLoads (en la CLI: --include-queued-loads): un booleano, del tipo: boolean (un valor booleano [true o false]).

  Un parámetro opcional que se puede utilizar para excluir los identificadores de carga de las solicitudes de carga en cola cuando se solicita una lista de identificadores de carga estableciendo el parámetro en FALSE. El valor predeterminado es TRUE.

• limit (en la CLI: --limit): un ListLoaderJobsInputLimitInteger, del tipo: integer (un valor entero firmado de 32 bits), no inferior a 1 ni superior a 100 ?st?s.

  El número de ID de carga que se van a incluir en la lista. Debe ser un entero positivo mayor que cero y no mayor que 100 (que es el valor predeterminado).

• payload: obligatorio: objeto LoaderIdResult.

  La lista solicitada de ID de trabajo.

• status: obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  Devuelve el estado de la solicitud de la lista de trabajos.

Errores

• UnsupportedOperationException

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• InternalFailureException

• ClientTimeoutException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException (Excepción de demasiadas solicitudes)

• loadId (en la CLI: --load-id): obligatorio: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El ID del trabajo de carga que se va a eliminar.

• status: una cadena, del tipo: string (una cadena codificada con UTF-8).

  El estado de la cancelación.

Errores

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException (Excepción de demasiadas solicitudes)

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

Campos

• loadIds: se trata de una cadena, del tipo: string (una cadena codificada con UTF-8).

  Una lista de ID de carga.