Query-Twins.yml

### YamlMime:RESTOperation
uid: digitaltwins-hostname.digital-twins.dataplane.query.querytwins
name: Query Twins
service: Azure Digital Twins
groupName: Query
apiVersion: 2023-10-31
summary: >-
  Executes a query that allows traversing relationships and filtering by property values.

  Status codes:

  * 200 OK

  * 400 Bad Request
    * BadRequest - The continuation token is invalid.
    * SqlQueryError - The query contains some errors.
    * TimeoutError - The query execution timed out after 60 seconds. Try simplifying the query or adding conditions to reduce the result size.
   * 429 Too Many Requests
    * QuotaReachedError - The maximum query rate limit has been reached.
consumes:
- application/json
produces:
- application/json
paths:
- content: POST https://digitaltwins-hostname/query?api-version=2023-10-31
uriParameters:
- name: api-version
  in: query
  isRequired: true
  description: The requested API version.
  types:
  - uid: string
responses:
- name: 200 OK
  headers:
  - name: query-charge
    value: number
  description: Success
  types:
  - uid: QueryResult
- name: Other Status Codes
  headers:
  - name: x-ms-error-code
    value: string
  description: Default response.
  types:
  - uid: ErrorResponse
requestBody:
- name: default
  parameters:
  - name: query
    in: body
    description: The query to execute. This value is ignored if a continuation token is provided.
    types:
    - uid: string
  - name: continuationToken
    in: body
    description: A token which is used to retrieve the next set of results from a previous query.
    types:
    - uid: string
requestHeader:
- name: max-items-per-page
  in: header
  description: The maximum number of items to retrieve per request. The server may choose to return less than the requested number.
  types:
  - uid: integer
- name: traceparent
  in: header
  description: Identifies the request in a distributed tracing system.
  types:
  - uid: string
- name: tracestate
  in: header
  description: Provides vendor-specific trace identification information and is a companion to traceparent.
  types:
  - uid: string
definitions:
- name: QueryResult
  description: The results of a query operation and an optional continuation token.
  kind: object
  properties:
  - name: value
    description: The query results.
    types:
    - uid: object
      isArray: true
  - name: continuationToken
    description: A token which can be used to construct a new QuerySpecification to retrieve the next set of results.
    types:
    - uid: string
- name: ErrorResponse
  description: Error response.
  kind: object
  properties:
  - name: error
    description: The error details.
    types:
    - uid: Error
- name: QuerySpecification
  description: A query specification containing either a query statement or a continuation token from a previous query result.
  kind: object
  properties:
  - name: query
    description: The query to execute. This value is ignored if a continuation token is provided.
    types:
    - uid: string
  - name: continuationToken
    description: A token which is used to retrieve the next set of results from a previous query.
    types:
    - uid: string
- name: Error
  description: Error definition.
  kind: object
  properties:
  - name: code
    isReadOnly: true
    description: Service specific error code which serves as the substatus for the HTTP error code.
    types:
    - uid: string
  - name: message
    isReadOnly: true
    description: A human-readable representation of the error.
    types:
    - uid: string
  - name: details
    isReadOnly: true
    description: Internal error details.
    types:
    - uid: Error
      isArray: true
  - name: innererror
    description: An object containing more specific information than the current object about the error.
    types:
    - uid: InnerError
- name: InnerError
  description: A more specific error description than was provided by the containing error.
  kind: object
  properties:
  - name: code
    description: A more specific error code than was provided by the containing error.
    types:
    - uid: string
  - name: innererror
    description: An object containing more specific information than the current object about the error.
    types:
    - uid: InnerError
examples:
- name: Query for digital twins
  request:
    uri: POST https://digitaltwins-hostname/query?api-version=2023-10-31
    body: >-
      {
        "query": "SELECT * FROM DIGITALTWINS WHERE temp = 79"
      }
    codeTab: |+
      # [HTTP](#tab/HTTP)
      ``` http
      POST https://digitaltwins-hostname/query?api-version=2023-10-31

      {
        "query": "SELECT * FROM DIGITALTWINS WHERE temp = 79"
      }

      ```

  responses:
  - statusCode: "200"
    body: >-
      {
        "value": [
          {
            "$dtId": "Twin-01",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              }
            },
            "name": "Sample01",
            "temp": 79,
            "comfortIndex": 50
          },
          {
            "$dtId": "Twin-02",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:29:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:29:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:29:00.1234567Z",
                "sourceTime": "2022-05-31T12:00:00.000125009Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:29:00.1234567Z"
              }
            },
            "name": "Sample02",
            "temp": 79,
            "comfortIndex": 50
          },
          {
            "$dtId": "Twin-03",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:31:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
              }
            },
            "name": "Sample03",
            "temp": 79,
            "comfortIndex": 50
          }
        ],
        "continuationToken": "<token>"
      }
- name: Retrieve paged query results
  request:
    uri: POST https://digitaltwins-hostname/query?api-version=2023-10-31
    body: >-
      {
        "continuationToken": "<continuationToken from previous query>"
      }
    codeTab: |+
      # [HTTP](#tab/HTTP)
      ``` http
      POST https://digitaltwins-hostname/query?api-version=2023-10-31

      {
        "continuationToken": "<continuationToken from previous query>"
      }

      ```

  responses:
  - statusCode: "200"
    body: >-
      {
        "value": [
          {
            "$dtId": "Twin-04",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              }
            },
            "name": "Sample04",
            "temp": 79,
            "comfortIndex": 50
          },
          {
            "$dtId": "Twin-05",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              }
            },
            "name": "Sample05",
            "temp": 79,
            "comfortIndex": 50
          },
          {
            "$dtId": "Twin-06",
            "$metadata": {
              "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
              "$model": "dtmi:com:example:Sample;1",
              "name": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "temp": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              },
              "comfortIndex": {
                "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
              }
            },
            "name": "Sample06",
            "temp": 79,
            "comfortIndex": 50
          }
        ]
      }
- name: Query for digital twins through a relationship
  request:
    uri: POST https://digitaltwins-hostname/query?api-version=2023-10-31
    body: >-
      {
        "query": "SELECT Widget, Gadget FROM DIGITALTWINS Widget JOIN Gadget RELATED Widget.Contains WHERE Widget.$dtId = 'Twin-01'"
      }
    codeTab: |+
      # [HTTP](#tab/HTTP)
      ``` http
      POST https://digitaltwins-hostname/query?api-version=2023-10-31

      {
        "query": "SELECT Widget, Gadget FROM DIGITALTWINS Widget JOIN Gadget RELATED Widget.Contains WHERE Widget.$dtId = 'Twin-01'"
      }

      ```

  responses:
  - statusCode: "200"
    body: >-
      {
        "value": [
          {
            "Widget": {
              "$dtId": "Twin-01",
              "$metadata": {
                "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
                "$model": "dtmi:com:example:Sample;1",
                "name": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "temp": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "comfortIndex": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                }
              },
              "name": "Sample01",
              "temp": 79,
              "comfortIndex": 50
            },
            "Gadget": {
              "$dtId": "Twin-02",
              "$metadata": {
                "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
                "$model": "dtmi:com:example:Sample;1",
                "name": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "temp": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "comfortIndex": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                }
              },
              "name": "Sample02",
              "temp": 79,
              "comfortIndex": 50
            }
          },
          {
            "Widget": {
              "$dtId": "Twin-01",
              "$metadata": {
                "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
                "$model": "dtmi:com:example:Sample;1",
                "name": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "temp": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "comfortIndex": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                }
              },
              "name": "Sample01",
              "temp": 79,
              "comfortIndex": 50
            },
            "Gadget": {
              "$dtId": "Twin-10",
              "$metadata": {
                "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
                "$model": "dtmi:com:example:Sample;1",
                "name": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "temp": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                },
                "comfortIndex": {
                  "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
                }
              },
              "name": "Sample10",
              "temp": 79,
              "comfortIndex": 50
            }
          }
        ]
      }
security:
- name: oauth2
  type: oauth2
  flow: implicit
  authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0
metadata:
  description: >-
    Executes a query that allows traversing relationships and filtering by property values.

    Status codes:

    200 OK

    400 Bad Request

    BadRequest - The continuation token
errorCodes: []