Oracle Database Queries API

openapi: 3.2.0
info:
  title: Oracle Database Oracle SODA (Simple Oracle Document Access) REST Queries 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: Queries
  description: Query by Example (QBE) and filter operations
paths:
  /custom-actions/query/{collection}:
    post:
      operationId: queryCollection
      summary: Oracle Database Query collection with QBE filter
      description: Queries the collection using a Query by Example (QBE) filter specification in the request body. Returns matching documents with optional pagination. This endpoint is equivalent to /{collection}/?action=query.
      tags:
      - Queries
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - name: limit
        in: query
        description: Maximum number of documents to return
        schema:
          type: integer
      - name: offset
        in: query
        description: Number of documents to skip
        schema:
          type: integer
      - name: fields
        in: query
        description: Control which fields are returned
        schema:
          type: string
          enum:
          - id
          - value
          - all
      requestBody:
        required: true
        description: QBE filter specification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QBEFilter'
      responses:
        '200':
          description: Query results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    DocumentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        hasMore:
          type: boolean
          description: Whether more documents exist beyond this page
        limit:
          type: integer
          description: Server-imposed result limit
        offset:
          type: integer
          description: Offset of first returned result
        count:
          type: integer
          description: Number of documents in this response
        totalResults:
          type: integer
          description: Total documents in collection (only if totalResults=true)
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        rel:
          type: string
          description: Link relation type
        href:
          type: string
          format: uri
          description: Link URL
        mediaType:
          type: string
          description: Media type of the linked resource
    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
    Document:
      type: object
      properties:
        id:
          type: string
          description: Unique document key
        etag:
          type: string
          description: Document version tag for optimistic concurrency
        lastModified:
          type: string
          format: date-time
          description: Last modification timestamp
        created:
          type: string
          format: date-time
          description: Creation timestamp
        value:
          type: object
          description: Document content (when fields=value or fields=all)
        mediaType:
          type: string
          description: Content type for non-JSON documents
        bytes:
          type: integer
          description: Content length for non-JSON documents
  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/