Find the request unit charge for operations in Azure Cosmos DB for NoSQL

Article
11/01/2023

APPLIES TO: NoSQL

Azure Cosmos DB supports many APIs, such as SQL, MongoDB, Cassandra, Gremlin, and Table. Each API has its own set of database operations. These operations range from simple point reads and writes to complex queries. Each database operation consumes system resources based on the complexity of the operation.

The cost of all database operations is normalized by Azure Cosmos DB and is expressed by request units (RU). Request charge is the request units consumed by all your database operations. You can think of RUs as a performance currency abstracting the system resources such as CPU, IOPS, and memory that are required to perform the database operations supported by Azure Cosmos DB. No matter which API you use to interact with your container, costs are always measured in RUs. Whether the database operation is a write, point read, or query, costs are always measured in RUs. To learn more, see Request Units in Azure Cosmos DB.

This article presents the different ways that you can find the request unit consumption for any operation run against a container in Azure Cosmos DB for NoSQL. If you're using a different API, see API for MongoDB, API for Cassandra, API for Gremlin, and API for Table.

Currently, you can measure consumption only by using the Azure portal or by inspecting the response sent from Azure Cosmos DB through one of the SDKs. If you're using the API for NoSQL, you have multiple options for finding the request charge for an operation.

Use the Azure portal

Sign in to the Azure portal.
Create a new Azure Cosmos DB account and feed it with data, or select an existing Azure Cosmos DB account that already contains data.
Go to the Data Explorer pane, and then select the container you want to work on.
Select New SQL Query.
Enter a valid query, and then select Execute Query.
Select Query Stats to display the actual request charge for the request you executed.

Objects that are returned from the .NET SDK v2 expose a RequestCharge property:

ResourceResponse<Document> fetchDocumentResponse = await client.ReadDocumentAsync(
    UriFactory.CreateDocumentUri("database", "container", "itemId"),
    new RequestOptions
    {
        PartitionKey = new PartitionKey("partitionKey")
    });
var requestCharge = fetchDocumentResponse.RequestCharge;

StoredProcedureResponse<string> storedProcedureCallResponse = await client.ExecuteStoredProcedureAsync<string>(
    UriFactory.CreateStoredProcedureUri("database", "container", "storedProcedureId"),
    new RequestOptions
    {
        PartitionKey = new PartitionKey("partitionKey")
    });
requestCharge = storedProcedureCallResponse.RequestCharge;

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri("database", "container"),
    "SELECT * FROM c",
    new FeedOptions
    {
        PartitionKey = new PartitionKey("partitionKey")
    }).AsDocumentQuery();
while (query.HasMoreResults)
{
    FeedResponse<dynamic> queryResponse = await query.ExecuteNextAsync<dynamic>();
    requestCharge = queryResponse.RequestCharge;
}

Objects that are returned from the .NET SDK v3 expose a RequestCharge property:

//------------------------------------------------------------
// Copyright (c) Microsoft Corporation.  All rights reserved.
//------------------------------------------------------------

namespace Microsoft.Azure.Cosmos.SampleCodeForDocs
{
    using Microsoft.Azure.Cosmos.Scripts;
    using System.Threading.Tasks;

    class CustomDocsSampleCode
    {
        private CosmosClient cosmosClient;

        internal void intitialize()
        {
            this.cosmosClient = new CosmosClient(
                accountEndpoint: "TestAccount",
                authKeyOrResourceToken: "TestKey",
                clientOptions: new CosmosClientOptions());
        }

        public async Task GetRequestChargeFromResource()
        {
            // <GetRequestCharge>
            Container container = this.cosmosClient.GetContainer("database", "container");
            string itemId = "myItem";
            string partitionKey = "partitionKey";
            string storedProcedureId = "storedProcedureId";
            string queryText = "SELECT * FROM c";

            ItemResponse<dynamic> itemResponse = await container.CreateItemAsync<dynamic>(
                item: new { id = itemId, pk = partitionKey },
                partitionKey: new PartitionKey(partitionKey));
            double requestCharge = itemResponse.RequestCharge;

            Scripts scripts = container.Scripts;
            StoredProcedureExecuteResponse<object> sprocResponse = await scripts.ExecuteStoredProcedureAsync<object>(
                storedProcedureId: storedProcedureId,
                partitionKey: new PartitionKey(partitionKey),
                parameters: new dynamic[] { new object() });

            requestCharge = sprocResponse.RequestCharge;

            FeedIterator<dynamic> feedIterator = container.GetItemQueryIterator<dynamic>(
                 queryText: queryText,
                 requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey(partitionKey) });
            while (feedIterator.HasMoreResults)
            {
                FeedResponse<dynamic> feedResponse = await feedIterator.ReadNextAsync();
                requestCharge = feedResponse.RequestCharge;
            }
            // </GetRequestCharge>
        }
    }
}

For more information, see Quickstart: Build a .NET web app by using a API for NoSQL account in Azure Cosmos DB.

Use the Java SDK

Objects that are returned from the Java SDK expose a getRequestCharge() method:

RequestOptions requestOptions = new RequestOptions();
requestOptions.setPartitionKey(new PartitionKey("partitionKey"));

Observable<ResourceResponse<Document>> readDocumentResponse = client.readDocument(String.format("/dbs/%s/colls/%s/docs/%s", "database", "container", "itemId"), requestOptions);
readDocumentResponse.subscribe(result -> {
    double requestCharge = result.getRequestCharge();
});

Observable<StoredProcedureResponse> storedProcedureResponse = client.executeStoredProcedure(String.format("/dbs/%s/colls/%s/sprocs/%s", "database", "container", "storedProcedureId"), requestOptions, null);
storedProcedureResponse.subscribe(result -> {
    double requestCharge = result.getRequestCharge();
});

FeedOptions feedOptions = new FeedOptions();
feedOptions.setPartitionKey(new PartitionKey("partitionKey"));

Observable<FeedResponse<Document>> feedResponse = client
    .queryDocuments(String.format("/dbs/%s/colls/%s", "database", "container"), "SELECT * FROM c", feedOptions);
feedResponse.forEach(result -> {
    double requestCharge = result.getRequestCharge();
});

For more information, see Quickstart: Build a Java application by using an Azure Cosmos DB for NoSQL account.

Use the Node.js SDK

Objects that are returned from the Node.js SDK expose a headers subobject that maps all the headers returned by the underlying HTTP API. The request charge is available under the x-ms-request-charge key:

const item = await client
    .database('database')
    .container('container')
    .item('itemId', 'partitionKey')
    .read();
var requestCharge = item.headers['x-ms-request-charge'];

const storedProcedureResult = await client
    .database('database')
    .container('container')
    .storedProcedure('storedProcedureId')
    .execute({
        partitionKey: 'partitionKey'
    });
requestCharge = storedProcedureResult.headers['x-ms-request-charge'];

const query = client.database('database')
    .container('container')
    .items
    .query('SELECT * FROM c', {
        partitionKey: 'partitionKey'
    });
while (query.hasMoreResults()) {
    var result = await query.executeNext();
    requestCharge = result.headers['x-ms-request-charge'];
}

For more information, see Quickstart: Build a Node.js app by using an Azure Cosmos DB for NoSQL account.

Use the Python SDK

The Container object from the Python SDK exposes a last_response_headers dictionary that maps all the headers returned by the underlying HTTP API for the last operation executed. The request charge is available under the x-ms-request-charge key:

new_item = {
    "id": "70b63682-b93a-4c77-aad2-65501347265f",
    "partition_key": "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    "name": "Yamba Surfboard"
}
container.create_item(new_item)

request_charge = container.client_connection.last_response_headers["x-ms-request-charge"]

existing_item = container.read_item(
    item="70b63682-b93a-4c77-aad2-65501347265f"
    partition_key="61dba35b-4f02-45c5-b648-c6badc0cbd79"
)

request_charge = container.client_connection.last_response_headers["x-ms-request-charge"]

For more information, see Quickstart: Build a Python app by using an Azure Cosmos DB for NoSQL account.

Next steps

To learn about optimizing your RU consumption, see these articles: