Skip to content

concepts-query-language.md

Latest commit

 

History

History
49 lines (33 loc) · 3.32 KB

concepts-query-language.md

File metadata and controls

49 lines (33 loc) · 3.32 KB
title Query language
titleSuffix Azure Digital Twins
description Learn about the basics of the Azure Digital Twins query language.
author baanders
ms.author baanders
ms.date 01/27/2025
ms.topic concept-article
ms.service azure-digital-twins

Azure Digital Twins query language

This article describes the basics of the query language and its capabilities. Recall that the center of Azure Digital Twins is the twin graph, constructed from digital twins and relationships. This graph can be queried to get information about the digital twins and relationships it contains. These queries are written in a custom SQL-like query language, referred to as the Azure Digital Twins query language. This language is similar to the IoT Hub query language with many comparable features.

For more detailed examples of query syntax and how to run query requests, see Query the twin graph.

About the queries

You can use the Azure Digital Twins query language to retrieve digital twins according to their...

  • Properties (including tag properties)
  • Models
  • Relationships
    • Properties of the relationships

To submit a query to the service from a client app, you'll use the Azure Digital Twins Query API. One way to use the API is through one of the SDKs for Azure Digital Twins.

[!INCLUDE digital-twins-query-reference.md]

Considerations for querying

When writing queries for Azure Digital Twins, keep the following considerations in mind:

  • Remember case sensitivity: All Azure Digital Twins query operations are case-sensitive, so take care to use the exact names defined in the models. If property names are misspelled or incorrectly cased, the result set is empty with no errors returned.

  • Escape single quotes: If your query text includes a single quote character in the data, the quote will need to be escaped with the \ character. Here's an example that deals with a property value of D'Souza:

    :::code language="sql" source="~/digital-twins-docs-samples/queries/examples.sql" id="EscapedSingleQuote":::

  • If you're using the Azure CLI to run queries, you may need to escape certain additional characters to meet the requirements of various shells. For more information, see Use special characters in different shells

[!INCLUDE digital-twins-query-latency-note.md]

Querying historized twin data over time

The Azure Digital Twins query language is only for querying the present state of your digital twins and relationships.

To run queries on historized twin graph data collected over time, use the data history feature to connect your Azure Digital Twins instance to an Azure Data Explorer cluster. This will automatically historize graph updates to Azure Data Explorer, where they can be queried using the Azure Digital Twins plugin for Azure Data Explorer.

Next steps

Learn how to write queries and see client code examples in Query the twin graph.