Cross-Partition Query

← Back to DP-420 Terminology Reference

Category: Client Connectivity & SDK

Summary: Query spanning multiple physical partitions; tuned via MaxConcurrency and MaxBufferedItemCount.

Overview

A cross-partition query (or fan-out query) is a query in Azure Cosmos DB for NoSQL that does not include the partition key in its filter or query request options, requiring the SDK and query engine to query multiple (or all) physical partitions in the container, retrieve results from each partition, and merge/sort them on the client side. Because cross-partition queries scan multiple physical partitions and require client-side coordination, they generally consume more Request Units (RUs) and have higher latency than single-partition targeted queries. When executing cross-partition queries in the Azure Cosmos DB SDK (such as the .NET SDK), you can tune performance, latency, and client resource utilization using QueryRequestOptions:

• MaxConcurrency (formerly MaxDegreeOfParallelism): Controls the maximum number of concurrent operations run client-side to query physical partitions in parallel. Setting MaxConcurrency = 0 or 1 queries partitions serially one by one. Setting MaxConcurrency = -1 allows the SDK to automatically and dynamically determine the optimal degree of parallelism based on the container's physical partition count, minimizing query latency at the expense of higher client CPU and network utilization. Setting MaxConcurrency = n caps concurrent requests to n partitions.
• MaxBufferedItemCount: Controls the maximum number of items that can be pre-fetched and held in client-side memory while the application consumes current result pages. Setting MaxBufferedItemCount = 0 disables client-side pre-fetching. Setting MaxBufferedItemCount = -1 allows the SDK to dynamically manage client buffer size based on the degree of parallelism, reducing latency between page reads at the expense of client memory usage. Setting MaxBufferedItemCount = n limits memory consumption by buffering at most n pre-fetched items.
• MaxItemCount (Page Size): Specifies the maximum number of items returned per round-trip page from each partition (default 100, or -1 for dynamic).

Example (.NET SDK): Cross-Partition Query with Parallelism & Buffering

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

// Configure QueryRequestOptions to tune cross-partition execution
QueryRequestOptions queryOptions = new QueryRequestOptions
{
    // MaxConcurrency: Parallelize across physical partitions (-1 = dynamic/optimal parallelism)
    MaxConcurrency = -1,

    // MaxBufferedItemCount: Pre-fetch and buffer results in client memory (-1 = dynamic/optimal buffer)
    MaxBufferedItemCount = -1,

    // MaxItemCount: Number of items returned per page
    MaxItemCount = 100
};

// Cross-partition query: filter does not include the partition key (/categoryId)
string queryText = "SELECT * FROM c WHERE c.price > 50.0 ORDER BY c.price DESC";

using FeedIterator feedIterator = container.GetItemQueryIterator(
    queryText: queryText,
    requestOptions: queryOptions
);

double totalRUs = 0;
while (feedIterator.HasMoreResults)
{
    FeedResponse response = await feedIterator.ReadNextAsync();
    totalRUs += response.RequestCharge;

    foreach (Product product in response)
    {
        Console.WriteLine($"Found: {product.Name} - ${product.Price}");
    }
}

Console.WriteLine($"Query completed. Total Request Charge: {totalRUs} RUs");

By setting MaxConcurrency = -1 and MaxBufferedItemCount = -1, the SDK dynamically parallelizes requests across all physical partitions and pre-fetches upcoming result pages into client-side memory, significantly reducing overall latency.

More Info & Links

• Microsoft Learn: Tune query performance with Azure Cosmos DB .NET SDK
• Microsoft Learn: Troubleshoot query issues in Azure Cosmos DB
• Microsoft Learn: Best practices for Azure Cosmos DB .NET SDK
• Microsoft Learn: DP-420 study guide

DP-420 Style Practice Questions

Q1. What is the primary effect of setting MaxConcurrency = -1 in QueryRequestOptions when executing a cross-partition query?

• A. The SDK dynamically queries multiple physical partitions in parallel, reducing overall query latency
• B. The query is forced to execute sequentially against one partition at a time to minimize CPU usage
• C. Client-side buffering is disabled to prevent out-of-memory errors
• D. The query results are restricted to return only one document per partition

Q2. Which QueryRequestOptions property controls how many items are pre-fetched and stored in client-side memory during a cross-partition query?

• A. MaxBufferedItemCount
• B. MaxConcurrency
• C. ResponseContinuationTokenLimitInKb
• D. IdleTcpConnectionTimeout

Answer Key

Answers are listed at the very end so you can attempt the questions first.

• Q1 (Cross-Partition Query): A. The SDK dynamically queries multiple physical partitions in parallel, reducing overall query latency — Setting MaxConcurrency to -1 instructs the SDK to dynamically manage parallelism across physical partitions, fetching results concurrently to achieve the lowest query latency.
• Q2 (Cross-Partition Query): A. MaxBufferedItemCount — MaxBufferedItemCount controls client-side pre-fetching and buffering of items from parallel partitions, reducing wait time between page reads at the trade-off of client memory utilization.

---

DP-420: Designing and Implementing Cloud-Native Applications Using Microsoft Azure Cosmos DB — term detail page