Amazon Neptune Loader API

openapi: 3.2.0
info:
  title: Amazon Neptune Loader API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '1.0'
  description: 'Operations tagged Loader across 2 of this provider''s published API definitions: amazon-neptune-data-openapi.yml, amazon-neptune-loader-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://neptune-db.{region}.amazonaws.com
  description: Amazon Neptune Data API regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
- url: https://{cluster-endpoint}:8182
  description: Neptune Loader REST endpoint
  variables:
    cluster-endpoint:
      default: your-cluster-endpoint.region.neptune.amazonaws.com
      description: The cluster endpoint DNS name for your Neptune DB cluster
security:
- aws_sigv4: []
tags:
- name: Loader
  description: Bulk data loading operations
paths:
  /loader:
    post:
      operationId: startLoaderJob
      summary: Amazon Neptune Start a Bulk Loader Job
      description: Initiates a bulk data loading job from Amazon S3 into the Neptune database. Supports CSV for property graphs and multiple RDF formats.
      tags:
      - Loader
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartLoaderJobInput'
      responses:
        '200':
          description: Loader job started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartLoaderJobOutput'
              examples:
                startLoaderJob200Example:
                  summary: Default startLoaderJob 200 response
                  x-microcks-default: true
                  value:
                    status: available
                    payload:
                      loadId: neptune-cluster-abc123
        '400':
          description: Bad request - invalid parameters.
        '500':
          description: Internal server error.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listLoaderJobs
      summary: Amazon Neptune List Bulk Loader Jobs
      description: Returns a list of Neptune bulk loader job IDs. Neptune tracks the most recent 1,024 bulk load jobs.
      tags:
      - Loader
      parameters:
      - name: limit
        in: query
        description: Maximum number of load IDs to return.
        schema:
          type: integer
      - name: includeQueuedLoads
        in: query
        description: Whether to include queued loads in the response.
        schema:
          type: boolean
      responses:
        '200':
          description: Loader job list retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    type: object
                    properties:
                      loadIds:
                        type: array
                        items:
                          type: string
              examples:
                listLoaderJobs200Example:
                  summary: Default listLoaderJobs 200 response
                  x-microcks-default: true
                  value:
                    status: available
                    payload:
                      loadIds:
                      - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://neptune-db.{region}.amazonaws.com
      description: Amazon Neptune Data API regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /loader/{loadId}:
    get:
      operationId: getLoaderJobStatus
      summary: Amazon Neptune Get the Status of a Bulk Loader Job
      description: Returns the status of a specific bulk loader job including overall progress and any error details.
      tags:
      - Loader
      parameters:
      - name: loadId
        in: path
        required: true
        description: The unique identifier of the load job.
        schema:
          type: string
      - name: details
        in: query
        description: Whether to include detailed status information.
        schema:
          type: boolean
      - name: errors
        in: query
        description: Whether to include error details.
        schema:
          type: boolean
      - name: page
        in: query
        description: Error page number to retrieve.
        schema:
          type: integer
      - name: errorsPerPage
        in: query
        description: Number of errors per page.
        schema:
          type: integer
      responses:
        '200':
          description: Loader job status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoaderJobStatusOutput'
              examples:
                getLoaderJobStatus200Example:
                  summary: Default getLoaderJobStatus 200 response
                  x-microcks-default: true
                  value:
                    status: available
                    payload:
                      feedCount:
                      - {}
                      overallStatus:
                        fullUri: example-value
                        runNumber: 1
                        retryNumber: 1
                        status: available
                        totalTimeSpent: 1
        '404':
          description: Load job not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: cancelLoaderJob
      summary: Amazon Neptune Cancel a Bulk Loader Job
      description: Cancels an in-progress bulk loader job by its load ID.
      tags:
      - Loader
      parameters:
      - name: loadId
        in: path
        required: true
        description: The unique identifier of the load job to cancel.
        schema:
          type: string
      responses:
        '200':
          description: Loader job cancelled successfully.
        '404':
          description: Load job not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://neptune-db.{region}.amazonaws.com
      description: Amazon Neptune Data API regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
components:
  schemas:
    StartLoaderJobInput:
      type: object
      required:
      - source
      - format
      - iamRoleArn
      - region
      properties:
        source:
          type: string
          description: Amazon S3 URI identifying files or folders to load (s3://bucket/key).
        format:
          type: string
          description: The data format of the files to load.
          enum:
          - csv
          - opencypher
          - ntriples
          - nquads
          - rdfxml
          - turtle
        iamRoleArn:
          type: string
          description: The ARN of the IAM role with S3 access.
        region:
          type: string
          description: The AWS Region of the S3 bucket.
        mode:
          type: string
          description: The load mode.
          enum:
          - NEW
          - RESUME
          - AUTO
          default: AUTO
        failOnError:
          type: string
          description: Whether to stop the load job on error.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'TRUE'
        parallelism:
          type: string
          description: The degree of parallelism for loading.
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - OVERSUBSCRIBE
          default: HIGH
        parserConfiguration:
          type: object
          description: Optional parser configuration settings.
          properties:
            baseUri:
              type: string
            namedGraphUri:
              type: string
            allowEmptyStrings:
              type: boolean
        updateSingleCardinalityProperties:
          type: string
          description: Whether to update existing single-cardinality properties.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'FALSE'
        queueRequest:
          type: string
          description: Whether to queue the request if a load is already running.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'FALSE'
        dependencies:
          type: array
          description: Load job IDs that must complete before this job runs.
          items:
            type: string
        userProvidedEdgeIds:
          type: string
          description: For openCypher format, whether edge IDs are provided.
          enum:
          - 'TRUE'
          - 'FALSE'
    StartLoaderJobOutput:
      type: object
      properties:
        status:
          type: string
        payload:
          type: object
          properties:
            loadId:
              type: string
              description: The unique identifier for the load job.
    LoaderJobStatusOutput:
      type: object
      properties:
        status:
          type: string
        payload:
          type: object
          properties:
            feedCount:
              type: array
              items:
                type: object
            overallStatus:
              type: object
              properties:
                fullUri:
                  type: string
                runNumber:
                  type: integer
                retryNumber:
                  type: integer
                status:
                  type: string
                totalTimeSpent:
                  type: integer
                startTime:
                  type: integer
                totalRecords:
                  type: integer
                totalDuplicates:
                  type: integer
                parsingErrors:
                  type: integer
                datatypeMismatchErrors:
                  type: integer
                insertErrors:
                  type: integer
    LoaderListResponse:
      type: object
      properties:
        status:
          type: string
        payload:
          type: object
          properties:
            loadIds:
              type: array
              description: The list of load job IDs.
              items:
                type: string
    LoaderStartResponse:
      type: object
      properties:
        status:
          type: string
          description: The HTTP status (e.g., '200 OK').
        payload:
          type: object
          properties:
            loadId:
              type: string
              description: The unique identifier for the initiated load job.
    LoaderStatusResponse:
      type: object
      properties:
        status:
          type: string
        payload:
          type: object
          properties:
            feedCount:
              type: array
              description: Count of feeds processed.
              items:
                type: object
            overallStatus:
              type: object
              description: Overall status of the load job.
              properties:
                fullUri:
                  type: string
                  description: The S3 URI of the data source.
                runNumber:
                  type: integer
                  description: The run number for this load.
                retryNumber:
                  type: integer
                  description: The retry number.
                status:
                  type: string
                  description: The job status (LOAD_NOT_STARTED, LOAD_IN_PROGRESS, LOAD_COMPLETED, LOAD_CANCELLED_BY_USER, LOAD_CANCELLED_DUE_TO_ERRORS, LOAD_FAILED, LOAD_UNEXPECTED_ERROR, LOAD_DATA_DEADLOCK, LOAD_DATA_FAILED_DUE_TO_FEED_MODIFIED_OR_DELETED, LOAD_S3_READ_ERROR, LOAD_S3_ACCESS_DENIED_ERROR, LOAD_COMMITTED_W_WRITE_CONFLICTS).
                  enum:
                  - LOAD_NOT_STARTED
                  - LOAD_IN_PROGRESS
                  - LOAD_COMPLETED
                  - LOAD_CANCELLED_BY_USER
                  - LOAD_CANCELLED_DUE_TO_ERRORS
                  - LOAD_FAILED
                  - LOAD_UNEXPECTED_ERROR
                  - LOAD_DATA_DEADLOCK
                  - LOAD_DATA_FAILED_DUE_TO_FEED_MODIFIED_OR_DELETED
                  - LOAD_S3_READ_ERROR
                  - LOAD_S3_ACCESS_DENIED_ERROR
                  - LOAD_COMMITTED_W_WRITE_CONFLICTS
                totalTimeSpent:
                  type: integer
                  description: Total time spent on the load in seconds.
                startTime:
                  type: integer
                  description: Start time as a Unix timestamp.
                totalRecords:
                  type: integer
                  description: Total records processed.
                totalDuplicates:
                  type: integer
                  description: Total duplicate records encountered.
                parsingErrors:
                  type: integer
                  description: Total parsing errors.
                datatypeMismatchErrors:
                  type: integer
                  description: Total datatype mismatch errors.
                insertErrors:
                  type: integer
                  description: Total insert errors.
            failedFeeds:
              type: array
              description: Details about failed feeds.
              items:
                type: object
            errors:
              type: object
              description: Error details (when errors=true was requested).
    LoaderRequest:
      type: object
      required:
      - source
      - format
      - iamRoleArn
      - region
      properties:
        source:
          type: string
          description: 'Amazon S3 URI identifying the data file(s), folder, or multiple folders to load. Supported URI formats: s3://bucket_name/key, https://s3.amazonaws.com/bucket_name/key, https://s3.region.amazonaws.com/bucket_name/key.'
        format:
          type: string
          description: The data format of the source files.
          enum:
          - csv
          - opencypher
          - ntriples
          - nquads
          - rdfxml
          - turtle
        iamRoleArn:
          type: string
          description: The ARN of the IAM role that provides Neptune access to the S3 bucket. Can be a comma-separated list for cross-account access.
        region:
          type: string
          description: The AWS Region of the S3 bucket. Must match the Neptune cluster region or be accessible cross-region.
        mode:
          type: string
          description: The load mode. NEW fails if data was previously loaded. RESUME continues a failed load. AUTO resumes or starts new as needed.
          enum:
          - NEW
          - RESUME
          - AUTO
          default: AUTO
        failOnError:
          type: string
          description: Whether to stop the entire load job on error.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'TRUE'
        parallelism:
          type: string
          description: The degree of parallelism for loading. LOW uses a single thread, MEDIUM uses num_vCPU/2, HIGH uses num_vCPU, OVERSUBSCRIBE uses all available resources.
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - OVERSUBSCRIBE
          default: HIGH
        parserConfiguration:
          type: object
          description: Optional parser configuration settings for RDF data.
          properties:
            baseUri:
              type: string
              description: The base URI for relative URIs in the data.
            namedGraphUri:
              type: string
              description: The default named graph URI for loaded triples.
            allowEmptyStrings:
              type: boolean
              description: Whether to allow empty string property values.
        updateSingleCardinalityProperties:
          type: string
          description: Whether to update existing single-cardinality vertex properties. Not supported for openCypher format.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'FALSE'
        queueRequest:
          type: string
          description: Whether to queue the request if a load is already running. Neptune queues up to 64 jobs in FIFO order.
          enum:
          - 'TRUE'
          - 'FALSE'
          default: 'FALSE'
        dependencies:
          type: array
          description: Array of load job IDs that must complete successfully before this job runs.
          items:
            type: string
        userProvidedEdgeIds:
          type: string
          description: For openCypher format only. TRUE requires an :ID column in edge files. FALSE auto-generates edge IDs.
          enum:
          - 'TRUE'
          - 'FALSE'
    LoaderErrorResponse:
      type: object
      properties:
        requestId:
          type: string
        code:
          type: string
        detailedMessage:
          type: string
          description: Detailed error message.
  securitySchemes:
    aws_sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication
x-refined-from:
- amazon-neptune-data-openapi.yml
- amazon-neptune-loader-openapi.yml