Edit

Share via

Query Units in Azure Digital Twins

  • Article

This article covers Query Units, how they're used by Azure Digital Twins, and how to find the Query Unit consumption in Azure Digital Twins.

An Azure Digital Twins Query Unit (QU) is a unit of on-demand computation that's used to execute your Azure Digital Twins queries using the Query API.

It abstracts away the system resources like CPU, IOPS, and memory that are required to perform query operations supported by Azure Digital Twins, allowing you to track usage in Query Units instead.

The amount of Query Units consumed to execute a query is affected by:

  • The complexity of the query
  • The size of the result set (so a query returning 10 results will consume more QUs than a query of similar complexity that returns just one result)

This article explains how to understand Query Units and track Query Unit consumption.

Find the Query Unit consumption in Azure Digital Twins

When you run a query using the Azure Digital Twins Query API, you can examine the response header to track the number of QUs that the query consumed. Look for "query-charge" in the response sent back from Azure Digital Twins.

The Azure Digital Twins SDKs allow you to extract the query-charge header from the pageable response. This section shows how to query for digital twins and how to iterate over the pageable response to extract the query-charge header.

The following code snippet demonstrates how you can extract the query charges incurred when calling the Query API. It iterates over the response pages first to access the query-charge header, and then iterates over the digital twin results within each page.

using Azure;
using Azure.DigitalTwins.Core;
using System;

namespace DigitalTwins_Samples
{
    public class GetQueryChargesSample
    {
        async public void Run(DigitalTwinsClient client)
        {
            AsyncPageable<BasicDigitalTwin> asyncPageableResponseWithCharge = client.QueryAsync<BasicDigitalTwin>("SELECT * FROM digitaltwins");
            int pageNum = 0;

            // The "await" keyword here is required, as a call is made when fetching a new page.

            await foreach (Page<BasicDigitalTwin> page in asyncPageableResponseWithCharge.AsPages())
            {
                Console.WriteLine($"Page {++pageNum} results:");

                // Extract the query-charge header from the page

                if (QueryChargeHelper.TryGetQueryCharge(page, out float queryCharge))
                {
                    Console.WriteLine($"Query charge was: {queryCharge}");
                }

                // Iterate over the twin instances.

                // The "await" keyword is not required here, as the paged response is local.

                foreach (BasicDigitalTwin twin in page.Values)
                {
                    Console.WriteLine($"Found digital twin '{twin.Id}'");
                }
            }
        }
    }
}

Next steps

To learn more about querying Azure Digital Twins, visit:

You can find Azure Digital Twins query-related limits in Azure Digital Twins service limits.