Domain 1 of 3 · Chapter 1 of 5

Evaluate resource models and SDK solutions

The resource model and the scope of each setting

Picture an order service on one Azure Cosmos DB account, a retail database and an orders container partitioned on /customerId. A developer who wants one container on strong consistency, or the account to stop paying for idle hours, must first know which level owns the setting and its override scopes.

An account holds databases, a database groups containers, and a container stores JSON items. Microsoft defines the container as the unit of scalability for both throughput and storage[1]: the service partitions it horizontally across machines in a region and distributes it to every region of the account, and because containers are schema-agnostic, items of different shapes can share one container. The .NET SDK mirrors the hierarchy, as the figure below shows: a CosmosClient object represents the connection to one account and creates or returns databases, a Database object creates or returns containers, and a Container object reads and writes items (CosmosClient class reference[2]).

Scope Examples of settings it owns
Account default consistency level, capacity mode (provisioned throughput or serverless), free-tier discount, features such as dynamic scaling and priority-based execution
Database optional shared throughput for its containers
Container partition key path, indexing policy, unique key policy, optional dedicated throughput
Client or request relaxed read consistency, session token, priority level, throughput bucket, connectivity mode

The account also caps the hierarchy: it holds at most 500 databases and containers combined, a limit that can't be increased[3], and the requests that create, read or list databases and containers are metadata operations served from a separate account allowance of 240 RU/s (Request Units per second, the throughput measure). Adding throughput to a container does not enlarge that metadata allowance, which is why the SDK guidance later in this topic caches database and container references instead of looking them up on every request.

The Microsoft DP-420 study guide skills measured[4] lists consistency levels (The five consistency levels), RU consumption (Request Units: measuring what operations cost and Rate limiting (HTTP 429) and the SDK retry budget), throughput (Choosing a capacity mode to Sharing one container's throughput among workloads), account- and container-level settings (When account and container settings can change to Unique key policies), database and container management (Creating and managing databases and containers) and SDK clients (Initializing CosmosClient). It lists this topic, Evaluate resource models and SDK solutions, apart from 'Implement create, replace, update, patch and delete operations' under Implement database operations and 'Design and select partition keys based on cardinality, access patterns, and write distribution requirements' under Design and implement data models and partitioning strategies, both in Design and develop database solutions, and from 'Analyze index performance metrics' under Optimize and remediate database performance and 'Implement multi-region read and write configurations' under Implement availability and recovery solutions, both in Secure, optimize, and deploy database solutions. The rule to carry forward: name a setting's scope before you change it.

CosmosClient, one per accountclient and request optionsconnects toAccountdefault consistency, capacity modecontainsDatabaseoptional shared throughputcontainsContainerpartition key path, indexing policyunique key policydedicated throughputcontainsItemJSON item; shapes can vary
Hierarchy of an Azure Cosmos DB for NoSQL account: the client, account, database, container and item, with example settings each level owns.

The five consistency levels

Consistency answers one question for every read: how fresh, and how well ordered, is the data a replica returns while other replicas are still catching up. Azure Cosmos DB offers five well-defined consistency levels[5], from strongest to weakest: strong, bounded staleness, session, consistent prefix and eventual.

One replication model sits under all five. A logical partition is the set of items that share one partition key value, and one or more logical partitions map to a single physical partition[6], a service-managed unit that How throughput divides across physical partitions below returns to. Each physical partition keeps a set of four replicas in every region of the account. For every level weaker than strong, a write is acknowledged once a local majority (three of the four replicas) has it, and it reaches the other regions asynchronously; strong normally commits a write in every region before acknowledging it, subject to dynamic quorum (see What strong and bounded staleness cost below) in accounts with three or more regions (consistency levels[5]). The levels provide these read guarantees:

Level What a read is guaranteed to return Fits
Strong the most recent committed version of the item (linearizability); never an uncommitted or partial write a shared value that every reader must see current, such as an inventory count
Bounded staleness data that lags the writes by less than K versions or T time, whichever bound is reached first near-strong reads across regions with a measurable maximum lag
Session within one client session, the session's own writes (read-your-writes) and writes that follow its reads (write-follows-reads) per-user state such as a shopping cart
Consistent prefix writes made in one transaction, visible together and in commit order; single-document writes behave as eventual grouped updates that must never appear half-applied
Eventual no ordering guarantee; a read can even return a version older than one the client already read counts of likes or retweets

Session is the default level for a new account (manage consistency[7]) and the most widely used one: it gives an individual user correct behavior with write latency, availability and read throughput comparable to eventual. Its guarantee belongs to a session, not to the whole database, so it says nothing about what a different user sees; a shared figure such as stock on hand needs strong if every independent reader must see the latest committed version, because session does not make independent sessions current. The guarantee also assumes one writer session, or writers that share a session token, which Session tokens across application instances below explains.

Consistent prefix is easy to misread as "reads arrive in order". Microsoft's definition[5] is narrower: if transaction T1 writes Doc1 and Doc2 and transaction T2 then updates both, a read sees both first versions, both second versions, or neither document, but never a mix; writes that are not grouped in a transaction get eventual behavior. Consistent prefix also sets no maximum staleness interval. Eventual is weaker still: the client may read any one of the four replicas, and a later read can return older data than an earlier one, which rules it out for any client that needs its reads to move forward in time (monotonic reads).

In practice a weaker level often returns current data, for example when nothing is being written. The Probabilistically Bounded Staleness (PBS) metric, shown in the Azure portal under Metrics (Classic) on the Consistency tab, estimates the probability of strongly consistent reads for your workload[7]. Treat it as an observation of how the workload has behaved, not as a guarantee: a favorable PBS value never turns an account's eventual or session setting into strong or bounded staleness, and eventual data converging when writes stop is not a promise of freshness while writes continue.

Strong and bounded staleness reads consult two replicas, which makes their RU cost twice that of the weaker levels[5], whose reads consult one, as the figure below shows from strongest to weakest. The takeaway: pick the weakest level whose guarantee the scenario's reader genuinely needs.

Strongest guaranteeReads use 2 replicas (about 2x RU)StrongBounded stalenessReads use 1 replicaSessionConsistent prefixEventualWeakest guarantee
The five Azure Cosmos DB consistency levels from strongest to weakest, grouped by how many replicas a read consults.

What strong and bounded staleness cost

The two strongest levels buy their guarantees with extra replicas, extra latency and extra configuration rules, and each of those costs shows up in design questions.

Read cost. Strong and bounded staleness read from two replicas of the local four-replica set (a local minority quorum), while session, consistent prefix and eventual read from one. As a result[5], a read at strong or bounded staleness costs about twice the RUs of the same read at a weaker level, and a fixed RU/s budget delivers half the read throughput. Writes are different: for a given type of write (insert, replace, upsert or delete), the RU charge is identical at every level. Weakening the consistency level therefore lowers read cost, never the charge of the same insert workload.

Write latency across regions. For provisioned throughput, qualifying point reads and writes have an under-10-millisecond latency SLA (service-level agreement) at the 99th percentile, with one write-latency exception: an account that spans several regions with strong consistency. There, write latency at the 99th percentile equals twice the round-trip time (RTT) between the two farthest regions, plus 10 milliseconds[5], because a write is acknowledged only after every region commits it. Strong consistency for accounts whose regions span more than 5,000 miles (8,000 kilometers) is blocked by default, and enabling it requires contacting support. A requirement for globally current reads therefore has to be reconciled with the write-latency budget before you choose strong.

Multiple write regions. An account configured with multiple write regions can't use strong consistency[5]: a distributed system can't offer a recovery point objective (RPO, the window of recent writes you can lose) of zero and a recovery time objective of zero at the same time, and strong across several write regions wouldn't lower write latency anyway. It is an account-level incompatibility, so no client option produces both.

Dynamic quorum. Normally a strong write commits when all regions acknowledge it. In an account with three or more regions, the service can remove slow or unresponsive regions from the quorum to keep strong consistency available; a removed region can't serve reads until it becomes consistent again and rejoins the quorum[5].

Bounded staleness bounds. You configure K (versions, that is updates, of an item) and T (a time interval). For a single-region account the minimum K is 10 versions (Microsoft counts them as write operations) and the minimum T is 5 seconds; for a multi-region account they are 100,000 versions and 300 seconds (consistency levels[5]), so check the region count before accepting a proposed configuration. The bound is enforced per physical partition: if a physical partition's replication lag to another region exceeds it, writes to that physical partition are throttled until the lag is back inside the bound. Staleness is checked only across regions; within a region, writes always reach a local majority.

Bounded staleness is designed for accounts with one write region and two or more regions. In an account with multiple write regions where each application instance reads and writes its own local region, Microsoft calls bounded staleness an anti-pattern[5]: it adds a dependency on inter-region replication lag that local reads don't need, and session already supplies read-your-writes. In short, strong and bounded staleness double read RUs, strong adds cross-region write latency and excludes multiple write regions, and bounded staleness works best for single-write accounts with two or more regions.

Session tokens across application instances

Session consistency works only while the reader presents the right session token, and in a web tier with several instances that token does not travel on its own.

A session token is the client's record of how far its session has progressed. After every write, the server returns an updated session token[5]; the client caches it and sends it with later reads. A replica that holds data for that token, or for a newer one, answers; otherwise the client retries another replica in the region and, if needed, other regions. Three properties follow from that mechanism:

  • It is a minimum, not a snapshot. The token works as a minimum version barrier, never as a request for a specific historical version: if newer data exists, the read returns the latest version even when the token is old[5]. An old token can't be used to read an earlier version of an item.
  • It is partition-bound. A token belongs to one physical partition. If the client never wrote to a physical partition, it holds no token for it and reads there behave like eventual reads; a re-created client starts with an empty token cache and behaves the same way until new writes rebuild it.
  • It is opaque. When you pass a token from one client instance to another, don't modify its contents[5].

Now the multi-instance case. Each CosmosClient keeps its own token cache inside its own process. When a round-robin load balancer without session affinity sends a user's write to instance A and the follow-up read to instance B, instance B holds no token for that write, and the user can briefly fail to see their own change. Microsoft's remedy[7] is to send the token from the write response to the user, for example in a cookie, and have it flow back to whichever instance serves the next read, which sets it on that read's request options.

Passing a session token from a write to a later read (.NET SDK v3, adapted from the manage-consistency article). The first two lines run on the instance that writes; the last two statements run on the instance that reads:

ItemResponse<SalesOrder> response = await container.CreateItemAsync<SalesOrder>(salesOrder);
string sessionToken = response.Headers.Session; // opaque: store and forward it unchanged

// ... the token travels to the user (for example in a cookie) and back to another instance ...

ItemRequestOptions options = new ItemRequestOptions { SessionToken = sessionToken };
ItemResponse<SalesOrder> read = await container.ReadItemAsync<SalesOrder>(
    salesOrder.Id, new PartitionKey(salesOrder.PartitionKey), options);

response.Headers.Session is the token the write produced, and ItemRequestOptions.SessionToken is where the reading instance presents it. If you don't set a token, the SDK tracks tokens automatically and uses the most recent one it holds, which is enough for a single instance. The figure below follows the token from the write on instance A to the read on instance B. The takeaway: session consistency spans instances when the reading instance receives the relevant session token.

Instance A writes the itemWrite response returns the tokenToken travels with the userInstance B reads with that tokenReplica at or past the token answers
A session token's path across two web-tier instances: the write on instance A, the token carried by the user, the read with that token on instance B.

Setting and overriding the consistency level

Consistency is configured in two places, a default on the account and optional overrides from the SDK, and knowing which mechanism can move consistency in which direction settles most questions about it.

The account default. You can configure the default consistency level at any time[5] in the portal's Default consistency pane, with Azure CLI or with PowerShell, and it applies to every database and container in the account; there is no per-container consistency setting to persist. Read consistency is scoped to a single read operation within a logical partition, so it is not a transaction guarantee across items or containers. After changing the default, recreate any SDK instance[5], for example by restarting the application, so the SDK uses the new level.

Changing the account default with Azure CLI (from the manage-consistency article).

az cosmosdb update --name $accountName --resource-group $resourceGroupName --default-consistency-level Strong

The SDK offers two override mechanisms, and they differ in direction, scope and availability:

Capability Traditional ConsistencyLevel override ReadConsistencyStrategy (preview)
Weaker than the account default Yes Yes
Stronger than the account default No Yes
Client level and per request Yes Yes
Choices strong, bounded staleness, session, consistent prefix, eventual (relax only) default, session, eventual, latest committed, global strong
Availability every SDK the article shows (.NET, Java, JavaScript, Python, Go) Java SDK 4.69+ and .NET SDK 3.46+, Direct mode only

The traditional override relaxes only. A ConsistencyLevel set on the client or on a request, where the request setting overrides the client's, can only relax consistency[7]; to move from weaker to stronger with this mechanism, change the account default. A relaxed read also changes reads alone: an account set to strong still writes and replicates synchronously to every region[7], and the overridden reads switch to a single replica only when relaxed to session, consistent prefix or eventual. Setting ItemRequestOptions.ConsistencyLevel to Strong on an account whose default is eventual does not strengthen anything.

Relaxing one read (.NET SDK v3, from the manage-consistency article).

// item is the item id string.
ItemRequestOptions requestOptions = new ItemRequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };
var response = await client.GetContainer(databaseName, containerName)
    .ReadItemAsync<dynamic>(item, new PartitionKey(itemPartitionKey), requestOptions);

ReadConsistencyStrategy can strengthen, within limits. This newer mechanism is in preview and supported in Direct mode only[7], not in Gateway mode (the two SDK connectivity modes that Initializing CosmosClient below explains). The strategy table names its choices DEFAULT, SESSION, EVENTUAL, LATEST_COMMITTED and GLOBAL_STRONG; the .NET enum spells the fourth one ReadConsistencyStrategy.LatestCommitted. Two of them need care:

  • LATEST_COMMITTED performs quorum reads with barrier requests against the replicas in the local region and returns the latest data committed in that region. Replication across regions stays asynchronous, so unlike bounded staleness it provides no staleness bound across regions[7]. It can replace bounded staleness only when consistent reads are needed but a maximum inter-region lag is not.
  • GLOBAL_STRONG provides linearizable reads across all regions, the choice when a read must be globally current rather than merely fresh in its own region.

A client-level strategy in .NET (from the manage-consistency article).

CosmosClient client = new CosmosClientBuilder(endpoint, new DefaultAzureCredential())
    .WithReadConsistencyStrategy(ReadConsistencyStrategy.LatestCommitted)
    .Build();

If one request sets both ConsistencyLevel and ReadConsistencyStrategy, ReadConsistencyStrategy takes precedence[7]. In short: the account default sets the baseline, the traditional override can only relax reads, and only the preview strategy, in Direct mode, can ask for more than the default.

Request Units: measuring what operations cost

Every operation in Azure Cosmos DB, from a point read to a complex query, is billed and throttled in one currency, so sizing throughput starts with knowing what each operation costs.

A Request Unit (RU) is a performance currency that abstracts the CPU, I/O operations and memory[8] an operation needs; reading a single item of about 1 KB by its id and partition key costs about 1 RU. RU per second (RU/s) is a different quantity: the amount of that work provisioned to be available every second. An application's throughput need is therefore the sum of its operations' charges per second, never its request count; a query that costs 50 RUs uses as much of the budget as fifty 1-KB point reads.

What raises a charge. Microsoft lists these factors that affect RU charges[8]:

Factor Effect
Item size larger items cost more RUs to read and write
Indexing items are indexed by default; indexing fewer items or properties lowers write cost
Property count with default indexing, more properties make a write more expensive
Consistency strong and bounded staleness reads cost about twice as much (see What strong and bounded staleness cost above)
Type of read point reads cost fewer RUs than queries
Query pattern the number of results, the number and nature of predicates, user-defined functions, source data size, result size and projections all matter
Script usage stored procedures and triggers cost RUs according to the work they do

Item size deserves a second look for writes, because the request charge of an operation correlates directly to the size of the document[9]. A replace writes the whole item, so estimate it from the full item's size, not from the one property that changed. A unique key policy also adds a little to create, update and delete charges, as Unique key policies below explains.

Charges are deterministic. For a given operation over a given dataset, the number of RUs is deterministic[8]: the same query on the same data costs the same RUs on every execution. That is what makes measurement reliable, and why a workload estimate must represent the real query shapes, data, result sizes and script work rather than an average guess.

Measuring a charge. Every response reports its request charge, the RUs that operation consumed. Over HTTP it is the x-ms-request-charge header, which the Python SDK exposes through last_response_headers; in the .NET SDK v3 it is the RequestCharge property[10] on responses such as ItemResponse<T> and FeedResponse<T>. A query that returns several pages returns one response, with its own charge, per page, so the query's full cost is the sum across every page.

Summing the charge of a paged query (.NET SDK v3, adapted from the find-request-unit-charge article).

FeedIterator<dynamic> feedIterator = container.GetItemQueryIterator<dynamic>(
    queryText: "SELECT * FROM c",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey(partitionKey) });
double totalCharge = 0;
while (feedIterator.HasMoreResults)
{
    FeedResponse<dynamic> feedResponse = await feedIterator.ReadNextAsync();
    totalCharge += feedResponse.RequestCharge; // this page's charge only
}

The article's listing reads feedResponse.RequestCharge inside the same loop; the running total totalCharge is the addition. Page boundaries come from per-execution limits such as a 5-second execution time and a 4-MB response size (service limits[3]), and can also reflect insufficient available RUs or throttling; page count alone does not establish a cheaper query: compare total charges. For a query that spans multiple pages, the first page's charge alone is not the cost of the query.

One multiplier applies to provisioned throughput: RU/s set on a container or database are provisioned in every region of the account[8], so R RU/s across N regions is R x N RU/s in total. To sum up: size from measured request charges, add up every page, and know which factors move the charge.

Rate limiting (HTTP 429) and the SDK retry budget

When the operations in one second need more RUs than are available, Azure Cosmos DB rejects the excess instead of queuing it, and the way the application retries decides whether users notice.

With provisioned throughput, the cost of each operation is deducted from the RUs available every second[11]; a request that doesn't fit is rate limited with HTTP status 429 (Too Many Requests). A 429 is safe to retry[12], and the SDKs already do it: they retry 429 responses by default, following the client configuration and waiting for the interval in the response's x-ms-retry-after-ms header. Only when the SDK's retries are exhausted does the application see the error. At that point, use the x-ms-retry-after-ms value as the wait hint, an exponential back-off, or a larger retry budget, never an immediate resubmit loop that ignores the service's recovery interval.

In the .NET SDK v3, two CosmosClientOptions[13] properties set that retry budget, and they are independent:

  • MaxRetryAttemptsOnRateLimitedRequests: the maximum number of retries after rate limiting.
  • MaxRetryWaitTimeOnRateLimitedRequests: the maximum cumulative retry wait time.

Setting both retry limits (.NET SDK v3; the values are examples, not recommendations).

CosmosClientOptions options = new CosmosClientOptions
{
    MaxRetryAttemptsOnRateLimitedRequests = 9,                         // how many retries
    MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(30)   // maximum cumulative retry wait
};

The retries stop when either limit is reached, so raising only the attempt count may not produce more retries if the wait budget runs out first. RequestTimeout is a third, unrelated setting that bounds a single network wait (see Tuning CosmosClient options below); it does not configure 429 retries. Most important, a bigger retry budget adds no capacity: it trades latency for success while the cause remains.

The cause is usually one of three things, each covered elsewhere in this topic: the resource's total RU/s is too low for the workload; one physical partition's share is exhausted while the others are idle (see How throughput divides across physical partitions below); or metadata requests exceeded the account's fixed 240-RU/s metadata allowance from The resource model and the scope of each setting above, which raising container throughput cannot fix. The takeaway: let the SDK retry with the service's hint, size its budget to the latency the application tolerates, and fix the cause by adding or redistributing throughput or by lowering the charge.

Choosing a capacity mode

Before you create a single container, you choose how the account is billed and how much throughput it can deliver, and one move within that choice, from serverless to provisioned throughput, can't be undone later.

Microsoft describes two capacity modes[14], provisioned throughput and serverless, which run exactly the same database operations but bill them very differently. Provisioned throughput comes in two types[1], standard (manual) and autoscale, so there are three options in practice. These criteria, in the order that eliminates options fastest, choose among them:

Standard (manual) throughput. You assign RU/s in increments of 100 and can change them at any time[8], and you're billed hourly for the RU/s provisioned, whether or not the application consumes them. A nearly idle application on manual throughput still pays for its full allocation.

Autoscale throughput. You set a maximum, and the service scales between 10 percent of it and the maximum; Autoscale throughput, including dynamic scaling below covers it in full.

Serverless. You don't configure throughput when you create containers[11], and each billing period charges the RUs your operations consumed. The serverless account type is chosen when the account is created: to use serverless, you create a new serverless account. The other direction works in place, once: changing a serverless account to provisioned throughput is irreversible[15], and the account can't return to serverless. Three consequences matter for design, because each returns an error: you can't pass throughput when creating a serverless container, can't read or update its throughput, and can't create a shared-throughput database. Capacity isn't unlimited either. A serverless container begins with 5,000 RU/s, and each physical partition can handle up to 5,000 RU/s[11], so the container's maximum grows only as data growth adds physical partitions, and paying per RU does not buy unlimited instantaneous bursts. Don't size serverless with the 10,000-RU/s per-partition maximum of provisioned throughput (service limits[3]); that is the other mode's limit.

A worked comparison from Microsoft shows why total consumption, not peak alone, decides between manual throughput and serverless. A workload that bursts to 500 RU/s and consumes 20 million RUs in a month costs $29.20 provisioned versus $5.00 serverless[14] at the sample prices, while the same peak with 250 million RUs a month costs $29.20 versus $62.50; Microsoft labels these prices as demonstration figures only. The rule to keep: rule out serverless first on regions and SLA, then pick manual or autoscale by how steady the traffic is.

Autoscale throughput, including dynamic scaling

Autoscale is still provisioned throughput, with the same SLA, but the service moves the RU/s within a range you set instead of holding one fixed value.

The range. You configure a maximum throughput, Tmax, and the service scales the current throughput T so that 0.1 x Tmax <= T <= Tmax[16], automatically, instantly and without disrupting clients. A Tmax of 20,000 RU/s scales between 2,000 and 20,000 RU/s. The entry point is a Tmax of 1,000 RU/s (scaling between 100 and 1,000 RU/s), and Tmax is set in increments of 1,000 RU/s. The floor never reaches zero, so an idle autoscale container still provisions a tenth of Tmax. Storage is tied to Tmax too: a resource can hold 0.1 x Tmax GB, and when storage grows past that, the maximum rises automatically; a Tmax of 50,000 RU/s holds 5,000 GB, and at 6,000 GB the maximum becomes 60,000 RU/s.

The bill. Each hour is billed at the highest throughput T the system scaled to during that hour[16], and never less than 0.1 x Tmax (service limits[3]). A short spike to Tmax therefore sets the whole hour's charge, and averaging the consumed RU/s over the hour underestimates the invoice. Microsoft's guidance is that autoscale can save money when the full Tmax is used for 66 percent or fewer of the hours in a month.

Dynamic scaling. Classic autoscale scales every physical partition in every region to match the most active partition and region. Dynamic scaling (Microsoft also calls it dynamic autoscale) scales each physical partition in each region independently[16], based on its own usage, which avoids unnecessary scale-ups for uneven workloads such as hot partitions or a passive secondary region. Microsoft's example[16] is a container with a 1,000-RU/s maximum, up to 500 RU/s for each of two partitions, in a write region and a read region. RU/s are provisioned in every region (Request Units: measuring what operations cost above), so classic autoscale scales both partitions in both regions to the hottest one's level: 1,000 RU/s per region, 2,000 RU/s in total. Dynamic scaling follows each partition's hourly usage (500 and 200 RU/s in the write region, 150 and 50 in the read region): 900 RU/s in total. With dynamic scaling, the bill aggregates the highest RU/s each partition and region scaled to in the hour.

Dynamic scaling is an account-level feature, and its scope is narrower than the account:

  • It is enabled by default for accounts created after September 25, 2024[16]; older accounts enable it on the portal's Features page (Dynamic Scaling (Per Region and Per Partition Autoscale)) or through PowerShell, Azure CLI or the REST API, with zero downtime.
  • It applies to the account's autoscale containers and autoscale shared-throughput databases.
  • It doesn't affect resources on manual throughput, which must first be changed to autoscale, and it doesn't apply to serverless accounts.

Enabling dynamic scaling therefore never converts a manual container to autoscale. To recap: choose Tmax for the peak, expect to pay at least a tenth of it every hour and the hourly peak beyond that, and let dynamic scaling stop one hot partition or region from scaling the rest.

Dedicated versus shared throughput

Provisioned throughput can be attached at two granularities, a container or a database, and that choice decides whether a container's performance is guaranteed.

Dedicated throughput. RU/s provisioned on a container are exclusively reserved for that container[1], available all the time and backed by SLAs. It is the most frequently used option and Microsoft's recommended approach for most workloads: each container gets its own capacity, so one container's workload doesn't affect another's.

Shared throughput. RU/s provisioned on a database are shared by the database's containers, and Azure Cosmos DB provides no predictable throughput guarantee for any particular container[1] in it. A container's portion depends on the number of containers, their partition keys and how the workload spreads across logical partitions. Microsoft does not recommend shared database throughput for most workloads: scaling the database for one large container can repartition smaller co-located containers and spread them thinly, causing 429s and less consistent latency, especially when containers grow or are used at different rates. Shared throughput still fits advanced cases, such as many small containers that don't need isolation, a migration from a self-hosted cluster, or low-traffic deployment stamps[17] (independent copies of an application's components and data stores, each serving a predefined number of tenants), accepting that a busy tenant can affect the others. It is the wrong tool for giving each tenant container a guaranteed equal share, because the pool enforces no share at all.

Mixing the two. A database can hold both kinds of container, and the allocations stay separate. In Microsoft's example[1], database Z has K RU/s of shared throughput and five containers, and container B was created with its own P RU/s. K is shared by A, C, D and E only, with no per-container SLA, while B is guaranteed P all the time. The database's provisioned capacity is K + P in total, but B's P is never available to the other four.

The 25-container limit. A shared-throughput database is limited to 25 containers[1]; after the first 25, you can add containers only with dedicated throughput, which stays separate from the database's shared RU/s. Microsoft describes the limit as a change: an account that already contains a shared-throughput database with 25 or more containers is exempt from this change[1], along with every other account in the same subscription. That is a legacy exemption, not a way for a database to escape the limit by growing past 25 containers.

The choice is permanent per container. Shared and dedicated throughput are configured only when the database and container are created. A dedicated container can't be converted to a shared database container, and a shared container can't be converted to dedicated throughput[1]; you move the data to a new container with the desired setting, for example with a container copy job, covered in Implement change feed. This is not the same as switching a resource between manual and autoscale throughput, which changes how RU/s scale, not where they are attached. The rule: give a container dedicated throughput whenever its performance must be predictable, and decide at creation.

Changing provisioned throughput within its limits

Provisioned throughput can change after creation, but only between a floor and a ceiling that the service computes, and large changes are not always immediate.

The floor for manual throughput. For a container on manual throughput, the minimum RU/s is the maximum of[3] 400 RU/s, the current storage in GB x 1 RU/s, and the highest RU/s ever provisioned on the container divided by 100. Microsoft's example: a container raised to 50,000 RU/s that holds 20 GB has a minimum of MAX(400, 20, 500) = 500 RU/s, and once storage reaches 2,000 GB the minimum becomes 2,000 RU/s. A temporary scale-up for a bulk load therefore raises the floor you can later return to, so a container that once ran at 50,000 RU/s can't go back to 400 RU/s just because traffic is low.

The floor for autoscale. For autoscale, the floor applies to the Tmax you may set, not to the live throughput: the minimum Tmax is the maximum of 1,000 RU/s, the current storage in GB x 10 RU/s, and the highest Tmax ever provisioned divided by 10, rounded up to the nearest 1,000 RU/s[3]. Don't confuse it with the 0.1 x Tmax level that autoscale scales down to (Autoscale throughput, including dynamic scaling above), and don't apply the manual divisor of 100 to it.

Shared databases add a container-count term. The minimum for a shared-throughput database also includes 400 + MAX(container count - 25, 0) x 100 RU/s for manual throughput, and 1,000 + MAX(container count - 25, 0) x 1,000 RU/s for autoscale's minimum Tmax (service limits[3]). The term matters for the legacy-exempt databases (Dedicated versus shared throughput above) that hold more than 25 containers, where a container-only formula understates the minimum.

The ceiling. The provisioned-throughput overview says there's no limit on the maximum provisioned throughput you can configure[1]. The service limits page gives the precise rule behind that: the default maximum is 1,000,000 RU/s per dedicated container or shared-throughput database, increased by filing an Azure support ticket[3]. Raising that quota leaves the partition limits unchanged: a logical partition still serves at most 10,000 RU/s and normally stores at most 20 GB; support can grant a temporary storage-limit increase, without SLA guarantees.

Reading and changing throughput in .NET. ReadThroughputAsync[1] with the RequestOptions overload on a container or database reads its throughput, and the ThroughputResponse it returns also carries MinThroughput, the current floor to check before a scale-down. ReplaceThroughputAsync changes the allocation; for an existing autoscale resource, pass a new maximum built with ThroughputProperties.CreateAutoscaleThroughput. Neither method touches the container definition, which ReplaceContainerAsync replaces separately[18], so scaling RU/s never goes through container properties.

Creating an autoscale container, then raising its maximum (.NET SDK v3, from the autoscale how-to article).

ContainerProperties autoscaleContainerProperties = new ContainerProperties("ContainerName", "/partitionKey");
ThroughputProperties autoscaleThroughputProperties = ThroughputProperties.CreateAutoscaleThroughput(1000); // Tmax
container = await database.CreateContainerAsync(autoscaleContainerProperties, autoscaleThroughputProperties);

// ... later: change the autoscale maximum of the existing container
await container.ReplaceThroughputAsync(ThroughputProperties.CreateAutoscaleThroughput(newAutoscaleMaxThroughput));

CreateAutoscaleThroughput(1000) is what makes the new container autoscale with a Tmax of 1,000 RU/s; passing a plain integer throughput instead provisions manual RU/s.

Large increases can be asynchronous. A resource scales synchronously only between its minimum and 100 times that minimum[3]; beyond that range, scaling runs asynchronously and can take minutes to hours. Most increases are instantaneous, but a large increase can take longer[1] while the system provisions resources, and another modification attempted meanwhile returns HTTP 423, because a scaling operation is already in progress. The scaling operation has no SLA, so before a large ingestion, start the increase ahead of time and check ThroughputResponse.IsReplacePending until the replacement completes.

Switching between manual and autoscale. The SDKs can create new autoscale resources but don't support migrating between autoscale and standard (manual) throughput[19]; migration is supported in the Azure portal, Azure CLI and PowerShell, and Azure Resource Manager templates can't perform it. In Azure CLI, throughput migrate changes the mode and throughput update changes the amount within the current mode (CLI reference[20]).

Migrating a container's throughput mode, then updating its maximum (Azure CLI).

# manual -> autoscale (use --throughput-type manual for the reverse)
az cosmosdb sql container throughput migrate --account-name <account> --database-name <database> \
    --name <container> --resource-group <resource-group> --throughput-type autoscale

# change the autoscale maximum within the current mode
az cosmosdb sql container throughput update --account-name <account> --database-name <database> \
    --name <container> --resource-group <resource-group> --max-throughput 4000

In short: read MinThroughput before scaling down, scale up ahead of large jobs, and use migrate for a mode change but update or ReplaceThroughputAsync for a change of amount.

How throughput divides across physical partitions

Provisioned throughput is set on a container or database, but it is enforced per physical partition, so a resource can throttle while most of its RU/s sit idle.

A physical partition is the service-managed unit that hosts one or more logical partitions (each logical partition being all the items that share one partition-key value), and it serves at most 10,000 RU/s[3]; partition design is covered in Design data models and partitioning. Under the default throughput policy, Equal, the throughput provisioned for a container is evenly distributed among its physical partitions[1], and the logical partitions on one physical partition share its slice: 18,000 RU/s on three physical partitions gives each 6,000 RU/s. If one logical partition receives a disproportionate share of requests (a hot partition), its physical partition can exhaust its slice and return 429s while the other partitions still have spare capacity. Evaluate the slice available to the busy partition, not the resource total.

Redistributing throughput (preview). For resources on provisioned throughput, manual or autoscale[21], you can move RU/s from quiet physical partitions to busy ones, with or without raising the total; the feature doesn't apply to serverless accounts. Its rules:

  • The policy flips to Custom. After you redistribute or assign custom per-partition RU/s, the throughput policy changes from Equal to Custom, and changing throughput at the container or shared-database level is blocked until you set the policy back to Equal. This is by design, to preserve the custom allocations.
  • The total can change. A redistribution is not necessarily a transfer: if the requested per-partition values add up to a different total, the operation updates the resource's total throughput. Microsoft's example is a 10,000-RU/s container whose two partitions run at 5,000 RU/s each; assigning 20,000 RU/s to one of them makes it a 25,000-RU/s container, a cost change to plan for.
  • High targets split partitions. A target can be up to 20,000 RU/s, but anything above 10,000 RU/s triggers a split: the partition first receives 10,000 RU/s, then the service splits it and distributes the requested throughput evenly across the new partitions. No physical partition is allowed to stay above 10,000 RU/s.
  • A single hot key isn't helped. If one logical partition key is the cause, a split leaves that key on one partition, still capped at 10,000 RU/s.

The figure below traces Microsoft's example of a 15,000-RU/s target for a partition that currently runs at 5,000 RU/s.

Inspecting and redistributing per-partition throughput with Azure CLI (adapted from the redistribution article).

az extension add --name cosmosdb-preview   # the commands ship in the preview extension

az cosmosdb sql container retrieve-partition-throughput \
    --resource-group "<resource-group-name>" --account-name "<cosmos-account-name>" \
    --database-name "<cosmos-database-name>" --name "<cosmos-container-name>" \
    --all-partitions   # or --physical-partition-ids "<space-separated ids>"

az cosmosdb sql container redistribute-partition-throughput \
    --resource-group "<resource-group-name>" --account-name "<cosmos-account-name>" \
    --database-name "<cosmos-database-name>" --name "<cosmos-container-name>" \
    --target-partition-info "0=5000 1=20000"

retrieve-partition-throughput reads the current RU/s of the chosen physical partitions, and --target-partition-info lists the desired RU/s per physical partition id. Neither CLI command has a shared-throughput database equivalent; for databases, use the PowerShell cmdlets Get-AzCosmosDBSqlDatabasePerPartitionThroughput and Update-AzCosmosDBSqlDatabasePerPartitionThroughput. Don't reach for throughput migrate here either: it switches between manual and autoscale, not between partitions. The takeaway: a 429 on a resource with spare RU/s usually means one partition's slice ran out; redistribution moves capacity to that partition, but only a better partition key spreads a single hot key.

Partition 1 runs at 5,000 RU/s;target set to 15,000 RU/sPartition 1 first gets 10,000 RU/sService splits partition 1Two partitions, 7,500 RU/s eachHighest target allowed: 20,000 RU/s
Throughput redistribution (preview) above 10,000 RU/s: a 15,000-RU/s target first gives the partition 10,000 RU/s, then splits it into two 7,500-RU/s partitions.

Sharing one container's throughput among workloads

Picture a container that serves a storefront's product reads and also absorbs a nightly catalog import. When the import pushes demand past the container's RU/s, something gets throttled, and two features let you decide what. Choose by the job:

Need Feature Mechanism
Interactive requests should win when demand exceeds capacity Priority-based execution low-priority requests are throttled first
A workload must never consume more than a set share Throughput buckets (preview) each bucket caps its requests at a maximum percentage of the container's throughput

Neither feature reserves capacity or adds RU/s; both decide how a fixed budget is shared.

Priority-based execution. You enable it on the account's Features page[22], then mark requests High or Low through SDK request options; in .NET (SDK 3.38.0 or later), that is ItemRequestOptions.PriorityLevel. When the requests to a container exceed its configured RU/s, Azure Cosmos DB throttles low-priority requests to prioritize high-priority ones, and the SDK retries the throttled low-priority requests under its configured retry policy. Requests without a priority run as High by default once the feature is enabled. The feature works on a best-effort basis with no SLA[22]: it doesn't always throttle low-priority work first. Don't confuse it with bulk execution (AllowBulkExecution), which groups many independent operations to raise aggregate throughput but assigns no service-side priority, as Implement database operations explains.

Marking background writes Low and user reads High (.NET SDK v3, adapted from the priority-based execution article).

// catalog import: preferentially throttled under contention (best effort)
ItemRequestOptions catalogRequestOptions = new ItemRequestOptions { PriorityLevel = PriorityLevel.Low };
await container.CreateItemAsync<Product>(product1, new PartitionKey("productId1"), catalogRequestOptions);

// shopper-facing read
ItemRequestOptions getProductRequestOptions = new ItemRequestOptions { PriorityLevel = PriorityLevel.High };
await container.ReadItemAsync<Product>("productId2", new PartitionKey("productId2"), getProductRequestOptions);

Throughput buckets (preview). After the subscription is registered for the preview, you activate up to five buckets on a container, each with a maximum throughput percentage[23]. Requests assigned to a bucket can consume throughput only up to that percentage and are throttled beyond it, but the throughput is not reserved for the bucket: it stays shared across all workloads. Requests assigned to no bucket use the container's throughput without restriction, unless you configure one bucket as the container's default. Assign a single request with ItemRequestOptions.ThroughputBucket, or every request from a client with CosmosClientBuilder.WithThroughputBucket. When bulk execution is enabled, a bucket can't be assigned to an individual request[23], so a bulk client uses the client-level setting. Buckets aren't supported for containers in a shared-throughput database or in serverless accounts. They are not throughput redistribution either: a bucket caps a workload, while redistribution assigns RU/s to physical partitions (How throughput divides across physical partitions above).

In short: use priority to choose who is throttled first, use a bucket to cap a workload's share, and add RU/s when every workload genuinely needs more.

When account and container settings can change

When you provision a new account and its first containers, some answers can be changed with one command later and some are locked in from the start; the scopes are those of The resource model and the scope of each setting above.

Setting Scope When you can change it
Capacity mode (provisioned throughput or serverless) Account At creation, or irreversibly from serverless to provisioned throughput in place; serverless means creating a new serverless account
Free-tier discount Account Only at creation
Default consistency level Account Any time; recreate SDK clients afterward
Dynamic scaling Account Enable any time (on by default for accounts created after September 25, 2024)
Priority-based execution Account Enable any time on the Features page
Shared throughput Database At database creation
Partition key path Container Only at creation
Dedicated versus shared throughput Container Only at creation
Unique key policy Container Only at creation
Indexing policy Container Any time
Amount of RU/s; manual versus autoscale Database or container Any time, within the limits in Changing provisioned throughput within its limits above, and while the throughput policy is Equal (How throughput divides across physical partitions above)

Regions are account settings too: you can add more regions to your account later[24], unless it is serverless (Choosing a capacity mode above).

Free tier. The free tier gives the first 1,000 RU/s and 25 GB of storage in the account for free[25] for the lifetime of the account, and throughput and storage beyond that are billed at the regular price. You can have at most one free-tier account per Azure subscription, and you must opt in when you create the account (the portal's Apply Free Tier Discount option, or "enableFreeTier": true in an Azure Resource Manager template); you can't set it after the account is created[25]. Free tier works with provisioned (manual or autoscale) throughput and with single or multiple write regions, but isn't currently available for serverless accounts. Planning to add free tier to an existing account after loading data misses the only opt-in point. The pattern to remember: check each setting's mutability; a container's indexing policy can change later.

Default indexing policy

Each new container gets its own indexing policy, which belongs to the container, not to the account or the client. A new container's default policy indexes every property of every item and enforces range indexes for any string or number[26], so queries work without creating an index property by property. A range index is an ordered, tree-like index used for equality, range and ORDER BY queries[27], among others. The policy's indexing mode takes one of two values:

  • Consistent: the index is updated synchronously as items are created, updated or deleted, and queries then return data at the account's configured consistency level.
  • None: indexing is disabled, which suits a container used as a pure key-value store with no secondary-index queries (it can also speed up bulk operations).

Indexing mode is not one of the five consistency levels: setting it to None turns indexing off, it does not request eventual reads. A third, lazy mode can return inconsistent or incomplete query results, and new containers can't select it[26]. Time to live (TTL) can't be activated on a container whose indexing mode is None. A container's indexing policy can be updated at any time[26], through an online, in-place index transformation; see Optimize and remediate database performance. The takeaway: every property is indexed by default, and None disables indexing rather than relaxing consistency.

Unique key policies

A unique key policy adds a uniqueness rule that Azure Cosmos DB enforces on writes, and its scope, shape and timing need careful consideration.

Scope: one logical partition. A unique key makes sure that one or more values are unique within a logical partition[28]. Microsoft's example container is partitioned on CompanyID with the email address as the unique key: two items with the same email can't exist under the same CompanyID, but the same email can appear under different companies. To make a value unique per tenant, partition by the tenant identifier and put a unique key on the value; a unique key can't enforce uniqueness across all partition-key values. A create or update that would produce a duplicate is rejected with a message such as Resource with specified ID, name, or unique index already exists.

Shape: one constraint can span several paths. A composite unique key groups paths, for example first name, last name and email address, into one constraint, and then only the combination must be unique within the logical partition; each component on its own can repeat. Separate single-path constraints would instead make each value independently unique, which is wrong for a rule like no duplicate full names. The policy's limits count the two shapes differently:

Limit Value How it counts
Unique key constraints per policy 10[28] a composite constraint counts once
Path values per policy 16 every path in every constraint counts, so a three-path composite uses 3 of the 16

Timing: only at creation. You can define unique keys only when you create the container[28], and the policy can't be changed afterward. To add or change one, create a new container with the policy and move the data, for NoSQL containers with a container copy job (Implement change feed); check the existing data for values that would conflict before copying.

Missing and mis-cased paths. Unique keys are not sparse: an item missing a constrained path contributes null, and nulls take part in the constraint, so with a single-path policy only one item per logical partition can lack the value. Unique key paths are case-sensitive as well. A policy on /address/zipcode against items that store ZipCode records null for every item, so the second such item fails. JSON values are case-sensitive too: Gaby and gaby are different values.

Cost. With a unique key policy in place, RU charges to create, update and delete an item are slightly higher[28], so include the enforcement overhead in write-cost estimates. To sum up: a unique key is enforced per logical partition, fixed from creation, counts missing values as null, is case-sensitive and adds a small write charge.

Creating and managing databases and containers

Application startup code usually creates or verifies its database and containers, and the .NET SDK methods for that look alike but behave differently.

Create versus create-if-not-exists. CosmosClient.CreateDatabaseIfNotExistsAsync and Database.CreateContainerIfNotExistsAsync check whether the named resource exists and create it only if it doesn't, which makes them safe to call on every startup (CosmosClient class[2], Database class[29]). The plain CreateDatabaseAsync and CreateContainerAsync send a create request every time, so use them when the resource must be new. Run either kind during setup, not on the request path: the .NET best practices say CreateIfNotExist should only be used once for setting up the database[9], because such calls are metadata operations that draw on the account's fixed metadata allowance (The resource model and the scope of each setting above).

Create-if-not-exists checks existence, not configuration equivalence. For containers, the container id is used to verify whether a container exists[29]; the SDK also checks for a partition-key path mismatch, including hierarchical paths, and throws ArgumentException if they differ. Throughput is not reconciled and can differ from the value you passed. The database method works the same way with the database id (CosmosClient class[2]). Calling CreateContainerIfNotExistsAsync with a new throughput value against an existing container therefore changes nothing; inspect the existing settings and change them with ReplaceThroughputAsync (Changing provisioned throughput within its limits above).

Defining the container. The simplest overload, Database.CreateContainerAsync(id, partitionKeyPath, throughput), takes the container id, the partition-key path and an optional throughput. The path names the JSON property, such as /category; it is not a partition-key value such as bikes. When the definition needs more, such as a unique key policy, an indexing policy or hierarchical partition key paths, pass a ContainerProperties object instead (Database class[29]). A throughput value passed at creation gives the container dedicated throughput; omitting it in a shared-throughput database makes the container share the database's RU/s.

Initializing a database and container at startup (.NET SDK v3).

// startup only: both calls check by id and create only when missing
Database database = await client.CreateDatabaseIfNotExistsAsync("retail");
Container products = await database.CreateContainerIfNotExistsAsync("products", "/category", 400);
// "/category" is the partition-key path; 400 is dedicated manual RU/s

Getting a reference is not checking existence. CosmosClient.GetContainer(databaseId, containerId) returns a proxy reference to a container, and the proxy doesn't guarantee existence[30]; ensure existence with CreateContainerAsync or CreateContainerIfNotExistsAsync. A non-null proxy proves nothing about deployment, and a wrong name surfaces only when a real operation runs against it. Keep the references you obtain and reuse them, as the best practices recommend for database and container names, rather than calling creation methods on every request.

Deleting. Resource deletion uses resource methods: Database.DeleteAsync[29] deletes a database and Container.DeleteContainerAsync[18] deletes a container, while Container.DeleteItemAsync deletes one item addressed by id and partition key and leaves the container and its configuration in place. Deleting every item never removes the container itself.

One account-wide limit applies to all of this: databases and containers together can't exceed 500 per account (service limits[3]), and Microsoft advises against container-per-tenant and database-per-tenant designs[11] in favor of a partition key per tenant or an account per tenant. The takeaway: initialize with the if-not-exists methods once at startup, reuse the references, and change settings with the throughput and container methods built for that.

Initializing CosmosClient

Every SDK call flows through a CosmosClient, and two main decisions made when constructing it, how many instances to create and which connectivity mode to use, shape latency and connection usage for the life of the application; an optional region preference then steers its routing.

One client per account. CosmosClient is thread-safe, and Microsoft recommends a single instance per lifetime of the application[2] for efficient connection management and performance; the client caches connections and routing information and reuses them across all the databases and containers in the account. An application whose tenants are separate databases, containers or partition keys within the same account should use a single client instance[9]. Only when tenants live in different accounts do you need one client per account, each still kept for the application's lifetime. Creating a short-lived client per request or per operation throws those caches and connection pools away.

Two connectivity modes. The SDK connectivity modes[31] decide the route that data operations take:

Property Gateway mode Direct mode
Protocol HTTPS TCP, encrypted with TLS (Transport Layer Security)
SDKs all SDKs .NET and Java only
Route to a gateway server in the frontend, which fans out the requests to the partitions straight to the backend replicas, with fewer network hops
Ports 443 for the NoSQL API 10000 through 20000 on public or service endpoints (0 through 65535 on private endpoints), in addition to the gateway port
Best for strict firewalls; a limited number of sockets best performance where the network allows it

Gateway mode is not a dedicated gateway: a dedicated gateway is server-side compute you provision as a front end to the account, and it hosts the integrated cache[32]; Gateway mode reaches the standard gateway or a dedicated gateway, depending on the configured endpoint.

Direct mode is the preferred option for performance, and the .NET checklist says to use Direct mode for the best performance[9]. Gateway mode is the right answer when outbound traffic is restricted to the standard HTTPS port, when sockets are scarce (Azure Functions on the Consumption plan is Microsoft's example), and for Python, JavaScript and every other SDK that doesn't implement Direct mode. Selecting Direct in the client options can't open ports the network blocks; with the TCP range closed, requests can fail with 503 Service Unavailable.

Direct mode still uses the gateway. To route an operation, a Direct-mode client first obtains the container information and the replicas' TCP addresses from a gateway node[31] over HTTPS. This control-plane metadata is cached, and the established TCP connections are reused across operations; when replicas move, the SDK refreshes the routing information through new gateway requests. A Direct-mode client in a network that allows the backend TCP range but blocks the gateway's HTTPS endpoint therefore can't initialize. The figure below shows both routes.

How many connections Direct mode opens. Connections are opened on demand as operations reach new physical partitions, and two factors drive the count[31]: the number of physical partitions (in a steady state, one connection per replica, about four per physical partition) and the volume of concurrent requests, because each connection serves a configurable number of concurrent operations and extra connections open beyond it. Estimate socket demand from both; Tuning CosmosClient options below shows the settings that bound it.

Region preferences. In the .NET SDK, ApplicationRegion[13] tells the client the location where the application is running, which influences the SDK's choice of region, and ApplicationPreferredRegions supplies an ordered list of preferred regions instead. Both only steer this client's routing; neither adds a region to the account or changes its write region, which is account configuration covered in Implement availability and recovery. The takeaway: build one client per account at startup, choose Direct where both the TCP range and the gateway's HTTPS endpoint are reachable, Gateway otherwise, with any region preference as client routing only.

SDK client(CosmosClient)HTTPS 443Gateway(HTTPS endpoint)fans outBackend replicasper physical partitionDirect modeTCP 10000-20000Gateway mode: all requests via gatewayDirect mode: gateway for metadata only
The two SDK connectivity modes: Gateway mode routes every request through the HTTPS gateway; Direct mode uses TCP to the replicas and the gateway only for metadata.

Tuning CosmosClient options

After the connectivity mode, a handful of CosmosClientOptions properties tune how the client uses connections, how long it waits and how it serializes your items. They group by concern, and a possible mistake is reaching for a setting from the wrong group:

Concern Settings What they control
Idle Direct connections IdleTcpConnectionTimeout, PortReuseMode when unused TCP connections close; how client ports are reused
Active Direct concurrency MaxRequestsPerTcpConnection, MaxTcpConnectionsPerEndpoint requests per TCP connection; TCP connections per backend endpoint
HTTPS connections GatewayModeMaxConnectionLimit, HttpClientFactory the SDK-managed HTTP connection limit; a custom HttpClient
Time limits RequestTimeout, plus a CancellationToken on each call one network wait; the whole operation
Serialization SerializerOptions, UseSystemTextJsonSerializerWithOptions, Serializer how your item payloads convert to and from JSON

Idle Direct connections. By default, idle connections are kept open indefinitely[9]. For sparse or sporadic workloads, Microsoft's guidance sets IdleTcpConnectionTimeout so unused connections close, and PortReuseMode to PrivatePortPool so the SDK uses a small pool of ephemeral ports, which together guard against ephemeral port exhaustion. The timeout must be at least 10 minutes, with 20 minutes to 24 hours recommended; low values close connections too often[31] and hurt overall performance. Neither setting raises how many requests can run at once, and creating a new client after each operation to free ports is the wrong fix, because it also discards the routing caches.

Active Direct concurrency. MaxRequestsPerTcpConnection sets how many requests can share one TCP connection, and MaxTcpConnectionsPerEndpoint caps the TCP connections to each backend; together they limit the requests sent simultaneously to a single backend[13] to their product. This is the active concurrency budget, separate from idle lifetime and port reuse.

HTTPS connections. The .NET SDK uses HttpClient regardless of the connectivity mode[9]: for data and metadata operations in Gateway mode, and for metadata operations in Direct mode. GatewayModeMaxConnectionLimit sets the maximum number of concurrent connections allowed for the target service endpoint[13] on the SDK-managed HTTP handler; Direct TCP settings such as MaxTcpConnectionsPerEndpoint don't touch that pool. HttpClientFactory accepts a delegate that supplies the HttpClient the client uses for HTTPS, which lets the application share and configure its own handler; once you supply one, connection limits are whatever you set on that handler. It doesn't replace Direct mode's TCP transport. One handler setting matters for availability: as long as pooled connections are kept open, they don't react to DNS changes[9], so set SocketsHttpHandler.PooledConnectionLifetime to close them periodically. Microsoft suggests starting at 5 minutes and balancing the cost of creating connections against how quickly the application must react to DNS changes.

Supplying a handler with a pooled-connection lifetime (.NET SDK v3, from the .NET best-practices article). The listing is only the body of the method that builds the application's single CosmosClient; the method signature is omitted.

// one SocketsHttpHandler, shared by every HttpClient in the application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5); // periodic reconnects pick up DNS changes

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // disposeHandler must be false so the shared handler outlives each HttpClient
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// still one CosmosClient for the application's lifetime
return new CosmosClient("<connection-string>", cosmosClientOptions);

Time limits. RequestTimeout is the time to wait for a response to come back from the network peer[13]: one network wait, not a cap on the whole operation with its internal work and retries. To get end-to-end timeouts, use both RequestTimeout and CancellationToken[9], passing the token to the SDK call so the operation stops when the application's deadline expires.

Asynchronous all the way. Use async and await through the whole call stack, and avoid the blocking calls Task.Result, Task.Wait and Task.GetAwaiter().GetResult()[9]; many synchronous blocking calls lead to thread-pool starvation and degraded response times. An asynchronous SDK call gains nothing if its caller immediately blocks on it.

Serialization. Prefer the built-in options before writing code. SerializerOptions takes a CosmosSerializationOptions for supported settings, such as IgnoreNullValues = true in the CosmosClientOptions example[13], and UseSystemTextJsonSerializerWithOptions makes System.Text.Json the serializer for your items, with the JsonSerializerOptions you pass. A custom CosmosSerializer assigned to Serializer is for behavior the built-in options don't supply. All three cover only user payloads: SDK-owned types such as DatabaseProperties and ContainerProperties always use the SDK's default serializer, so a custom serializer can't change how a container definition is serialized. Switching items to System.Text.Json also doesn't remove Newtonsoft.Json: the SDK's internal operations still use it for system types[9], so the project needs an explicit Newtonsoft.Json reference, version 13.0.3 or higher. The takeaway: match each symptom to its group (idle sockets, active concurrency, the HTTPS pool, deadlines or payload format) before changing a setting.

Capacity options: provisioned throughput (standard (manual) or autoscale) versus serverless

CriterionProvisioned: standard (manual)Provisioned: autoscaleServerless
Best suited forSustained, predictable trafficVariable or unpredictable trafficIntermittent traffic with a low average-to-peak ratio
What you configureA fixed RU/s, in increments of 100A maximum RU/s (Tmax), in increments of 1,000Nothing: resources take no throughput setting
Throughput availableThe provisioned RU/sScales between 0.1 x Tmax and TmaxUp to 5,000 RU/s per physical partition
BillingProvisioned RU/s per hourHighest RU/s reached in the hour, at least 0.1 x TmaxRUs consumed
Azure regionsAny numberAny numberOne region only
Latency commitmentUnder 10 ms point reads and writes (subject to SLA conditions); multi-region strong writes: 2 x farthest-region RTT + 10 ms at the 99th percentileUnder 10 ms point reads and writes (subject to SLA conditions); multi-region strong writes: 2 x farthest-region RTT + 10 ms at the 99th percentileUnder 10 ms point reads, under 30 ms writes (SLO)
Shared database throughputYes, up to 25 containersYes, up to 25 containersNot available

Decision tree

Need a second regionor a latency SLA?NoYesIntermittent trafficwith idle periods?YesNoServerlesspay per RU consumedSteady, predictabletraffic?YesNoManual throughputfixed RU/sAutoscaleup to Tmax

Sharp facts the exam loves — give these one last read before exam day.

Cheat sheet

Sharp facts the exam loves — scan these before test day.

Strong consistency returns the latest committed item version

When every reader must observe the latest committed item version, use strong consistency because it provides linearizability. The guarantee applies to committed data rather than exposing partial writes. It is stronger than the user-specific freshness provided by session consistency.

Trap Using session consistency for a shared inventory figure, which preserves a client's session guarantees rather than freshness across independent sessions.

3 questions test this
Bounded staleness limits lag by versions or elapsed time

Bounded staleness constrains replication lag by K item versions or T time, whichever bound is reached first. If a partition's inter-region lag exceeds the configured bound, writes to that partition are throttled until replication catches up. Choose it when a measurable freshness bound is required without demanding the most recent global commit on every read.

Trap Choosing consistent prefix for a maximum-age requirement, which supplies no configured time or version bound.

3 questions test this
Bounded-staleness minimums depend on the number of regions

Bounded staleness permits minimum settings of 10 versions and 5 seconds for a single-region account. For an account with multiple regions, the minimum settings are 100,000 versions and 300 seconds. Check the account's region count before accepting a proposed staleness configuration.

3 questions test this
Session consistency preserves a user's read-your-writes guarantee

When a user must immediately read their own updates while other sessions may lag, use session consistency. Within the session it provides read-your-writes and write-follows-reads guarantees, with latency and read throughput comparable to eventual consistency. Multiple participating clients must share the relevant session token to preserve the same session boundary.

Trap Choosing bounded staleness solely for a shopping-cart session, which adds quorum-read cost when only session-local guarantees are required.

1 question tests this
Consistent prefix preserves the visibility of transactionally grouped writes

Consistent prefix returns transactionally grouped updates consistently with their commit order: writes within a transaction are visible together. It does not impose a maximum staleness interval. Current documentation distinguishes this transaction grouping from independent single-document writes, which can exhibit eventual consistency.

Trap Selecting eventual consistency for ordered transactional visibility, which provides no ordering guarantee.

1 question tests this
Eventual consistency can return data older than a previous read

Eventual consistency reads from a replica that can be behind other replicas, so a client can receive stale data or even a version older than one it previously read. Use it for workloads that tolerate temporary discrepancies and require no ordering guarantee. Convergence in the absence of new writes is not a promise of immediate freshness.

Trap Using eventual consistency for a client that requires monotonic reads, which allows later reads to regress.

2 questions test this
Strong and bounded-staleness reads cost twice as many RUs

Strong and bounded-staleness reads consult two replicas, whereas session, consistent-prefix, and eventual reads consult one. For the same read workload, the quorum-read levels consume approximately twice the RUs and provide half the read throughput at a fixed RU budget. Write RU charges for the same write operation are identical across consistency levels.

Trap Weakening consistency to reduce the RU charge of the same insert workload, which changes read cost rather than the write operation's RU charge.

3 questions test this
Strong consistency adds inter-region distance to write latency

Strong consistency across multiple regions must coordinate commits across regions, so geographically distant regions increase write latency. The documented 99th-percentile write-latency expression is twice the round-trip time between the farthest regions plus 10 milliseconds. A requirement for globally current reads therefore needs to be reconciled with the write-latency budget.

Trap Choosing strong consistency to improve geographically distributed write latency, which adds synchronous inter-region coordination.

2 questions test this
Strong consistency cannot be used with multiple write regions

Strong consistency is unsupported on an Azure Cosmos DB account configured with multiple write regions. Treat this as a compatibility constraint when choosing a consistency level. A design cannot obtain both configurations simply by changing a client's consistency option.

Trap Selecting strong consistency for an existing multi-write account, which combines incompatible account settings.

1 question tests this
Dynamic quorum preserves strong consistency by excluding unhealthy regions

In a strongly consistent account with at least three regions, dynamic quorum can remove slow or unresponsive regions from the quorum to improve write availability and replication latency. Removed regions cannot serve reads until they become consistent with the other regions and rejoin the quorum.

Bounded staleness is an anti-pattern for local reads and writes in a multi-write account

When each application instance reads and writes in its local writable region and needs no cross-region staleness bound, avoid bounded staleness. Its inter-region replication-lag dependency adds a constraint that this local access pattern does not require. Select a weaker level that meets the application's actual read guarantees instead.

Trap Choosing bounded staleness solely to obtain local read-your-writes behavior, which session consistency can provide without imposing the inter-region lag bound.

1 question tests this
PBS estimates observed freshness rather than configuring a consistency guarantee

Probabilistically Bounded Staleness (PBS) estimates the probability that a workload using weaker consistency receives strongly consistent reads in practice. A favorable PBS observation describes that workload's observed behavior; it does not replace the account's configured consistency guarantee with bounded staleness or strong consistency.

The account's default consistency applies to its databases and containers

Azure Cosmos DB configures the default consistency level at account scope, and reads and queries in its databases and containers inherit that default. Read consistency applies to an individual read operation within a logical partition; it is not a cross-container transaction guarantee. Recreate SDK client instances after changing the account default so they use the new setting.

Trap Assigning separate persisted default consistency levels to two containers in one account, which mistakes an account default for a container policy.

2 questions test this
The traditional ConsistencyLevel override only weakens reads

The SDK's traditional ConsistencyLevel setting can relax read consistency at client or request scope, and a request setting overrides the client default. It cannot strengthen the account default through that mechanism. Relaxing a read also leaves the account's write-replication behavior unchanged.

Trap Setting ItemRequestOptions.ConsistencyLevel to Strong on an eventual account, which attempts to strengthen consistency through a relax-only override.

3 questions test this
A session token is a partition-bound minimum-version barrier

A session token identifies the minimum session progress a read must honor for the relevant partition. It does not request a historical snapshot: a replica with newer committed data can return that newer data. Preserve tokens as opaque values rather than parsing or editing their contents.

Trap Reusing an older session token to retrieve an earlier item version, which confuses a minimum-version barrier with historical version selection.

2 questions test this
Session tokens must follow the user across independent client instances

When a write and subsequent read can reach different application instances, pass the write's session token to the instance performing the read. Each CosmosClient maintains its own token cache, so another instance does not automatically know the user's most recent write. Without a relevant token, a session read can behave like an eventual read for that partition.

Trap Relying on the session-token cache in a different web server's CosmosClient, which is not shared across processes.

2 questions test this
ReadConsistencyStrategy is a separate direct-mode read-control mechanism

ReadConsistencyStrategy is a preview feature documented for Java SDK 4.69 or later and .NET SDK 3.46 or later. Unlike the traditional ConsistencyLevel override, it permits supported read strategies stronger than the account default. It is supported only in Direct mode, so it cannot be substituted into a Gateway-mode design.

Trap Applying ReadConsistencyStrategy to a Gateway client, which does not support this preview mechanism.

LATEST_COMMITTED guarantees local committed freshness rather than a global lag bound

The LATEST_COMMITTED read strategy (part of the preview ReadConsistencyStrategy feature) performs quorum reads and barrier requests against replicas in the local region to obtain the latest locally committed data. Cross-region replication remains asynchronous, so the strategy does not impose bounded staleness across regions. Use its local freshness guarantee only when a global time-or-version bound is unnecessary.

Trap Replacing bounded staleness with LATEST_COMMITTED while retaining a maximum inter-region lag requirement, which the local-region strategy does not guarantee.

2 questions test this
GLOBAL_STRONG requests globally linearizable reads through ReadConsistencyStrategy

The preview ReadConsistencyStrategy mechanism includes GLOBAL_STRONG, documented as providing linearizable reads across all regions. Choose that strategy when a read must be globally linearizable rather than just locally fresh.

Trap Choosing LATEST_COMMITTED for a globally current read requirement, which establishes freshness within the local region rather than global linearizability.

Session is the default consistency level for a new account

Azure Cosmos DB applies session consistency to a new account when another consistency level is not selected.

ReadConsistencyStrategy takes precedence over ConsistencyLevel on the same request

In the direct-mode-only ReadConsistencyStrategy preview, ReadConsistencyStrategy determines the read behavior when both it and ConsistencyLevel are specified on the same request.

RUs measure operation work while RU/s measures available throughput

A Request Unit normalizes CPU, I/O, and memory consumed by an Azure Cosmos DB operation. Provisioned RU/s describes how much of that work is available per second, not the number of requests the application may send. Operations with different complexity therefore consume different portions of the same throughput allocation.

Trap Sizing RU/s as one unit per application request, which ignores differences between operation charges.

1 question tests this
Response request-charge metadata reports the work an operation consumed

Use the x-ms-request-charge response header, or RequestCharge on a .NET SDK response, to measure RU consumption. For a paged query, add the charge from every page to obtain the complete query charge. The charge measures work already performed rather than the container's provisioned RU/s.

Trap Treating the first query page's RequestCharge as the complete query cost, which omits work performed by subsequent page requests.

1 question tests this
Larger items require more RUs to read and write

Item size is a primary RU charge driver: reading or writing a larger JSON item generally consumes more RUs. With default indexing, additional indexed properties also increase write work. A design that repeatedly replaces a large item should account for the whole written item's size, not only the changed property's size.

Trap Estimating a full replace from the size of its one changed field, which ignores the rest of the rewritten document.

2 questions test this
Equivalent operations on the same data have deterministic RU charges

Azure Cosmos DB makes RU charges deterministic for a given operation over a given dataset. Repeating the same query against unchanged data has the same total RU cost even if the service divides results into different page sizes. Query complexity, source data, result size, and script work must all be represented in a workload estimate.

Trap Assuming a different number of response pages proves that unchanged query logic became cheaper, which confuses paging with total operation work.

2 questions test this
HTTP 429 retries should respect the service's retry-after interval

HTTP 429 indicates request-rate throttling, represented by HttpStatusCode.TooManyRequests in .NET. Azure Cosmos DB SDKs retry these responses automatically according to their configured limits and honor x-ms-retry-after-ms. If retries are exhausted, the application receives the error and should use the retry-after guidance or an appropriate backoff policy.

Trap Immediately resubmitting every throttled request in a tight loop, which disregards the service's indicated recovery interval.

2 questions test this
Manual throughput suits sustained predictable demand

When a workload has sustained, predictable traffic, manual provisioned throughput lets you reserve a fixed RU/s allocation. Billing is based on the provisioned capacity per hour even if the application consumes fewer RUs. Throughput changes use increments of 100 RU/s, subject to the resource's current minimum.

Trap Choosing manual throughput for a nearly idle application solely to pay for consumed requests, which is the serverless billing model.

1 question tests this
Autoscale varies throughput between one tenth of Tmax and Tmax

When a provisioned workload has variable or unpredictable demand, configure autoscale with the required maximum throughput Tmax. The service scales between 0.1 times Tmax and Tmax without application interruption. The entry maximum is 1,000 RU/s, and configured maximums use increments of 1,000 RU/s.

Trap Sizing autoscale as if idle capacity falls to zero, which ignores its one-tenth minimum.

2 questions test this
Autoscale billing follows the highest scaled throughput within the hour

Autoscale is still provisioned capacity, not per-request serverless billing. Under uniform autoscale, an hour is billed according to the highest throughput reached in that hour, with a minimum of one tenth of Tmax. A short peak can therefore determine that hour's throughput charge.

Trap Using the hourly average consumed RU/s to predict an autoscale invoice, which ignores the hourly peak billing rule.

2 questions test this
Dynamic autoscale scales physical partitions and regions independently

Dynamic autoscale allows each physical partition in each region to scale according to its own usage instead of scaling everything to match the busiest partition and region. This avoids unnecessary scale-ups for nonuniform workloads. Billing aggregates the highest scaled throughput for each partition and region during the hour.

Trap Treating classic autoscale's hottest-partition scaling as independent partition scaling, which overlooks the dynamic-scaling enhancement.

2 questions test this
Dynamic scaling is an account feature that applies only to autoscale resources

Dynamic scaling is enabled by default on accounts created after September 25, 2024, and can be enabled on older accounts. The account-level setting applies to its autoscale containers and shared-throughput databases. It does not convert manual resources to autoscale and does not apply to serverless accounts.

Trap Enabling Dynamic Scaling to make a manually provisioned container autoscale, which leaves its capacity mode unchanged.

2 questions test this
Serverless charges for consumed RUs without a reserved throughput allocation

When traffic is intermittent with low average utilization, evaluate serverless because it bills for consumed RUs rather than a reserved RU/s allocation. You do not provision throughput when creating resources in a serverless account. The database operations remain available, but the capacity and billing behavior differ from provisioned throughput.

Trap Provisioning shared database RU/s in a serverless account, which has no reserved-throughput resource to configure.

2 questions test this
A requirement for multiple Azure regions rules out serverless

Azure Cosmos DB serverless accounts run in a single Azure region and cannot provide provisioned-throughput geo-distribution. If an application requires more than one region, choose a provisioned-throughput account. Low average traffic does not remove that compatibility constraint.

Trap Selecting serverless for a low-traffic application that must use two regions, which violates its single-region restriction.

2 questions test this
The throughput migrate command changes an existing container's provisioned-throughput type

To change an existing NoSQL container from manual throughput to autoscale, use az cosmosdb sql container throughput migrate with --throughput-type autoscale and the resource identifiers. Use --throughput-type manual for the reverse migration. Throughput update changes an allocation within the current mode rather than performing this mode migration.

Trap Running throughput update to switch a manual container to autoscale, which changes throughput values rather than migrating the mode.

3 questions test this
Creating an autoscale resource requires autoscale throughput properties

To create an autoscale database or container in .NET, supply throughputProperties built with ThroughputProperties.CreateAutoscaleThroughput(Tmax). The value specifies the autoscale maximum, whereas an ordinary integer throughput argument provisions manual RU/s. SDK support for creating autoscale resources does not imply support for migrating an existing manual resource to autoscale.

Trap Passing an integer throughput argument and expecting it to mean Tmax, which selects manual throughput instead of an autoscale definition.

2 questions test this
Provisioned throughput and serverless have different latency commitments

When capacity selection requires SLA-backed point-operation latency, evaluate provisioned throughput rather than choosing solely by average traffic or billing. Microsoft's capacity-mode comparison lists less than 10-ms point-read and write latency for provisioned throughput, versus serverless SLO targets of less than 10 ms for point reads and less than 30 ms for writes. SLA conditions still apply; multi-region strong consistency has a separate write-latency expression. A serverless SLO is not the same commitment as the provisioned-throughput SLA.

2 questions test this
Serverless maximum throughput grows with storage-driven physical partition count

A serverless container has a documented maximum capacity of 5,000 RU/s per physical partition. When its data outgrows one physical partition, its maximum container throughput increases with the number of partitions. These values are capacity ceilings rather than guaranteed throughput, so consumed-RU billing does not provide unlimited instantaneous burst capacity.

Trap Applying the provisioned-throughput 10,000-RU/s physical-partition ceiling to serverless sizing, because serverless has a separate per-partition capacity limit.

Dedicated container throughput provides isolation that shared database throughput does not

When a container needs predictable reserved throughput, provision throughput on that container. Database-level throughput is shared by participating containers and guarantees no fixed share to any one of them. Current guidance recommends dedicated container throughput for most workloads, especially when containers have different growth or demand patterns.

Trap Using database-shared throughput to guarantee each tenant container an equal reserved share, which the shared pool does not enforce.

2 questions test this
A container with dedicated throughput does not draw from its database's shared allocation

A database can contain both shared-throughput containers and containers with dedicated throughput. The dedicated container receives its own provisioned allocation, while the database allocation is shared only among the participating shared containers. Include both allocations when estimating the resource's provisioned capacity.

Trap Adding a dedicated container's allocation to the shared pool available to other containers, which double-counts isolated capacity.

2 questions test this
Shared and dedicated throughput cannot be interchanged on the same existing container

A container's choice between database-shared and dedicated throughput is made at creation. Moving between these granularities requires copying data into a container created with the desired setting. This differs from changing manual provisioned throughput to autoscale on an existing resource.

Trap Using a manual-to-autoscale migration to turn a shared container into a dedicated one, which changes the scaling mode rather than the throughput granularity.

2 questions test this
A shared-throughput database normally supports at most 25 shared containers

A shared-throughput database normally allows up to 25 containers to participate in its allocation. Additional containers must be created with dedicated throughput, subject to documented legacy exemptions. Do not assume that adding containers always leaves the database's existing shared-throughput arrangement available.

2 questions test this
A manual container's minimum throughput includes storage and historical provisioning

For a manual-throughput container, estimate the minimum RU/s as the maximum of 400 RU/s, current storage in GB multiplied by 1 RU/s, and the highest RU/s ever provisioned divided by 100. A temporary large scale-up can therefore raise the minimum you can later select. Read the resource's current minimum before planning a scale-down.

Trap Returning a previously large container to 400 RU/s solely because current traffic is low, which ignores storage and historical-throughput minimums.

2 questions test this
Autoscale's minimum configurable Tmax includes storage and its historical maximum

For an autoscale container, the minimum configurable Tmax is the maximum of 1,000 RU/s, current storage in GB multiplied by 10 RU/s, and the highest configured maximum divided by 10, rounded up to the next 1,000 RU/s. This is a lower bound on the selected maximum, not the live one-tenth scaling floor. Storage growth can require Tmax to increase.

Trap Applying the manual container's historical-maximum divisor to autoscale Tmax, which uses a different minimum formula.

2 questions test this
Large throughput increases can complete asynchronously

A provisioned-throughput increase can require background resource provisioning rather than taking effect immediately. While a scaling operation is in progress, another modification can return HTTP 423. In .NET, inspect ThroughputResponse.IsReplacePending to distinguish a pending replacement from an already completed allocation.

Trap Starting a large ingestion immediately after requesting a large RU/s increase, which assumes background scaling has already finished.

2 questions test this
Throughput redistribution reallocates capacity among physical partitions

The preview redistribution feature supports manual and autoscale provisioned resources and can move RU/s from quieter physical partitions to busier ones without necessarily raising total throughput. It does not apply to serverless accounts. Custom partition allocations switch the throughput policy from Equal to Custom, which blocks normal container- or database-level throughput changes until Equal distribution is restored.

Trap Changing overall container throughput while a Custom per-partition policy is active, which is blocked to preserve those custom allocations.

2 questions test this
Shared-database minimum throughput can also depend on container count

For a shared database, the usual storage and historical-provisioning minimums also include a container-count term. For manual throughput, that term is 400 + MAX(container count - 25, 0) times 100 RU/s; for autoscale's minimum Tmax, it is 1,000 + MAX(container count - 25, 0) times 1,000 RU/s. The term matters for legacy databases permitted to exceed the normal shared-container count limit, so a container-only minimum formula is insufficient there.

Trap Applying only the dedicated-container minimum formula to a legacy shared database with many containers, which omits its container-count term.

2 questions test this
The standard per-resource throughput quota can be raised through support

The documented default maximum provisioned throughput is 1,000,000 RU/s per dedicated container or shared-throughput database. A support request can increase that resource quota. This is distinct from a full logical partition's architectural limit, which is not removed by increasing the resource-wide quota.

2 questions test this
Per-partition throughput has separate retrieval and redistribution commands

Use az cosmosdb sql container retrieve-partition-throughput to inspect current physical-partition allocations, selecting --physical-partition-ids or --all-partitions as needed. Use redistribute-partition-throughput with --target-partition-info to request the desired per-partition allocations. These commands require the cosmosdb-preview extension; their documented CLI path has no shared-database equivalent, for which the PowerShell database cmdlets are available.

Trap Using throughput migrate to move RU/s between physical partitions, which changes the resource's provisioned-throughput type rather than its per-partition allocation.

2 questions test this
Equal allocation can throttle a hot physical partition below the resource's total RU budget

The default Equal throughput policy divides provisioned throughput evenly among a resource's physical partitions. A busy partition can exhaust its assigned share and return throttling responses while other partitions still have unused capacity. Evaluate the allocation available to the busy partition rather than treating all resource RU/s as one immediately usable pool.

2 questions test this
ReadThroughputAsync retrieves throughput settings and the current minimum

Use ReadThroughputAsync on the database or container whose throughput is being inspected. In .NET, the overload taking RequestOptions returns a ThroughputResponse with Resource and MinThroughput; the parameterless convenience call returns only a nullable throughput value. Use the richer response when a planned scale-down must respect the resource's current minimum.

Trap Reading ContainerProperties to obtain MinThroughput, which belongs to the throughput response rather than the container definition.

2 questions test this
ReplaceThroughputAsync changes an existing resource's throughput allocation

Use ReplaceThroughputAsync on a database or container to change its provisioned throughput allocation. For an existing autoscale resource, pass ThroughputProperties.CreateAutoscaleThroughput with the new maximum. This updates throughput settings rather than replacing container properties or migrating between manual and autoscale modes.

Trap Using ReplaceContainerAsync to scale RU/s, which changes the container definition rather than its separately managed throughput allocation.

2 questions test this
Redistribution changes total throughput when the target allocations change its sum

A throughput redistribution request in the redistribution preview is not necessarily a capacity-neutral transfer. If the requested physical-partition allocations sum to a different total, the operation updates the resource's total throughput accordingly. Include a larger requested total in capacity and cost planning.

2 questions test this
A redistribution target above 10,000 RU/s triggers a physical-partition split

The redistribution preview accepts a target of up to 20,000 RU/s for a physical partition, but a target above 10,000 RU/s triggers splitting. The original partition first receives up to 10,000 RU/s, and the requested throughput is then divided evenly among the resulting partitions. The larger request does not authorize one physical partition to remain above its 10,000-RU/s ceiling.

2 questions test this
Priority-based execution preferentially throttles low-priority work during contention

When interactive requests and less urgent background work compete for a container's RU/s, enable priority-based execution on the account and assign High or Low priority through SDK request options. In .NET, set ItemRequestOptions.PriorityLevel to PriorityLevel.High or PriorityLevel.Low. The service attempts to throttle low-priority requests first when demand exceeds configured throughput, but this preference is best effort rather than an SLA or a reservation of additional capacity.

Trap Using AllowBulkExecution to protect interactive requests from background ingestion, because bulk grouping optimizes aggregate throughput without assigning service-side request priority.

1 question tests this
Throughput buckets cap a workload's percentage without reserving that share

The throughput-bucket preview limits an assigned workload to a configured maximum percentage of a dedicated container's throughput, while the underlying capacity remains shared. Assign ordinary requests with ItemRequestOptions.ThroughputBucket or set a client-wide bucket with WithThroughputBucket; bulk-enabled clients require client-level assignment rather than a bucket on each operation. Buckets govern workload consumption rather than redistributing RU/s among physical partitions. Shared-throughput database containers and serverless accounts do not support this feature.

Trap Using physical-partition throughput redistribution to impose an application-specific RU ceiling, because redistribution assigns capacity by storage partition rather than by request workload.

New NoSQL containers automatically index their item properties by default

A newly created NoSQL container has an automatic indexing policy that indexes every item's properties and uses range indexes for strings and numbers. This supplies query support without separate index creation for each property. The indexing policy belongs to the container rather than to the account or client.

Trap Creating a separate account-wide index policy for all containers, which mistakes a per-container setting for an account property.

2 questions test this
Consistent indexing updates synchronously while None disables indexing

A container's Consistent indexing mode updates its index synchronously with item writes and deletes. None disables indexing and is appropriate for a pure key-value workload that does not need secondary-index queries. Indexing mode is a container policy, not a choice among the five read-consistency levels.

Trap Selecting None to request eventual read consistency, which disables indexing instead of selecting a read-consistency level.

2 questions test this
A unique-key policy enforces uniqueness within a logical partition

When a tenant's items must not repeat a business value, define a unique-key policy on that value and partition by the tenant identifier. The policy prevents duplicate values within each logical partition, not across all partition-key values. A create or update that violates the constraint is rejected.

Trap Using a unique email policy to enforce account-wide uniqueness across unrelated partition keys, which exceeds the policy's logical-partition scope.

2 questions test this
Paths grouped in one unique key constrain their combined value

A composite unique key groups multiple property paths into one uniqueness constraint. The combined tuple must be unique within a logical partition; each component need not be individually unique. Use separate unique-key constraints only when each value must be independently unique.

Trap Defining separate first-name and last-name constraints to prevent duplicate full names, which unnecessarily requires each name component to be unique.

2 questions test this
Unique-key policies must be defined when the container is created

An existing container's unique-key policy cannot be added or changed in place. To introduce a different policy, create a new container with the required constraints and copy the data. Check for conflicting existing values before performing the copy.

Trap Replacing an existing container's properties to add a new unique-key constraint, which is not a mutable container policy.

2 questions test this
Missing unique-key paths participate as null and path names are case-sensitive

Unique keys are not sparse: a missing constrained path contributes a null value to the uniqueness check. Property paths and JSON string values are case-sensitive, so a mis-cased path can unexpectedly constrain null rather than the intended field. For a single-path constraint, multiple missing values in the same logical partition violate uniqueness.

Trap Using a mis-cased path such as /email for items containing Email, which constrains missing null values instead of the intended property.

2 questions test this
A standard unique-key policy allows up to ten constraints

A standard unique-key policy supports at most 10 unique-key constraints or combinations. Grouping several property paths in one composite constraint consumes one constraint entry. Count policy entries rather than counting every participating property as a separate constraint.

3 questions test this
A standard unique-key policy has a total budget of sixteen path values

The unique-key documentation gives a maximum of 16 path values in a standard unique-key policy. A composite constraint consumes one path value for each participating property, so its paths still count individually toward that budget. Check the total path count separately from the number of constraints.

2 questions test this
Unique-key enforcement slightly increases item mutation RU charges

A container with a unique-key policy has slightly higher RU charges for creating, updating, and deleting items. Include that enforcement overhead when estimating mutation costs. The constraint is not a cost-free metadata declaration.

2 questions test this
A database manages containers while a container is the scaling unit

An Azure Cosmos DB account contains databases, and a database manages one or more containers of items. The container is the unit of horizontal storage and throughput scalability. Multiple item shapes can coexist because containers are schema-agnostic.

2 questions test this
Create-if-not-exists methods support repeatable resource initialization

Use CreateDatabaseIfNotExistsAsync on CosmosClient and CreateContainerIfNotExistsAsync on Database for repeatable initialization. Their create counterparts attempt creation and can fail when the named resource already exists. Perform these metadata operations during setup rather than on every item request.

Trap Calling resource creation during every point read to obtain a container reference, which introduces unnecessary metadata work on the data path.

2 questions test this
Container creation supplies the partition-key path and optional dedicated throughput

In .NET, Database.CreateContainerAsync accepts an id, partitionKeyPath, and optional throughput. ContainerProperties provides the richer definition needed for policies such as unique keys or hierarchical key paths. Setting a dedicated throughput allocation at creation is different from letting the container share a database allocation.

Trap Passing an item's partition-key value where CreateContainerAsync expects the partition-key path, which confuses a definition such as /category with a value such as bikes.

2 questions test this
Resource proliferation can exhaust account metadata limits independently of item throughput

An account has a documented combined limit of 500 databases and containers, and metadata operations use a separate system allocation with a maximum of 240 RU/s. Increasing a container's item throughput does not enlarge that metadata allocation. Cache resource references and avoid unnecessary enumeration or creation calls in request loops.

Trap Raising item RU/s to remove throttling caused by repeated resource metadata calls, which uses a different throughput allocation.

3 questions test this
CreateContainerIfNotExists checks identity rather than reconciling an existing configuration

CreateContainerIfNotExistsAsync checks for an existing container by id. If it exists, the method does not validate that properties such as throughput match the requested configuration. Inspect and manage the existing settings separately rather than using this initializer as a configuration-reconciliation operation.

Trap Calling CreateContainerIfNotExistsAsync with new throughput and assuming it updates an existing container, which checks existence instead of reconciling its properties.

2 questions test this
GetContainer returns a proxy without establishing that the resource exists

CosmosClient.GetContainer(databaseId, containerId) obtains a proxy reference for later operations. It does not guarantee that the remote container exists. Use creation or a service operation when existence must actually be established; repeatedly acquiring a proxy is not a database validation request.

Trap Treating a non-null GetContainer result as proof that the remote container was deployed, which returns a proxy even without that guarantee.

2 questions test this
Database and container deletion use resource-management methods rather than item deletion

In .NET, call Database.DeleteAsync to delete a database and Container.DeleteContainerAsync to delete a container. DeleteItemAsync instead removes one addressed item while retaining its container. Choose the resource-level operation only when removing the resource itself is the intended management action.

Trap Deleting individual items to remove a container resource, which leaves the container and its configuration in place.

2 questions test this
The free-tier discount must be selected at account creation

Azure Cosmos DB free tier provides a lifetime discount for the first 1,000 RU/s and 25 GB of storage on one opted-in account per subscription. Opt in when creating the account rather than planning to enable it later on an existing account. Work beyond the allowance is not automatically free.

Trap Creating a standard account first and planning to attach free tier after loading data, which misses the account-creation opt-in boundary.

2 questions test this
Reuse one SDK client per account for the application's lifetime

Use a singleton CosmosClient per Azure Cosmos DB account for the lifetime of the application. Its connections and routing caches are reused across databases and containers in that account. Separate tenant databases or partition keys in the same account do not require separate client instances; separate accounts do.

Trap Creating a new CosmosClient for every tenant partition in one account, which duplicates connection pools and routing caches without an account boundary.

2 questions test this
Direct mode reduces hops while Gateway uses a single HTTPS endpoint

When the environment supports the required connections and low latency is important, use Direct mode in the .NET or Java SDK. Direct connects to backend replicas over TLS-encrypted TCP, while Gateway routes requests through an HTTPS frontend. Gateway is appropriate for strict outbound-port restrictions or limited socket budgets and is the mode used by Python and the other non-.NET/non-Java SDKs.

Trap Selecting Direct mode in the Python SDK to bypass the gateway, which that SDK does not support.

2 questions test this
Direct-mode clients still use HTTPS to obtain routing metadata

Direct mode changes the data-operation route but still uses Gateway HTTPS requests to discover account, container, and replica-routing information. The SDK caches that metadata and reuses the resulting TCP connections. An environment that permits backend TCP but blocks the metadata endpoint cannot fully initialize the client.

Trap Removing HTTPS access after selecting Direct mode, which still needs gateway metadata discovery and refresh.

2 questions test this
ApplicationRegion and ApplicationPreferredRegions guide client routing

ApplicationRegion tells the .NET SDK where the application runs, and ApplicationPreferredRegions supplies an ordered list of preferred account regions. These are alternative client-routing options configured through CosmosClientOptions; set one, not both. They do not create regions in the account or change the account's write-region configuration.

Trap Setting ApplicationRegion to provision a missing account region, which changes client preferences rather than account topology.

2 questions test this
A custom Cosmos serializer controls user payloads rather than SDK-owned resource types

CosmosClientOptions.Serializer customizes serialization and deserialization of user request and response payloads. SDK-owned types such as ContainerProperties and DatabaseProperties continue to use the SDK's default serializer. Keep serialized property names aligned with the stored JSON, especially the lowercase id and partition-key fields.

Trap Expecting a custom user serializer to redefine the serialization of ContainerProperties, which remains SDK-controlled.

2 questions test this
Rate-limited retry count and retry wait time are independent client options

The .NET client's MaxRetryAttemptsOnRateLimitedRequests limits the number of retries after rate limiting. MaxRetryWaitTimeOnRateLimitedRequests limits the time budget spent waiting for such retries. Configure both with the application's tolerance for delayed responses; increasing the retry budget does not add service capacity.

Trap Raising only the request timeout to configure the number of HTTP 429 retries, which is governed by separate retry options.

2 questions test this
Idle TCP timeout and port reuse control sparse Direct-mode connection costs

For sparse Direct-mode workloads with many clients, IdleTcpConnectionTimeout can close unused TCP connections and PortReuseMode.PrivatePortPool can reduce ephemeral-port demand. Connections otherwise remain open for reuse by default. The idle timeout must be at least 10 minutes; avoid very short values because frequent reconnection adds overhead.

Trap Constructing a new client after each operation to release idle ports, which discards all routing and connection reuse instead of tuning connection lifetime.

2 questions test this
RequestTimeout alone is not an end-to-end operation deadline

The .NET client's RequestTimeout governs waiting for a network response, not the full operation across all internal work and retries. Use a CancellationToken as well when an end-to-end deadline is required. Keep timeout and retry settings consistent with the application's allowed operation duration.

Trap Treating RequestTimeout as a strict cap on the full operation including every retry, which only bounds a narrower network wait.

2 questions test this
The .NET SDK should be used asynchronously throughout the call chain

Use async and await for Azure Cosmos DB .NET operations rather than blocking on Task.Result or Task.Wait. Blocking asynchronous network calls can starve the thread pool and degrade concurrent request handling. An asynchronous SDK call provides little benefit if its caller immediately blocks waiting for it.

Trap Wrapping every asynchronous SDK call in Task.Wait to simplify request handling, which can exhaust request-processing threads.

2 questions test this
Direct mode through public or service endpoints needs TCP ports 10000 through 20000

A Direct-mode client using public or service endpoints must reach backend TCP ports 10000 through 20000 in addition to Gateway HTTPS access on port 443. Select Gateway mode when the environment permits only the HTTPS route. Merely selecting Direct in client options cannot establish connections that the environment blocks.

2 questions test this
Direct-mode connection demand grows with partitions and active concurrency

A Direct-mode client establishes connections to replica endpoints on demand as it accesses physical partitions. More partitions increase the endpoints it may need, and higher concurrent request volume can require additional connections to the same endpoint. Estimate socket demand from both the accessed partition set and active concurrency.

Direct TCP concurrency depends on both requests per connection and connections per endpoint

MaxRequestsPerTcpConnection controls how many requests can share one Direct TCP connection, while MaxTcpConnectionsPerEndpoint caps connections to each backend endpoint. Together they bound the requests that can be sent simultaneously to that endpoint. Configure this active concurrency budget separately from idle-connection lifetime or client-port reuse.

Trap Increasing IdleTcpConnectionTimeout to raise active request capacity, which retains idle connections longer rather than changing request multiplexing or the endpoint connection cap.

GatewayModeMaxConnectionLimit controls the SDK-managed Gateway connection pool

For the SDK-managed HTTP handler, GatewayModeMaxConnectionLimit sets the maximum concurrent connections to the target endpoint in Gateway mode and defaults to 50. With a custom HttpClientFactory, configure the supplied handler's MaxConnectionsPerServer instead. Direct TCP connection settings do not configure this HTTP pool.

Trap Increasing MaxTcpConnectionsPerEndpoint to expand a Gateway HTTP pool, which configures Direct backend TCP connections rather than Gateway connections.

HttpClientFactory supplies the HttpClient used for SDK HTTPS communication

CosmosClientOptions.HttpClientFactory accepts a delegate that supplies an HttpClient for HTTPS communication. This covers Gateway operations and Direct-mode metadata requests, making it useful when an application manages shared HTTP clients. It does not replace the Direct TCP data transport.

Built-in serialization options can remove the need for a custom CosmosSerializer

Use CosmosClientOptions.SerializerOptions for supported built-in serialization settings, such as ignoring null values, without implementing a custom serializer. To select System.Text.Json for user payloads, set UseSystemTextJsonSerializerWithOptions with JsonSerializerOptions. Reserve a custom CosmosSerializer for behavior these built-in options do not supply.

System.Text.Json payload serialization does not remove the Newtonsoft.Json dependency

The Azure Cosmos DB .NET v3 SDK still uses Newtonsoft.Json internally for system types when user payloads use System.Text.Json. Microsoft's setup guidance therefore requires an explicit Newtonsoft.Json dependency and recommends version 13.0.3 or higher. Keep that dependency when switching the application's payload serializer.

A finite HTTP pooled-connection lifetime lets a reused client react to DNS changes

When configuring the HTTP transport for a long-lived CosmosClient, set SocketsHttpHandler.PooledConnectionLifetime so pooled HTTPS connections are periodically replaced. An open pooled connection does not react to a DNS change; creating replacement connections allows the transport to resolve the endpoint again. Supply the handler through HttpClientFactory while retaining singleton client reuse, and balance connection churn against the required DNS responsiveness.

Trap Tuning IdleTcpConnectionTimeout to refresh the HTTPS connection pool, because that option controls idle Direct-mode TCP connections rather than the HTTP handler's pooled lifetime.

Also tested in

References

  1. https://learn.microsoft.com/en-us/azure/cosmos-db/set-throughput
  2. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclient
  3. https://learn.microsoft.com/en-us/azure/cosmos-db/concepts-limits
  4. https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/dp-420
  5. https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels
  6. https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning-overview
  7. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-consistency
  8. https://learn.microsoft.com/en-us/azure/cosmos-db/request-units
  9. https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/best-practice-dotnet
  10. https://learn.microsoft.com/en-us/azure/cosmos-db/find-request-unit-charge
  11. https://learn.microsoft.com/en-us/azure/cosmos-db/serverless
  12. https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/conceptual-resilient-sdk-applications
  13. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions
  14. https://learn.microsoft.com/en-us/azure/cosmos-db/throughput-serverless
  15. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-change-capacity-mode
  16. https://learn.microsoft.com/en-us/azure/cosmos-db/provision-throughput-autoscale
  17. https://learn.microsoft.com/en-us/azure/architecture/patterns/deployment-stamp
  18. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.container
  19. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-provision-autoscale-throughput
  20. https://learn.microsoft.com/en-us/cli/azure/cosmosdb/sql/container/throughput
  21. https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/distribute-throughput-across-partitions
  22. https://learn.microsoft.com/en-us/azure/cosmos-db/priority-based-execution
  23. https://learn.microsoft.com/en-us/azure/cosmos-db/throughput-buckets
  24. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-database-account
  25. https://learn.microsoft.com/en-us/azure/cosmos-db/free-tier
  26. https://learn.microsoft.com/en-us/azure/cosmos-db/index-policy
  27. https://learn.microsoft.com/en-us/azure/cosmos-db/index-overview
  28. https://learn.microsoft.com/en-us/azure/cosmos-db/unique-keys
  29. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.database
  30. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclient.getcontainer
  31. https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/sdk-connection-modes
  32. https://learn.microsoft.com/en-us/azure/cosmos-db/dedicated-gateway