openapi: 3.2.0
info:
  title: Query Service Accelerated Queries API
  description: "Use the Adobe Experience Platform Query Service API to query Platform data with standard SQL. With this serverless tool, you can join any datasets in the [Experience Platform Data Lake](https://experienceleague.adobe.com/docs/experience-platform/landing/license/data-management-best-practices.html#understanding-adobe-experience-platform-data-storage) and capture the query results as a new dataset for use in reporting, Data Science Workspace, or for ingestion into Real-time Customer Profile.\n\n**Related Documentation**:\n  * [Query Service documentation](http://www.adobe.com/go/query-service-home-en)\n\n**Visualize API calls with Postman (a free, third-party software)**:\n  * [Query Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Query%20Service%20API.postman_collection.json)\n  * [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n  * [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n**API paths**:\n  * PLATFORM Gateway URL: https://<span>platform.adobe.io/\n  * Base path for this API: /data/foundation/query\n  * Example of a complete path: https://<span>platform.adobe.io/data/foundation/query/queries\n\n**Required headers**:\n  * All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n  * All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n  * All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n**API error handling**:\n  * Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#request-header-errors).\n  * Refer to the Query Service troubleshooting guide for [common query related FAQs](https://experienceleague.adobe.com/docs/experience-platform/query/troubleshooting-guide.html)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/query
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Accelerated Queries
  description: Query the accelerated store in a stateless manner to quickly return results based on aggregated data.
paths:
  /accelerated-queries:
    post:
      tags:
      - Accelerated Queries
      summary: Query the accelerated store
      operationId: runAcceleratedQuery
      description: Run a query on accelerated store datasets by including either an SQL statement or a template ID within the request payload.
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. The value should be 'application/json'.
        required: true
        schema:
          type: string
      - name: x-sandbox-id
        in: header
        description: The unique identifier of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        schema:
          type: string
      - name: x-request-id
        in: header
        description: An optional header that serves as a tracking ID for the request. If one is not provided on the request, the server generates one automatically.
        schema:
          type: string
      - name: User-Agent
        in: header
        description: The type of the client making the HTTP request.
        schema:
          type: string
      - name: Accept-Encoding
        in: header
        description: This request header indicates the type of content encoding that the client can understand when consuming compressed response bodies. It is usually a compression algorithm. Accepted values include `gzip` and `identity`.
        schema:
          type: string
      requestBody:
        description: The request body to run a query on the accelerated store. The request accepts either a query string as `sql` or the ID of a saved query as `templateId`.
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/SqlAcceleratedQueryDefinition'
              - $ref: '#/components/schemas/TemplateIdAcceleratedQueryDef'
            examples:
              SQL accelerated query:
                $ref: '#/components/examples/SqlAcceleratedQueryDefinition'
              Template ID accelerated query:
                $ref: '#/components/examples/TemplateIdAcceleratedQueryDefinition'
      responses:
        200:
          x-summary: Success
          description: Query Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/accelerated_query_response'
                - $ref: '#/components/schemas/TemplateIdAcceleratedQueryResponse'
              examples:
                SQL accelerated query response:
                  $ref: '#/components/examples/SqlAcceleratedQueryResponse'
                Template ID accelerated query response:
                  $ref: '#/components/examples/TemplateIdAcceleratedQueryResponse'
        401:
          x-summary: Unauthorized
          description: Unauthorized
          content: {}
        404:
          x-summary: Not found
          description: Not Found
          content: {}
        '500':
          x-summary: Internal server error
          description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
          content: {}
      x-codegen-request-body-name: accelerated-query-body
components:
  schemas:
    TemplateIdAcceleratedQueryDef:
      type: object
      required:
      - dbName
      - templateId
      properties:
        dbName:
          type: string
          description: The name of the database you are making an accelerated query to. The value for `dbName` should take the format of `{SANDBOX_NAME}:{ACCELERATED_STORE_DATABASE}.{ACCELERATED_STORE_SCHEMA}`. The database provided must exist within the accelerated store or the request will result in an error. You must ensure that the `x-sandbox-name` header and sandbox name in `dbName` refer to same sandbox.
          example: acmesbox1:acmeacceldb:accmeaggschema
        templateId:
          type: string
          description: The ID of a query created when a POST request is made to the `/templates` endpoint. The corresponding query is submitted to the query accelerated store. Accelerated queries require EITHER an SQL statement OR a template ID, but not both. Submitting both in a request causes an error.
          example: f7cb5155-29da-4b95-8131-8c5deadfbe7f
        name:
          type: string
          description: An optional human-friendly, descriptive name for the accelerated query.
          example: Second Accelerated Query Sample
        description:
          type: string
          description: An optional comment on the intent of the query to help other users understand its purpose. The maximum size allowed is 1000 bytes.
          example: Another sample of an accelerated query.
      description: The query definition submitted to the query accelerated store.
    TemplateIdAcceleratedQueryResponse:
      type: object
      properties:
        queryId:
          type: string
          description: The unique identifier for the query.
          example: ba7aa60c-f5ab-47de-b980-c30789108efe
        resultsMeta:
          $ref: '#/components/schemas/metadata_schema_ref'
        results:
          type: array
          description: The results of the query in JSON format.
          items:
            $ref: '#/components/schemas/results_each_row_schema_ref'
        request:
          $ref: '#/components/examples/TemplateIdAcceleratedQueryDefinition'
      description: The response body for the accelerated query.
    results_each_row_schema_ref:
      type: object
      description: An object that represents a single row of the result set.
      example:
        Industry_name: Acme
        Industry_code: 23
        Value: 93141
        column_name_boolean_type: true
    accelerated_query_response:
      type: object
      properties:
        queryId:
          type: string
          description: The unique identifier for the query.
          example: ba7aa60c-f5ab-47de-b980-c30789108efe
        resultsMeta:
          $ref: '#/components/schemas/metadata_schema_ref'
        results:
          type: array
          description: The results of the query in JSON format.
          items:
            $ref: '#/components/schemas/results_each_row_schema_ref'
        request:
          $ref: '#/components/examples/SqlAcceleratedQueryDefinition'
      description: The response body for the accelerated query.
    metadata_schema_ref:
      type: object
      properties:
        _adhoc:
          type: object
          properties:
            type:
              type: string
              description: The data type of the `_adhoc` object.
            meta:xdmType:
              type: string
              description: This is a system-generated value for the XDM field type. For more information on the available types see the documentation on available [XDM types](https://experienceleague.adobe.com/docs/experience-platform/xdm/tutorials/custom-fields-api.html).
            properties:
              type: object
              properties: {}
              description: These are the column names of the queried dataset.
              example:
                Industry_name:
                  type: string
                  meta:xdmType: string
                  default: null
                Industry_code:
                  type: integer
                  meta:xdmType: int,
                  maximum: 2147483647
                  minimum: -2147483648
                Value:
                  type: number
                  meta:xdmType: number
                  maximum: null,
                  minimum: null
                Active_customer:
                  type: boolean
                  meta:xdmType: boolean
          description: The schema of the ad hoc object created. An ad-hoc Experience Data Model (XDM) schema with fields that are namespaced for usage only by a single dataset.
      description: This object contains the metadata for each column returned in the response. It includes the name and type of each column.
    SqlAcceleratedQueryDefinition:
      type: object
      required:
      - dbName
      - sql
      properties:
        dbName:
          type: string
          description: The name of the database you are making an accelerated query to. The value for `dbName` should take the format of `{SANDBOX_NAME}:{ACCELERATED_STORE_DATABASE}.{ACCELERATED_STORE_SCHEMA}`. The database provided must exist within the accelerated store or the request will result in an error. You must ensure that the `x-sandbox-name` header and sandbox name in `dbName` refer to same sandbox.'
          example: acmesbox1:acmeacceldb:accmeaggschema
        sql:
          type: string
          description: An SQL statement string to be submitted to the query accelerated store. The maximum size allowed is 1000000 bytes. Accelerated queries require EITHER an SQL statement OR a template ID, but not both. Submitting both in a request causes an error.
          example: SELECT * FROM accounts;
        name:
          type: string
          description: An optional human-friendly, descriptive name for the accelerated query.
          example: Second Accelerated Query Sample
        description:
          type: string
          description: An optional comment on the intent of the query to help other users understand its purpose. The maximum size allowed is 1000 bytes.
          example: Another sample of an accelerated query.
      description: The query definition submitted to the query accelerated store.
  examples:
    SqlAcceleratedQueryDefinition:
      description: A payload for an accelerated query request that includes SQL in the payload.
      value:
        dbName: acmesbox1:acmeacceldb:accmeaggschema
        sql: SELECT * FROM accounts;
        name: Accelerated Query Sample
        description: A sample of an accelerated query.
    TemplateIdAcceleratedQueryResponse:
      description: A sample response for an accelerated query request that used a template ID in the payload.
      value:
        queryId: ba7aa60c-f5ab-47de-b980-c30789108efe
        resultsMeta:
          _adhoc:
            type: string
            meta:xdmType: string
            properties:
              Industry_name:
                type: string
                meta:xdmType: string
                default: null
              Industry_code:
                type: integer
                meta:xdmType: int,
                maximum: 2147483647
                minimum: -2147483648
              Value:
                type: number
                meta:xdmType: number
                maximum: null,
                minimum: null
              Active_customer:
                type: boolean
                meta:xdmType: boolean
        results:
          Industry_name: Acme
          Industry_code: 23
          Value: 93141
          column_name_boolean_type: true
        request:
          dbName: acmesbox1:acmeacceldb:accmeaggschema
          templateId: f7cb5155-29da-4b95-8131-8c5deadfbe7f
          name: Second Accelerated Query Sample
          description: Another sample of an accelerated query.
    TemplateIdAcceleratedQueryDefinition:
      description: A payload for an accelerated query request that includes a template ID in the payload.
      value:
        dbName: acmesbox1:acmeacceldb:accmeaggschema
        templateId: f7cb5155-29da-4b95-8131-8c5deadfbe7f
        name: A Templated Accelerated Query Sample
        description: A sample of an accelerated query request that uses a template ID.
    SqlAcceleratedQueryResponse:
      description: A sample response for an accelerated query request that used SQL directly in the payload.
      value:
        queryId: ba7aa60c-f5ab-47de-b980-c30789108efe
        resultsMeta:
          _adhoc:
            type: string
            meta:xdmType: string
            properties:
              Industry_name:
                type: string
                meta:xdmType: string
                default: null
              Industry_code:
                type: integer
                meta:xdmType: int,
                maximum: 2147483647
                minimum: -2147483648
              Value:
                type: number
                meta:xdmType: number
                maximum: null,
                minimum: null
              Active_customer:
                type: boolean
                meta:xdmType: boolean
        results:
          Industry_name: Acme
          Industry_code: 23
          Value: 93141
          column_name_boolean_type: true
        request:
          dbName: acmesbox1:acmeacceldb:accmeaggschema
          sql: SELECT * FROM accounts;
          name: Accelerated Query Sample
          description: A sample of an accelerated query.