openapi: 3.0.0
info:
  version: 2.0
  title: Queries and Dashboards API
  description:
    "This feature is in [Public Preview](https://docs.microsoft.com/azure/databricks/release-notes/release-types).\n
   
    **Important:** To access Databricks REST APIs, you must [authenticate](https://docs.microsoft.com/azure/databricks/sql/api/authentication).
   "
tags:
  - name: "Queries / Results"
    description:
      "These endpoints are used for CRUD operations on query definitions. Query definitions include the query text, name, description, tags, execution schedule, parameters, and visualizations."
  - name: Dashboards
    description:
      "In general, there is little need to modify dashboards using the API. However, it can be useful to use dashboard objects to look-up a collection of related query IDs. The API can also be used to duplicate multiple dashboards at once since you can get a dashboard definition with a GET request and then POST it to create a new one."
  - name: ACL / Permissions
    description: 
      "The SQL Permissions API is similar to the endpoints of the [Permissions API](https://docs.microsoft.com/azure/databricks/dev-tools/api/latest/permissions). However, this exposes only one endpoint, which gets the Access Control List for a given object. You cannot modify any permissions using this API.\n
    
    There are three levels of permission:\n

      - `CAN_VIEW`: Allows read-only access\n

      - `CAN_RUN`: Allows read access and run access (superset of `CAN_VIEW`)\n

      - `CAN_MANAGE`: Allows all actions: read, run, edit, delete, modify permissions (superset of `CAN_RUN`)"

servers:
  - url: https://<databricks-instance>/api/2.0/preview/sql
    description: 
      "In the URL, substitute `<databricks-instance>` with the domain name of your
      Azure Databricks deployment. Use the form `adb-<workspace-id>.<random-number>.azuredatabricks.net`."
paths:
  /queries:
    description:
      "This endpoint can search and filter query objects or to create a new query object."
    get:
      tags:
        - Queries / Results
      summary: Retrieve a list of queries
      description:
        "Optionally this list can be filtered by a search term."
      operationId: sql-analytics-get-queries
      parameters:
        - name: page_size
          in: query
          required: false
          description: "Number of queries to return per page."
          schema:
            type: integer
            example: 50
        - name: page
          in: query
          required: false
          description: "Page number to retrieve."
          schema:
            type: integer
            example: 1
        - name: order
          in: query
          required: false
          description: 
            "Name of query attribute to order by. Default sort order is ascending. Append a dash (`-`) to order descending instead. \n
          
- `name`: The name of the query. \n

- `created_at`: The timestamp the query was created. \n

- `schedule`: The refresh interval for each query. For example: \"Every 5 Hours\" or \"Every 5 Minutes\". \"Never\" is treated as the highest value for sorting. \n

- `runtime`: The time it took to run this query. This will be blank for parameterized queries. A blank value is treated as the highest value for sorting. \n

- `executed_at`: The timestamp when the query was last run. \n

- `created_by`: The user name of the user that created the query. \n
          "
          schema:
            type: string
            enum:
              - name
              - -name
              - created_at
              - -created_at
              - schedule
              - -schedule
              - runtime
              - -runtime
              - executed_at
              - -executed_at
              - created_by
              - -created_by
        - name: q
          in: query
          required: false
          description: "Full text search term"
          schema:
            type: string
            example: orders by month
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The total number of queries.
                    example: 1
                  page:
                    type: integer
                    description: The page number that is currently displayed.
                    example: 1
                  page_size:
                    type: integer
                    description: The number of queries per page.
                    example: 25
                  results:
                    type: array
                    description: List of queries returned.
                    items:
                      anyOf:
                        - $ref: "#/components/schemas/query-object"

    post:
      summary: Create a new query definition
      description:
        "Queries created with this endpoint belong to the authenticated user making the request. \n

        **Note**: You cannot add a visualization until you create the query."
      tags:
        - Queries / Results
      operationID: sql-analytics-create-query
      requestBody:
        description: A query object to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/query-post-content"
      responses:
        200:
          summary: "Query created successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/query-object"


  /queries/{queryID}:
    get:
      summary: Retrieve a query definition.
      description: Retrieve a query object definition along with contextual permissions information about the currently authenticated user.
      operationId: sql-analytics-get-query
      tags:
        - Queries / Results
      parameters:
        - name: queryID
          in: path
          schema:
            type: string
            format: UUID
            example: 2cca1687-60ff-4886-a445-0230578c864d
      responses:
        200:
          summary: "Query fetched successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/query-object"
    post:
      summary: Change a query definition
      description: 
        "Modify this query definition.\n

         **Note**: You cannot undo this operation."
      operationId: sql-analytics-change-query
      tags:
        - Queries / Results
      parameters:
        - name: queryID
          in: path
          schema:
            type: string
            format: UUID
            example: 2cca1687-60ff-4886-a445-0230578c864d
      requestBody:
        description: The query definition that will replace the current definition for this `queryID`.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/query-post-content"
      responses:
        200:
          summary: "Query changed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/query-object"
    delete:
      summary: Move a query to the trash
      description: Trashed queries immediately disappear from searches and list views and cannot be used for alerts. The trash is deleted after 30 days.
      operationId: sql-analytics-trash-query
      tags:
        - Queries / Results
      responses:
        200:
          summary: "Query moved to trash"
          content:
            application/json:
              schema:
                type: string
                example: null

  /queries/trash/{queryID}:
    post:
      summary: Restore a trashed query
      description: A restored query appears in list views and searches. You can use restored queries for alerts.
      operationId: sql-analytics-restore-trashed-query
      tags:
        - Queries / Results
      responses:
        200:
          summary: "Query restored successfully"
          content:
            application/json:
              schema:
                type: string
                example: null

  /dashboards:
    get:
      description: 
      summary: Fetch a paginated list of dashboard objects
      tags:
        - Dashboards
      operationId: get-sql-analytics-dashboards
      parameters:
        - name: page_size
          in: query
          required: false
          description: "Number of dashboards to return per page."
          schema:
            type: integer
            example: 50
        - name: page
          in: query
          required: false
          description: "Page number to retrieve."
          schema:
            type: integer
            example: 1
        - name: order
          in: query
          required: false
          description: "Name of dashboard attribute to order by."
          schema:
            type: string
            enum:
              - name
              - created_at
        - name: q
          in: query
          required: false
          description: "Full text search term."
          schema:
            type: string
            example: orders by month
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The total number of dashboards.
                    example: 1
                  page:
                    type: integer
                    description: The current page being displayed.
                    example: 1
                  page_size:
                    type: integer
                    description: The number of dashboards per page.
                    example: 25
                  results:
                    type: array
                    description: List of dashboards returned.
                    items:
                      anyOf:
                        - $ref: "#/components/schemas/dashboard-object"
    post:
      summary: Create a new dashboard object
      tags:
        - Dashboards
      operationId: sql-analytics-create-dashboard
      requestBody:
        description: Only the `name` parameter is required in the POST request JSON body. Other fields can be included when duplicating dashboards with this API. Databricks does not recommend designing dashboards exclusively using this API.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The title of this dashboard which appears in list views and at the top of the dashboard page.
                  example: Sales Dashboard
                  required: true
                layout:
                  type: array
                  description: Currently unused. In a previous version of this API `layout` contained information for arranging widgets on the grid.
                  example: []
                  required: false
                dashboard_filters_enabled:
                  type: boolean
                  description: In the web application, query filters that share a name are coupled to a single selection box if this value is true.
                  default: false
                  example: false
                  required: false
                widgets:
                  type: array
                  description: An array of widget objects. A complete description of widget objects can be found in the response to [Retrieve A Dashboard Definition](#operation/sql-analytics-fetch-dashboard). Databricks does not recommend creating new widgets via this API. 
                  required: false
                is_trashed:
                  type: boolean
                  description: Whether the dashboard is trashed. Trashed dashboards won't appear in list views.
                  example: false
                  required: false
                is_draft:
                  type: boolean
                  description: Draft dashboards only appear in list views for their owners.
                  is_draft: true
                  required: false
                tags:
                  type: array
                  required: false
                  items:
                    anyOf:
                      - $ref: "#/components/schemas/tag-string"


        refresh_schedules:
          type: array
          description: Current undocumented while back-end dashboard refresh is under development.
          example: []
        is_favorite:
          type: boolean
          description: 
            "Whether this query object should appear in the current user's favorites list. The application uses this flag to determine whether or not the \"favorite star \" should be colored."

      responses:
        200:
          summary: "A dashboard object was successfully created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/dashboard-object"
  /dashboards/{dashboardId}:
    get:
      summary: Retrieve a dashboard definition
      description: Returns a JSON representation of a dashboard object, including its visualization and query objects.
      operationId: sql-analytics-fetch-dashboard
      tags:
        - Dashboards
      responses:
        200:
          summary: "Dashboard fetched successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/dashboard-object"
    delete:
      summary: "Move a dashboard to the trash"
      description: "Trashed dashboards do not appear in list views or searches and cannot be shared."
      operationId: sql-analytics-trash-dashboard
      tags:
        - Dashboards
      responses:
        200:
          summary: "Dashboard successfully moved to trash"
          content:
            application/json:
              schema:
                type: string
                example: null
  /dashboards/trash/{dashboardId}:
    post:
      summary: Restore a trashed dashboard
      description: A restored dashboard appears in list views and searches and can be shared.
      operationId: sql-analytics-restore-trashed-dashboard
      tags:
        - Dashboards
      responses:
        200:
          summary: "Dashboard restored successfully"
          content:
            application/json:
              schema:
                type: string
                example: null
  /permissions/{objectType}/{objectId}:
    description:
      "Fetches the access control list (ACL) for a specific object."
    # ^^ endpoint description outside verb get/post/etc is not exposed in current redoc version
    get:
      tags:
        - ACL / Permissions
      summary: Get object access control list
      description:
        "Returns a JSON representation of the access control list (ACL) for a specified object."
      operationId: get-sql-analytics-object-permissions
      parameters:
        - name: objectType
          in: path
          required: true
          description: The type of object permissions to check.
          schema:
            $ref: '#/components/schemas/object_type_plural'
        - name: objectId
          in: path
          required: true
          description: Object ID. An ACL will be returned for the object with this UUID.
          schema:
            $ref: '#/components/schemas/object_id'
      responses:
        200:
          $ref: '#/components/responses/access-control-list-response'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - ACL / Permissions
      summary: Set object access control list
      description:
        "Completely rewrite the access control list for a specified object."
      operationId: set-sql-analytics-object-permissions
      parameters:
        - name: objectType
          in: path
          required: true
          description: The type of object permission to set.
          schema:
            $ref: '#/components/schemas/object_type_plural'
        - name: objectId
          in: path
          required: true
          description: Object ID. The ACL for the object with this UUID will be overwritten by this request's POST content.
          schema:
            $ref: '#/components/schemas/object_id'
      requestBody:
        description: An ACL list to be applied to the object specified in the URL.
        required: true
        content:
          access_control_list:
            schema:
              $ref: "#/components/schemas/access_control_list"
      responses:
        200:
          $ref: '#/components/responses/access-control-list-response'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
  /permissions/{objectType}/{objectId}/transfer:
    description:
      "Transfer ownership of a single object."
    # ^^ endpoint description outside verb get/post/etc is not exposed in current redoc version
    post:
      tags:
        - ACL / Permissions
      summary: Transfer object ownership
      description:
        "Transfer ownership of a dashboard, query, or alert to an active user. Requires an admin API key."
      operationId: set-sql-analytics-object-owner
      parameters:
        - name: objectType
          in: path
          required: true
          description: The type of object on which to change ownership.
          schema:
            $ref: '#/components/schemas/ownable_object_type'
        - name: objectId
          in: path
          required: true
          description: The ID of the object on which to change ownership.
          schema:
            type: object
            properties:
              new_owner:
                description: Email address that will become the new owner. This user must exist within the workspace.
                example: "user@example.com"
                type: string
                format: email
      requestBody:
        description: Email address for the new owner, who must exist in the workspace.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                new_owner:
                  type: string
                  format: email
                  example: user@example.com
                  description: Email address of active user who will become object owner. This user must already exist in the workspace.
      responses:
        200:
          $ref: '#/components/responses/generic-success-message'
        400:
          $ref: '#/components/responses/ObjectTransferBadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'

components:
  parameters:
  schemas:
    integer_max_100:
      type: integer
      example: 50
    object_type:
      type: string
      description: A singular noun object type
      enum:
        - alert
        - dashboard
        - data_source
        - query
      example: query
    ownable_object_type:
      type: string
      description: The singular form of the type of object which can be owned.
      enum:
        - alert
        - dashboard
        - query
      example: query
    object_type_plural:
      type: string
      description: Always a plural of the object type.
      enum:
        - alerts
        - dashboards
        - data_sources
        - queries
      example: queries
    object_id:
      type: string
      description: A UUID generated by the application.
      example: "2cca1687-60ff-4886-a445-0230578c864d"
      format: uuid
    object_type_and_id:
      type: string
      description: An object's type and UUID, separated by a forward slash (/) character.
      format: "<object-type>/<uuid>"
      example: "query/2cca1687-60ff-4886-a445-0230578c864d"
    permission_level:
      type: string
      enum:
        - CAN_VIEW
        - CAN_RUN
        - CAN_MANAGE
    user_acl:
      type: object
      properties:
        user_name:
          type: string
          format: email
        permission_level:
          $ref: '#/components/schemas/permission_level'
    group_acl:
      type: object
      properties:
        group_name:
          type: string
          example: admins
        permission_level:
          $ref: '#/components/schemas/permission_level'
    access_control_list:
      type: array
      items:
        anyOf:
          - $ref: '#/components/schemas/user_acl'
          - $ref: '#/components/schemas/group_acl'
      example:
        - group_name: 'admins'
          permission: 'CAN_MANAGE'
    query_interval_object:
      type: object
      properties:
        interval:
          description: Integer number of seconds between runs.
          type: integer
          example: 900
        time:
          description: For daily, weekly, and monthly runs, the time-of-day for run to start.
          example: "00:15"
          default: null
        day_of_week:
          description: For weekly runs, a day of the week for run to start.
          example: "Wednesday"
          default: null
        until:
          description: A date after which this schedule no longer applies.
          example: "2021-01-07"
          default: null
    parameter-object:
      type: object
      properties:
        title:
          type: string
          description: The text displayed in a parameter picking widget.
        name:
          type: string
          description: The literal parameter marker that appears between double curly braces in the query text.
        type:
          type: string
          description: Parameters can have several different types.
          enum:
            - text
            - datetime
            - number
            - dropdown-list
          value:
            type: string
            description: The default value for this parameter.
    text-parameter-value:
      type: object
      properties:
        name:
          type: string
          description: The name of this parameter that appears between curly braces in the query definition.
        value:
          type: string
          description: The parameter value as text.
    number-parameter-value:
      type: object
      properties:
        name:
          type: string
          description: The name of this parameter that appears between curly braces in the query definition.
        value:
          type: number
          description: An integer or floating-point number.
    dropdown-parameter-value:
      type: object
      properties:
        name:
          type: string
          description: The name of this parameter that appears between curly braces in the query definition.
        value:
          oneOf:
            - name: string-dropdown-value
              type: string
              example: "param"
              description: "If the dropdown parameter does not support multi-select, provide a single string value. If it supports multi-select, use the `Array` field."
            - name: array-dropdown-value
              type: array
              items:
                type: string
                description: "If the dropdown parameter supports multi-select then values can be passed as an array of strings. If it does not, use the `string` field."

    date-parameter-value:
      type: object
      properties:
        name:
          type: string
          description: The name of this parameter that appears between curly braces in the query definition.
        value:
          type: string
          format: date-time
          description: "Date value in format as defined by RFC 3339, section 5.6. The required granularity of date and time depends on the resolution expected by the parameter: date, date and time, or date and time with seconds."
          example: "1991-08-03 09:21:21"


    user-object:
      type: object
      properties:
        id:
          type: integer
          example: 899619779028913
        name:
          type: string
          example: user@example.com
        email:
          type: string
          format: email
          example: user@example.com
        profile_image_url:
          type: string
          format: url
          description: The URL for the gravatar profile picture tied to this user's email address
          example: https://www.gravatar.com/avatar/732f2b4824846f9a0253f233e0d79bf0?s=40&d=identicon
        is_db_admin:
          type: boolean
          description: Whether this user is an admin in the Databricks workspace.
          example: true
    tag-string:
      type: string
      description: Tags can be applied to dashboards and queries. They are used for filtering list views.
      example: "Payroll"
    visualization-object:
      type: object
      description: 
        "The visualization description API changes frequently and is unsupported. You can duplicate a visualization by copying description objects received _from the API_ and then using them to create a new one with a POST request to the same endpoint. Databricks does not recommend constructing ad-hoc visualizations entirely in JSON."
      properties:
        id:
          type: integer
          description: The integer ID for this visualization.
          example: 29830
        type:
          type: string
          example: TABLE
          description: "The type of visualization: chart, table, pivot table, and so on."
        name:
          type: string
          description: The name of the visualization that appears on dashboards and the query screen.
          example: Chart
        description:
          type: string
          description: A short description of this visualization. This is not displayed in the UI.
          example: A table of data from this query.
        options:
          type: object
          description: The options object varies widely from one visualization type to the next and is unsupported. Databricks does not recommend modifying visualization settings in JSON.
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    query-object:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: dee5cca8-1c79-4b5e-a711-e7f9d241bdf6
        latest_query_data_id:
          type: string
          format: uuid
          description: If there is a cached result for this query and user, this field includes the query result ID. If this query uses parameters, this field is always null.
          example: ab281b1a-527a-4789-bcf7-cfc3ba08d910
        name:
          type: string
          description: The title of this query that appears in list views, widget headings, and on the query page.
          example: "Orders by month by customer"
        description:
          type: string
          description: General description that conveys additional information about this query such as usage notes.
          example: "Summarizes total order dollars for customers in the Europe/Asia region."
        query:
          type: string
          description: "The text of the query to be run."
          example: "SELECT field FROM table WHERE field = {{ param }}"
        query_hash:
          type: string
          description: A SHA-256 hash of the query text along with the authenticated user ID.
          example: 08314a3361c4795528acd1139a2b7c58
        schedule:
          $ref: '#/components/schemas/query_interval_object'
        api_key:
          type: string
          description: 
            "This field is unsupported and is for internal use only."
        is_archived:
          type: boolean
          description:  Whether the query is trashed. Trashed queries can't be used in dashboards, or appear in search results. If this boolean is `true`, the `options` property for this query will include a `moved_to_trash_at` timestamp. Trashed queries are permanently deleted after 30 days. 
        is_draft:
          type: boolean
          description: Whether the query is a draft. Draft queries only appear in list views for their owners. Visualizations from draft queries cannot appear on dashboards.
        updated_at:
          type: string
          format: date-time
          description: The timestamp at which this query was last updated.
          example: "2021-01-07T20:29:24.289Z"
        created_at:
          type: string
          format: date-time
          description: The timestamp when this query was created.
          example: "2020-12-15T18:39:15.837Z"
        data_source_id: 
          type: string
          format: UUID
          description: Data Source ID. The UUID that uniquely identifies this data source across the API.
          example: 0c205e24-5db2-4940-adb1-fb13c7ce960b
        options:
          type: object
          properties:
            moved_to_trash_at: 
              type: string
              format: date-time
              description: The timestamp when this query was moved to trash. Only present when the `is_archived` property is `true`. Trashed items are deleted after thirty days.
              example: "2020-12-15T18:39:15.837Z"
            parameters:
              type: array
              items:
                anyOf:
                  - $ref: "#/components/schemas/parameter-object"
        version:
          type: string
          description: Unused field.
        tags:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/tag-string"
        is_safe:
          type: boolean
          description:
            "Text parameter types are not safe from SQL injection for all types of data source. Set this Boolean parameter to `true` if a query either does not use any text type parameters or uses a data source type where text type parameters are handled safely."
          example: false
        user_id:
          type: integer
          description: The ID of the user who created this query.
          example: 899619779028913
        last_modified_by_id:
          type: integer
          description: The ID of the user who last saved changes to this query.
          example: 899619779028913
        visualizations:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/visualization-object"
        is_favorite:
          type: boolean
          description: 
            "Whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is colored in."
          example: true
        user:
          $ref: "#/components/schemas/user-object"
        last_modified_by:
          $ref: "#/components/schemas/user-object"
        can_edit:
          type: boolean
          description: Describes whether the authenticated user may edit the definition of this query.
          example: true
        permission_tier:
          $ref: "#/components/schemas/permission_level"
    query-post-content:
      type: object
      properties:
        data_source_id:
          description: The ID of the data source where this query will run.
          type: uuid
          example: 2cca1687-60ff-4886-a445-0230578c864d
        query:
          description: The text of the query.
          type: string
          example: 
            "SELECT field FROM table WHERE field = {{ param }}"
        name:
          description: The name or title of this query to display in list views.
          type: string
          example: "Orders by month by customer"
        description:
          description: General description that can convey additional information about this query such as usage notes.
          type: string
          example:
            "Summarizes total order dollars for customers in the Europe/Asia region."
        schedule:
          description: 
            "JSON object that describes the scheduled execution frequency. A schedule object includes `interval`, `time`, `day_of_week`, and `until` fields. If a scheduled is supplied, then only `interval` is required. All other field can be `null`."
          type: object
          example:
            interval: 86400
            time: "06:15"
            day_of_week: "Wednesday"
            until: "1991-08-03"
          schema:
            $ref: "#/components/schemas/query_interval_object"
        options:
          description: 
            "Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, `name`, `type`, and `value` properties. The `value` field here is the default value. It can be overridden at runtime."
          type: object
          example:
            parameters:
              - title: customer
                name: param
                type: text
                value: acme
    query-result-column-description:
      type: object
      properties:
        name:
          type: string
        friendly_name:
          type: string
        type:
          type: string
      example:
        name: orig_date
        friendly_name: Original Date
        type: datetime
    query-result-row-description:
      type: object
      description: A JSON object whose keys are the names of each column in this query result and whose values constitute a single row of the result.
      example:
        - orig_date: 1991-08-03
          value: 0
    query-result-object:
      type: object
      description: A JSON response body that contains a serialized result table.
      properties:
        query_result:
          type: object
          properties:
            id:
              type: string
              format: UUID
              description: The UUID for this cached query result. Each cached result is keyed with the current user name and query text.
              example: 06192bfa-cd91-4b57-9a81-df98be5570c2
            query_hash:
              type: string
              description: A SHA-256 hash of the query text that generated this result, including actual parameter values.
              example: 08314a3361c4795528acd1139a2b7c58
            query:
              type: string
              description: The complete query that generated this result, including parameter values used at runtime.
              example: "SELECT field FROM table WHERE field = 100"
            data:
              type: object
              description: Serialized tabular data from this query.
              properties:
                columns:
                  type: array
                  items:
                    anyOf:
                      - $ref: "#/components/schemas/query-result-column-description"
                rows:
                  type: array
                  items:
                    anyOf:
                      - $ref: "#/components/schemas/query-result-row-description"
            data_source_id:
              type: string
              format: UUID
              example: af574c41-045c-4d50-b078-67d78b766128
            runtime:
              type: float
              description: Query run time in seconds.
              example: 0.850272178649902
            retrieved_at:
              type: string
              format: date-time
              description: Timestamp when this result was retreived from the database.
              example: 1991-08-03T13:02:35.916Z
    job-object:
      type: object
      description: A JSON object that represents the status of a query run job.
      properties:
        id:
          type: string
          format: "org_id:user_id:query_uuid"
          description: "A tuple of the organization ID, user ID, and query ID."
          example: "org:6051921418418893:user:899619779028913:id:cb9a11e8-68c4-4531-8d0c-104b921f7306"
        updated_at:
          type: string
          format: date-time
          description: "Timestamp when this job was last updated by Databricks SQL."
        status:
          type: integer
          example: 3
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          description: "

      1. `PENDING` (waiting to run)

      2. `STARTED` (running)

      3. `SUCCESS`

      4. `FAILURE`

      5. `CANCELLED`
          "
        error:
          type: string
          description: "Error message. This is `null` unless the job has a `FAILURE` status (code 4). This is the error that resulted in the failure."
          example: null
        result:
          type: string
          format: UUID
          description: "Result ID. This is `null` unless the job has a `SUCCESS` status (code 3). This is the UUID for the query result object that was cached following this query run."
          example: 7ae47ad7-c401-4c2e-884e-51249058b9b3
        query_result_id:
          type: string
          format: UUID
          description: Same as `result` above.
          example: 7ae47ad7-c401-4c2e-884e-51249058b9b3
    dashboard-object:
      type: object
      description: A JSON representing a dashboard containing widgets of visualizations and text boxes.
      properties:
        id:
          type: string
          format: UUID
          description: The ID for this dashboard.
          example: 4e443c27-9f61-4f2e-a12d-ea5668460bf1
        slug:
          type: string
          description: URL slug. Usually mirrors the query name with dashes (`-`) instead of spaces. Appears in the URL for this query.
          example: sales-dashboard
        name:
          type: string
          description: The title of the dashboard that appears in list views and at the top of the dashboard page.
          example: Sales Dashboard
        user_id:
          type: integer
          description: The ID of the user that created and owns this dashboard.
          example: 7878537523656153
        layout:
          type: array
          description: Unused field.
          example: []
        dashboard_filters_enabled:
          type: boolean
          description: In the web application, query filters that share a name are coupled to a single selection box if this value is `true`.
          default: false
          example: false
        widgets:
          $ref: "#/components/schemas/widget-object"
        is_archived:
          type: boolean
          description: Whether a dashboard is trashed. Trashed dashboards won't appear in list views.  If this boolean is `true`, the `options` property for this dashboard will include a `moved_to_trash_at` timestamp. Items in Trash are permanently deleted after 30 days.
        is_draft:
          type: boolean
          description: Whether a dashboard is a draft. Draft dashboards only appear in list views for their owners.
        tags:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/tag-string"
        updated_at:
          type: string
          format: date-time
          description: "Timestamp when this dashboard was last updated."
        created_at:
          type: string
          format: date-time
          description: Timestamp when this dashboard was created.
        version:
          type: string
          description: Unused field.
        refresh_schedules:
          type: array
          description: Unsupported field.
          example: []
        is_favorite:
          type: boolean
          description: 
            "Whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is colored in."
        can_edit:
          type: boolean
          description: Whether the authenticated user can edit the query definition.
          example: true
        permission_tier:
          $ref: "#/components/schemas/permission_level"
        user:
          $ref: "#/components/schemas/user-object"
        options:
          type: object
          properties:
            moved_to_trash_at: 
              type: string
              format: date-time
              description: The timestamp when this dashboard was moved to trash. Only present when the `is_archived` property is `true`. Trashed items are deleted after thirty days.
              example: "2020-12-15T18:39:15.837Z"
    widget-object:
      type: object
      properties:
        id:
          type: integer
          description: The unique ID for this widget.
          example: 11536
        width:
          type: integer
          description: Unused field.
          example: 1
        options:
          type: object
          properties:
            parameterMappings:
              type: object
              description: How parameters used by the visualization in this widget relate to other widgets on the dashboard. Databricks does not recommend modifying this definition in JSON.
              example:
                param:
                  name: param
                  type: dashboard-level
                  mapTo: param
                  value: null
                  title: This is a parameter
            isHidden:
              type: boolean
              description: Whether this widget is hidden on the dashboard.
              default: false
              example: false
            position:
              type: object
              description: Coordinates of this widget on a dashboard. This portion of the API changes frequently and is unsupported.
            dashboard_id:
              type: text
              format: UUID
              description: The dashboard ID to which this widget belongs. Each widget can belong to one dashboard.
              example: a6d3a7a9-693d-472f-96b2-912622c2ffcd
            text:
              type: text
              description: If this is a textbox widget, the application displays this text. This field is ignored if the widget contains a visualization in the `visualization` field.
              default: null
            updated_at:
              type: text
              format: date-time
              description: Timestamp of the last time this object was updated.
            created_at:
              type: text
              format: date-time
              description: Timestamp when this object was created
        visualization:
          $ref: "#/components/schemas/visualization-object"


  responses:
    access-control-list-response:
      description: "A JSON representation of the access control list (ACL) for an object."
      content:
        application/json:
          schema:
            type: object
            properties:
              object_id:
                $ref: '#/components/schemas/object_type'
              object_type:
                $ref: '#/components/schemas/object_type_and_id'
              access_control_list:
                $ref: '#/components/schemas/access_control_list'
    generic-success-message:
      description: "Generic success message"
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                enum: ["Success",]
    NotFound:
      description: Path not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message that describes the cause of the error.
                example:  The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message that describes the cause of the error.
                example:  The browser (or proxy) sent a request that this server could not understand.
    Forbidden:
      description: Forbidden request
      content:
        text/plain; charset=utf-8:
          schema:
            type: string
            format: html
            description: An HTML page that describes the cause of the error.
    ServerError:
      description: Server error
      content:
        text/plain; charset=utf-8:
          schema:
            type: string
            format: html
            description: An HTML error page that indicates a general server error but does not mention the cause of the error.
    ObjectTransferBadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message that describes the cause of the error.
                enum: ["You must specify a new_owner by email address", "The browser (or proxy) sent a request that this server could not understand."]