Azure Cosmos Db: Point Read Vs. Query

Introduction

Retrieving information effectively from Cosmos DB is crucial, second only to choosing an appropriate partition key. While this article assumes you understand basic partitioning concepts, if you’re not familiar with them, I recommend starting there before diving into this article.

There are two primary ways to fetch data from Cosmos DB: Point Reads and Queries. Microsoft’s documentation may lead you to believe that Point Reads are universally superior. While generally true, there are exceptions. In cases involving large documents — approximately 500 KB or larger — Queries may actually be more cost-effective.

For further reading

Query vs. Point Read

For documents at or below 1 KB, a Point Read is about 2.3 times more efficient than a Query. Including a partition key in Queries is optional, and its exact cost depends on several factors: the chosen partition key, collection size, among others. The RU cost for querying a 1 KB document could be 2.3 RUs or even higher. As your collection grows, this cost will also increase.

On the other hand, if your document is 1 KB or smaller, a Point Read will never cost more than 1 RU.

Query Example in C#

Here’s how a query might look in C#:

using Microsoft.Azure.Cosmos;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

class Program
{
    private static readonly string EndpointUrl = 
        "https://<your-account>.documents.azure.com:443/";
    private static readonly string AuthorizationKey = 
        "<your-primary-key>";
    private static CosmosClient cosmosClient;

    public static async Task Main(string[] args)
    {
        using (cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey))
        {
            Container container = cosmosClient
                .GetContainer("YourDatabaseId", "YourContainerId");

            QueryDefinition queryDefinition = 
                new QueryDefinition("SELECT * FROM c WHERE c.someProperty 
                  = @value")
                .WithParameter("@value", "<your-value>");

            FeedIterator<YourClass> queryResultSetIterator = 
                container.GetItemQueryIterator<YourClass>(queryDefinition);

            List<YourClass> items = new List<YourClass>();

            while (queryResultSetIterator.HasMoreResults)
            {
                FeedResponse<YourClass> currentResultSet = 
                  await queryResultSetIterator.ReadNextAsync();
                foreach (YourClass item in currentResultSet)
                {
                    items.Add(item);
                }
            }

            Console.WriteLine($"Fetched {items.Count} items");
        }
    }
}

Point Read Example in C#

And here’s an example of a Point Read:

using Microsoft.Azure.Cosmos;
using System;
using System.Threading.Tasks;

class Program
{
    private static readonly string EndpointUrl = 
        "https://<your-account>.documents.azure.com:443/";
    private static readonly string AuthorizationKey = 
        "<your-primary-key>";
    private static CosmosClient cosmosClient;

    public static async Task Main(string[] args)
    {
        using (cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey))
        {
            Container container = cosmosClient
                .GetContainer("YourDatabaseId", "YourContainerId");

            string id = "<your-document-id>";
            string partitionKeyValue = "<your-partition-key-value>";

            ItemResponse<YourClass> response = 
                await container.ReadItemAsync<YourClass>
                    (id, new PartitionKey(partitionKeyValue));
            YourClass yourObject = response.Resource;

            Console.WriteLine($"Fetched item with id: {yourObject.Id}");
        }
    }
}

When comparing the two, you’ll notice that the Point Read specifies both the unique ID and the partition key, whereas the Query involves only a query expression.

Practical Considerations

Review your Cosmos DB instance to understand the size of documents you’re storing. If they are predominantly small and you’re not using Point Reads, consider this an opportunity to reduce costs. Similarly, if you’re using Point Reads for very large documents, switching to Queries could yield significant savings.

Conclusion

You may encounter codebases that exclusively use Queries, even when only storing small documents. Often, this arises because the initial database setup was done without an understanding of partitioning or the differences between Point Reads and Queries. By reading this article, you’ve armed yourself with the knowledge to make more informed choices and optimize your Cosmos DB operations.