openapi: 3.2.0
info:
  title: Query Service Query Templates 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: Query Templates
  description: Query templates let you create, store, and execute any query as an ad hoc or scheduled service.
paths:
  /query-templates:
    get:
      tags:
      - Query Templates
      summary: List query templates
      operationId: listQueryTemplates
      description: This request provides a list of every query template.
      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: 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: isPrevLink
        in: query
        description: '`isPrevLink` is part of pagination. Results are sorted using the `created` timestamp and the `orderby` property.  When navigating pages of results, `isPrevLink` is set to true when paging backwards. It reverses the order of the query. See "next" and "prev" links as examples.'
        schema:
          type: boolean
      - name: orderby
        in: query
        description: The field that specifies the order of results. The supported fields are `created` and `updated`. Prepend the property name with `+` for ascending and `-` for descending order. The default is `-created`. Note that the plus sign (`+`) has to be escaped with `%2B`. For example `%2Bcreated` is the value for an ascending created order.
        schema:
          type: string
      - name: limit
        in: query
        description: Restrict the maximum number of records that should be returned for a given request.
        schema:
          type: integer
      - name: start
        in: query
        description: The timestamp used with `orderby` to order the returned results.
        schema:
          type: string
      - name: property
        in: query
        description: "Comma-separated filters. Multiple filters separated by commas can be passed.\n\n  List of properties that allow filtering: `name`, `userId`, `lastUpdatedBy`.\n\n  * The `name` property can only be filtered with the `~` (contains) operator.\n  Only one name string WITHOUT a comma can be included. For example, `property=name~maria`.\n\n  * The `userId` and the `lastUpdatedBy` properties can be used with the `==` (equal to) operator.\n  Only one name string WITHOUT a comma can be included. For example, `property=userId==49D005796000B4B20A495J85@acme.adobe.com`"
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_template_list'
        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: {}
    post:
      tags:
      - Query Templates
      summary: Create a query template
      operationId: createQueryTemplate
      description: This request creates a query template.
      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: 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
      requestBody:
        description: The query template to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/query_template_def'
        required: true
      responses:
        202:
          x-summary: Success
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_template'
        401:
          x-summary: Unauthorized
          description: Unauthorized
          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: queryTemplate
  /query-templates/count:
    get:
      tags:
      - Query Templates
      summary: Retrieve the count of query templates
      operationId: retrieveQueryTemplateCount
      description: This request retrieves the count of query templates.
      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: 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: property
        in: query
        description: "Comma-separated filters. Multiple filters separated by commas can be passed. Examples below are given with unsafe HTML characters for clarity, but all content MUST be HTML escaped.\n\n  Currently only `userId` is allowed in filtering count.\nExample: `property=userId=={USER_ID}`"
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/template_count'
        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: {}
  /query-templates/{queryTemplateId}:
    get:
      tags:
      - Query Templates
      summary: Retrieve a query template
      operationId: retrieveQueryTemplate
      description: This request retrieves the query template for the template ID provided in the request path.
      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: 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: queryTemplateId
        in: path
        description: The query template ID for the query template to be retrieved.
        required: true
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_template'
        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: {}
    put:
      tags:
      - Query Templates
      summary: Update a query template
      operationId: updateQueryTemplate
      description: This request updates the query template for the template ID provided in the request path.
      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: 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: queryTemplateId
        in: path
        description: The query template ID for the template to be updated.
        required: true
        schema:
          type: string
      requestBody:
        description: Query template to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/query_template_def'
        required: true
      responses:
        202:
          x-summary: Success
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_template'
        401:
          x-summary: Unauthorized
          description: Unauthorized
          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: queryTemplate
    delete:
      tags:
      - Query Templates
      summary: Delete a query template
      operationId: deleteQueryTemplate
      description: This request deletes the query template for the template ID provided in the request path.
      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: 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: queryTemplateId
        in: path
        description: The query template ID for the template to be deleted.
        required: true
        schema:
          type: string
      responses:
        202:
          x-summary: Success
          description: Query Template Delete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_template_delete'
        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: {}
components:
  schemas:
    query_template_delete:
      type: object
      properties:
        message:
          type: string
          description: A message to indicate the outcome of the request.
          example: Deleted
        statusCode:
          type: string
          description: The status code generated by the request.
          example: 202
    _page:
      type: object
      properties:
        orderby:
          type: string
          description: The property by which this page is ordered.
          example: -created
        start:
          type: string
          description: The first value, in sorted order, of the orderby property on this page.
          example: '2021-12-06T22:00:17.362Z'
        next:
          type: string
          description: The start value for the next page.
          example: '2022-11-22T00:52:34.839Z'
        property:
          type: string
          description: The list of properties by which the result is filtered, if any. If the `property` query parameter is set when the query is issued, then it is returned in the `_page` object.
          example: created>=2021-04-05T13:30:00Z,state==IN_PROGRESS
        count:
          type: integer
          description: The number of items on the page.
          example: 26
      description: Pagination information for this resource. It contains a `count` property for the number of resources returned.
    query_template:
      type: object
      properties:
        sql:
          type: string
          description: The SQL query statement. You can use either standard SQL or include parameter replacements. To use a parameter replacement in the SQL you must prepend the parameter key with a `$`. For example, `$key`, and provide the parameters used in the SQL as JSON key value pairs in the `queryParameters` field.
          example: SELECT $key from $key1 where $key > $key2;
        name:
          type: string
          description: The name for the template.
          example: Sample template query
        id:
          type: string
          description: The ID of the query template.
          example: f7cb5155-29da-4b95-6131-6c5beadjde7f
        queryParameters:
          type: object
          properties:
            key:
              type: string
              description: An example key value pair for a parameterized query.
              example: value
            key1:
              type: string
              description: An example key value pair for a parameterized query.
              example: value1
            key2:
              type: string
              description: An example key value pair for a parameterized query.
              example: value2
          description: A key value pairing for replacing values in the SQL. The key must be prepended with a `$`. For example, `SELECT column1 FROM table2 WHERE column1=$key;`. No value type checking will be done. This is required if using a parameter replacement.
        updated:
          type: string
          description: The time in UTC format when query template was last updated.
          example: '2022-11-21T21:50:01.469Z'
        lastUpdatedBy:
          type: string
          description: The ID of the user who last updated the template.
          example: '{USER_ID}'
        userId:
          type: string
          description: The ID of the user who created the template.
          example: '{USER_ID}'
        _links:
          $ref: '#/components/schemas/query_template_links'
      description: Query Template Response.
    next:
      type: object
      properties:
        href:
          type: string
          description: A link to the next page of results.
          example: https://platform.adobe.io/data/foundation/query/queries/alert-subscriptions?orderby=-created&page=2
      description: Pre-constructed URI for the next page of results, if any exist.
    query_list_template_links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/next'
        prev:
          $ref: '#/components/schemas/prev'
    query_template_links:
      type: object
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              description: The URI of this resource.
              example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
            method:
              type: string
              description: The HTTP method to use with the `href`.
              example: GET
          description: Contains the information required to access this resource.
        update:
          type: object
          properties:
            href:
              type: string
              description: The URI to update this resource.
              example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
            method:
              type: string
              description: The HTTP method to use with the `href`.
              example: PUT
            body:
              type: string
              description: The JSON payload to send to the `href`.
              example: '{\"sql\" : \"new sql\", \"name\" : \"new name\"}'
          description: Contains the information required to update this resource.
        delete:
          type: object
          properties:
            href:
              type: string
              description: The URI to delete this resource.
              example: https://platform-va7.adobe.io/data/foundation/query/query-templates/2f560b99-abc0-4058-92dj-9408jaddcd71
            method:
              type: string
              description: The HTTP method to use with the `href`.
              example: DELETE
          description: Contains the information required to delete this resource.
      description: The object contains links to perform actions on this schedule run.
    query_template_def:
      required:
      - name
      - sql
      type: object
      properties:
        sql:
          type: string
          description: You can either use standard SQL or a parameter replacement. To use a parameter replacement in the SQL you must prepend the parameter key with a `$`. For example, `$key`, and provide the parameters used in the SQL as JSON key value pairs in the `queryParameters` field. The values passed here will be the default parameters used in the template. If you want to override these parameters, you must override them in the POST request.
          example: SELECT $key FROM $key1 WHERE $key > $key2;
        queryParameters:
          type: object
          properties:
            key:
              type: string
              description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
              example: value
            key1:
              type: string
              description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
              example: value1
            key2:
              type: string
              description: A set of two linked data items. The key is a unique identifier for some item of data, and the value, is either the data that is identified or a pointer to the location of that data.
              example: value2
          description: A key value pairing to replace values in the SQL statement. These are required if you are using parameter replacements. No value type checking will be done on these key value pairs.
        name:
          type: string
          description: A descriptive and human readable name for the template.
          example: Test Parameterized Query
      description: A description of the query template to be submitted.
    template_count:
      type: object
      properties:
        totalCount:
          type: integer
          description: The total number of templates.
          example: 52
        version:
          type: integer
          description: The REST API version of this resource.
          example: 1
      description: Total Query Template count Response.
    prev:
      type: object
      properties:
        href:
          type: string
          description: A link to the previous page of results.
          example: https://platform.adobe.io/data/foundation/query/queries/alert-subscriptions?orderby=-created&page=0
      description: Pre-constructed URI for the previous page of results, if any exist.
    query_template_list:
      type: object
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/query_template'
        _page:
          $ref: '#/components/schemas/_page'
        _links:
          $ref: '#/components/schemas/query_list_template_links'
        version:
          type: integer
          description: The REST API version of this resource.
      description: List of queries