Oracle Database Bulk Operations API

openapi: 3.2.0
info:
  title: Oracle Database Oracle SODA (Simple Oracle Document Access) REST Bulk Operations API
  description: NoSQL-style document access API for Oracle Database. SODA for REST provides HTTP operations for managing JSON document collections, enabling CRUD operations, querying by example (QBE), bulk operations, and index management through a RESTful interface built on Oracle REST Data Services.
  version: 1.0.0
  contact:
    name: Oracle Support
    url: https://support.oracle.com
    email: support@oracle.com
  license:
    name: Oracle Technology Network License
    url: https://www.oracle.com/downloads/licenses/standard-license.html
  termsOfService: https://www.oracle.com/legal/terms.html
servers:
- url: https://{host}:{port}/ords/{schema}/soda/{version}
  description: SODA REST API Server
  variables:
    host:
      default: localhost
      description: ORDS server hostname
    port:
      default: '8443'
      description: ORDS server port
    schema:
      default: myschema
      description: Oracle Database schema name
    version:
      default: latest
      description: SODA API version
security:
- oauth2: []
- basicAuth: []
tags:
- name: Bulk Operations
  description: Bulk insert, delete, and update operations
paths:
  /custom-actions/insert/{collection}:
    post:
      operationId: bulkInsert
      summary: Oracle Database Bulk insert documents
      description: Inserts multiple documents into the collection in a single operation. Documents are provided as a JSON array. Server-assigned keys are generated for each document.
      tags:
      - Bulk Operations
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        required: true
        description: Array of JSON documents to insert
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Documents inserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInsertResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Collection is read-only
  /custom-actions/delete/{collection}:
    post:
      operationId: bulkDelete
      summary: Oracle Database Bulk delete documents by filter
      description: Deletes multiple documents matching a QBE filter specification. Returns the count of deleted documents.
      tags:
      - Bulk Operations
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        required: true
        description: QBE filter to identify documents to delete
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QBEFilter'
      responses:
        '200':
          description: Documents deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Collection is read-only
  /custom-actions/truncate/{collection}:
    post:
      operationId: truncateCollection
      summary: Oracle Database Truncate all documents from collection
      description: Removes all documents from the collection without deleting the collection itself. This is faster than deleting documents one by one or with a filter.
      tags:
      - Bulk Operations
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      responses:
        '200':
          description: Collection truncated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Collection is read-only
  /custom-actions/update/{collection}:
    post:
      operationId: bulkUpdate
      summary: Oracle Database Bulk update documents by filter
      description: Updates multiple documents matching a QBE filter using JSON Patch operations specified in the $patch field of the request body.
      tags:
      - Bulk Operations
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        required: true
        description: QBE filter with $patch operations
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateRequest'
      responses:
        '200':
          description: Documents updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          description: Collection is read-only
components:
  schemas:
    BulkUpdateResponse:
      type: object
      properties:
        count:
          type: integer
          description: Number of documents matched
        itemsUpdated:
          type: integer
          description: Number of documents updated
    BulkUpdateRequest:
      type: object
      description: Combination of QBE filter fields and $patch operations. Filter fields identify documents to update, $patch contains the JSON Patch operations to apply.
      properties:
        $patch:
          type: array
          items:
            $ref: '#/components/schemas/JsonPatchOperation'
      additionalProperties: true
      example:
        department: HR
        $patch:
        - op: replace
          path: /salary
          value: 70000
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    BulkDeleteResponse:
      type: object
      properties:
        count:
          type: integer
          description: Number of documents affected
        itemsDeleted:
          type: integer
          description: Number of documents deleted
    JsonPatchOperation:
      type: object
      required:
      - op
      - path
      properties:
        op:
          type: string
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
          description: The patch operation to perform
        path:
          type: string
          description: JSON Pointer path to the target field
        value:
          description: The value to use for add, replace, or test operations
        from:
          type: string
          description: JSON Pointer path for move and copy source
    BulkInsertResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DocumentMetadata'
        hasMore:
          type: boolean
    DocumentMetadata:
      type: object
      properties:
        id:
          type: string
        etag:
          type: string
        lastModified:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
    QBEFilter:
      type: object
      description: Query by Example filter specification. Provide field names and values to match, or use operators like $gt, $lt, $in, $regex, etc.
      additionalProperties: true
      example:
        name: John
        salary:
          $gt: 50000
  responses:
    NotFound:
      description: The specified collection or document was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    collectionParam:
      name: collection
      in: path
      required: true
      description: The name of the SODA collection
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /ords/{schema}/oauth/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: SODA for REST Documentation
  url: https://docs.oracle.com/en/database/oracle/simple-oracle-document-access/rest/