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.
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.
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.
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_COMMITTEDperforms 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_STRONGprovides 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:
- Regions first. A serverless account can run only in a single Azure region, and regions can't be added to it after creation[11] while it stays serverless. Any requirement for a second region, for availability or for local reads, means provisioned throughput, however low the traffic.
- Latency commitment second. Provisioned throughput offers under 10-ms point reads and writes covered by an SLA[14]; serverless offers under 10 ms for point reads and under 30 ms for writes as an SLO (service-level objective), and serverless containers offer no assurance of predictable throughput or latency[11]. A contractual latency requirement therefore points to provisioned throughput, whatever the billing comparison says.
- Traffic shape last. Serverless fits intermittent, hard-to-forecast traffic with long idle periods and a low (under 10 percent) average-to-peak ratio; autoscale fits variable or unpredictable traffic that still needs an SLA; manual throughput fits sustained, predictable traffic.
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.
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.
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
| Criterion | Provisioned: standard (manual) | Provisioned: autoscale | Serverless |
|---|---|---|---|
| Best suited for | Sustained, predictable traffic | Variable or unpredictable traffic | Intermittent traffic with a low average-to-peak ratio |
| What you configure | A fixed RU/s, in increments of 100 | A maximum RU/s (Tmax), in increments of 1,000 | Nothing: resources take no throughput setting |
| Throughput available | The provisioned RU/s | Scales between 0.1 x Tmax and Tmax | Up to 5,000 RU/s per physical partition |
| Billing | Provisioned RU/s per hour | Highest RU/s reached in the hour, at least 0.1 x Tmax | RUs consumed |
| Azure regions | Any number | Any number | One region only |
| Latency commitment | Under 10 ms point reads and writes (subject to SLA conditions); multi-region strong writes: 2 x farthest-region RTT + 10 ms at the 99th percentile | Under 10 ms point reads and writes (subject to SLA conditions); multi-region strong writes: 2 x farthest-region RTT + 10 ms at the 99th percentile | Under 10 ms point reads, under 30 ms writes (SLO) |
| Shared database throughput | Yes, up to 25 containers | Yes, up to 25 containers | Not available |
Decision tree
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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Strong consistency and has regions in East US and West Europe. A pricing service in East US updates an item named P1. While that
- You are designing four Azure Cosmos DB for NoSQL workloads for a regional bank. Each workload gets its own account with one write region and two read regions, and each account uses the weakest consist
- You have an Azure Cosmos DB for NoSQL account named account1 that has a single write region in East US and read regions in West Europe and Japan East. Stock-reservation services in all three regions r
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with one write region and two read regions. The default consistency level is Bounded staleness, configured with 200,000 versions and 600 se
- You are designing an Azure Cosmos DB for NoSQL account for a price-quote service with a write region in West Europe and read regions in North Europe and UK South. Read regions can lag behind writes, b
- You have an Azure Cosmos DB for NoSQL account named account1 with a write region in East US and a read region in West Europe. The default consistency level is Bounded staleness with 100,000 versions a
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with a single write region in East US and read regions in Canada Central and Brazil South. The default consistency level is Bounded stalene
- You manage an Azure Cosmos DB for NoSQL account named account1 that currently has one region, West US 3. Its default consistency level is Bounded staleness with the smallest bounds allowed for a singl
- Your company has two Azure Cosmos DB for NoSQL accounts that use Bounded staleness. The dev account has one region, West US. The prod account has a write region in West US and a read region in East US
- 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.
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Eventual consistency. A status dashboard polls an item named job42 every second. Occasionally a poll shows an older status than t
- You have a mobile app that uses an Azure Cosmos DB for NoSQL account named account1 with Eventual consistency. Each app instance uses one CosmosClient. Users report that a refreshed order status somet
- 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
- You have a read-heavy catalog API that uses an Azure Cosmos DB for NoSQL account with Bounded staleness. The API needs no staleness bound across regions, but each client session must read its own writ
- You have an IoT ingestion service that only inserts items into an Azure Cosmos DB for NoSQL account named account1 and never reads them back. account1 uses Session consistency. A team member proposes
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Session consistency. A container has 20,000 RU/s that are used only for point reads of 1-KB items, and the workload currently rea
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Strong consistency, with a write region in East US and read regions in West Europe and Australia East. Users only need to read th
- You are designing an Azure Cosmos DB for NoSQL account for a payment ledger. Every read in every region must return the latest committed balance. The 99th-percentile write-latency budget is 50 ms. The
- 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.
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. An administrator changes its default consistency level from Session to Bounded staleness in the Azure portal. A long-running .NET worker s
- You have an Azure Cosmos DB for NoSQL account named account1 with a database named db1. Reads from the orders container must always return the latest committed version, while reads from the logs conta
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 whose default consistency level is Strong. A .NET application creates its CosmosClient with CosmosClientOptions.ConsistencyLevel set to Eve
- You have an Azure Cosmos DB for NoSQL account named account1 whose default consistency level is Eventual. A .NET application in Gateway mode reads payment items, and a developer adds the following cod
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Strong consistency and has regions in East US and West US. To reduce latency, a developer sets CosmosClientOptions.ConsistencyLev
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Session consistency. Two microservices share a user's session by passing session tokens through a message queue. To shorten messa
- You have an Azure Cosmos DB for NoSQL account named account1 that uses Session consistency. An audit tool saved the session token returned when version 1 of an item named inv-7 was written. Versions 2
- 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
- You have an ASP.NET Core API that writes cart items by using the Azure Cosmos DB for NoSQL .NET SDK v3 and Session consistency. A separate instance of the API, which has its own CosmosClient, reads th
- You have a web application that runs on four virtual machines behind Azure Load Balancer, which distributes requests round-robin without session affinity. Each virtual machine has its own CosmosClient
- 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
- Your Java application uses Azure Cosmos DB Java SDK 4.70 in Direct mode with an account that has one write region, two read regions, and Session as its default consistency level. A reporting service i
- You have a Java application that uses Azure Cosmos DB Java SDK 4.70 in Direct mode against an account with a write region in East US and a read region in West US. The default consistency level is Sess
- 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.
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL container in which each customer item is 300 KB because it embeds the customer's documents. A dashboard performs thousands of point reads per minute by id and par
- You have an Azure Cosmos DB for NoSQL container that stores 100-KB product items. An application updates a 50-byte stockLevel property on each item by reading the item, changing the property, and call
- 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
- You are planning the throughput for a new Azure Cosmos DB for NoSQL workload. The workload includes point reads, inserts of 5-KB items, two queries with different filters, and a stored procedure. The
- You have an Azure Cosmos DB for NoSQL container. A reporting query is run once with MaxItemCount set to 100 and returns 10 pages. It's run again against the same unchanged data with MaxItemCount set t
- 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
- You have a .NET service that uses the Azure Cosmos DB .NET SDK v3 with its default client options. During a traffic spike, the container exceeds its provisioned RU/s and the service returns HTTP 429 r
- You have a .NET batch job that writes to an Azure Cosmos DB for NoSQL container by using the .NET SDK v3 with its default retry settings. During peaks, some writes still fail with a CosmosException wh
- 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.
- 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
- You are developing a new application on an Azure Cosmos DB for NoSQL container, and its throughput requirement is still unknown. You plan to use autoscale throughput and monitor usage before you adjus
- You have an Azure Cosmos DB for NoSQL container named events that uses autoscale throughput with a maximum throughput (Tmax) of 20,000 RU/s. The container stores 50 GB of data. Overnight, the applicat
- 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
- You have an Azure Cosmos DB for NoSQL container in a single-region account that uses autoscale with a maximum throughput of 10,000 RU/s. Dynamic scaling isn't enabled. During one hour, the system stay
- You have an Azure Cosmos DB for NoSQL container that uses autoscale with a maximum throughput of 20,000 RU/s. The finance team wants to see, for each hour of last month, the RU/s that the container wa
- 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
- Your Azure Cosmos DB for NoSQL account was created in 2025 and has one write region and one read region. A container uses autoscale with a maximum of 10,000 RU/s across four physical partitions, and t
- You have an Azure Cosmos DB for NoSQL container with autoscale Tmax of 2,000 RU/s, two physical partitions, and a write region and a read region, so each partition can scale up to 1,000 RU/s in each r
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that was created in 2023. Its containers use autoscale, but monitoring shows that every partition scales to match the hottest partition. Th
- You have an Azure Cosmos DB for NoSQL account created in 2023. It contains container c1 with autoscale throughput, database db2 with autoscale shared throughput used by three containers, and container
- 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
- You have an Azure Cosmos DB for NoSQL serverless account named account1. A deployment script that uses the .NET SDK calls CreateContainerAsync("orders", "/customerId", 400) to create a container for a
- You are designing a back end for an internal approval API that uses Azure Cosmos DB for NoSQL. The API runs in one Azure region on Azure Functions, is used for a few minutes several times a day, and h
- 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
- You have an Azure Cosmos DB for NoSQL serverless account named account1 in West Europe that stores order data for a regional retail application. A new disaster-recovery policy requires a replica of th
- You are designing an Azure Cosmos DB for NoSQL account for a low-traffic booking application that averages 50 RU/s with occasional bursts. A compliance rule requires that the data be replicated to two
- 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
- You have an Azure Cosmos DB for NoSQL container named legacy that uses manual throughput. A developer plans to switch legacy to autoscale from a .NET deployment routine by calling ReplaceThroughputAsy
- You have an Azure Cosmos DB for NoSQL container named container2 in database db1 that uses 4,000 RU/s of manual throughput. You need to change container2 to autoscale by using the Azure CLI. You plan
- You have an Azure Cosmos DB for NoSQL container named container3 that uses manual throughput. You need to switch container3 to autoscale and then set its maximum throughput to 10,000 RU/s by using two
- 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
- You are writing a .NET deployment routine that uses the Azure Cosmos DB .NET SDK v3 to create a container that must use autoscale throughput with a maximum of 4,000 RU/s. The routine calls the followi
- You have an Azure Cosmos DB for NoSQL container named legacy that uses manual throughput. A developer plans to switch legacy to autoscale from a .NET deployment routine by calling ReplaceThroughputAsy
- 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
- Your team plans to move a single-region Azure Cosmos DB for NoSQL workload from provisioned throughput to a serverless account to cut costs. The workload is mostly point reads and point writes. An int
- You are designing an Azure Cosmos DB for NoSQL account for a payment authorization service in one Azure region. Traffic is low and intermittent, but the contract requires that point writes complete in
- 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.
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
- You are reviewing four planned Azure Cosmos DB for NoSQL workloads. Current guidance recommends container-level throughput for most workloads, and you will approve database-level shared throughput onl
- You have an Azure Cosmos DB for NoSQL database named tenants that has 4,000 RU/s of shared manual throughput and 10 containers, one for each enterprise customer. A new contract requires that every cus
- 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
- You have an Azure Cosmos DB for NoSQL database named sales that has 4,000 RU/s of shared manual throughput used by five containers. A sixth container named orders was created in sales with 2,000 RU/s
- Six containers in the crm database of an Azure Cosmos DB for NoSQL account draw on the database's 5,000 RU/s of shared manual throughput. The exports container in crm was provisioned with its own 3,00
- 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
- You have an Azure Cosmos DB for NoSQL database named db1 with 4,000 RU/s of shared throughput. A container named reports in db1 uses the shared throughput and now needs its own dedicated 2,000 RU/s. T
- You are designing an Azure Cosmos DB for NoSQL database named Z that has shared throughput for several small containers. You plan to add a container named B, and its owner expects B to need guaranteed
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 database named media in an Azure Cosmos DB for NoSQL account uses shared manual throughput, and all 25 of its containers draw on that allocation. The account isn't covered by the legacy exemption th
- Your team is designing a new Azure Cosmos DB for NoSQL database for a partner portal. The design calls for 32 small partner containers, and the team wants as many of them as possible to draw on one sh
- 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
- You manage four Azure Cosmos DB for NoSQL containers that use dedicated manual throughput. Container A stores 350 GB, and its highest throughput ever was 30,000 RU/s. B stores 60 GB and once had 70,00
- A cost script estimates the lowest manual throughput allowed for each Azure Cosmos DB for NoSQL container by using MAX(400, storage in GB x 1, current RU/s / 100). For a container named claims that st
- 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
- You have an Azure Cosmos DB for NoSQL container named archive that uses autoscale throughput. Its maximum throughput was once set to 100,000 RU/s, and it now stores 10 GB of data. A script calculates
- You have an Azure Cosmos DB for NoSQL container named logs that uses autoscale throughput. The highest maximum throughput ever configured was 20,000 RU/s, and the container now stores 300 GB of data.
- 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
- You have an Azure Cosmos DB for NoSQL container named ingest that has 10,000 RU/s. Next Monday, a one-time data load will require 500,000 RU/s. You plan to scale the container by using the .NET SDK fr
- You have an Azure Cosmos DB for NoSQL container named ingest. A script raised its throughput from 10,000 RU/s to 400,000 RU/s. Minutes later, a second script calls ReplaceThroughputAsync to change the
- 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
- You manage four Azure Cosmos DB for NoSQL accounts. Each has a container with a hot physical partition and other partitions with unused throughput. You plan to use the throughput redistribution previe
- You have an Azure Cosmos DB for NoSQL container named orders that has 20,000 RU/s. Last week, you used the redistribution preview to give one hot physical partition more RU/s. Today, a deployment pipe
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
- You have a legacy Azure Cosmos DB for NoSQL shared-throughput database named portal that is exempt from the 25-container limit. portal uses manual throughput, has 34 containers, stores 12 GB, and its
- You have a legacy Azure Cosmos DB for NoSQL shared-throughput database that is exempt from the 25-container limit. The database uses manual throughput, has 30 containers, stores 15 GB of data, and has
- 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
- You have an Azure Cosmos DB for NoSQL container that has 300,000 RU/s. One logical partition key, a celebrity's profile, receives about 15,000 RU/s at peak and is throttled. A team proposes a support
- You are preparing an Azure Cosmos DB for NoSQL container named ticketing for a concert sale. Load tests show that the container needs 1,400,000 RU/s of dedicated provisioned throughput for two hours,
- 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
- You have an Azure Cosmos DB for NoSQL container named container1 with dedicated throughput and the cosmosdb-preview Azure CLI extension installed. Before you redistribute throughput, you want to see t
- You have an Azure Cosmos DB for NoSQL database named shared1 that has shared throughput, with a hot physical partition. You need to read the current RU/s of each physical partition of shared1 before y
- 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
- You have an Azure Cosmos DB for NoSQL container named sessions with 8,000 RU/s of manual throughput spread across four physical partitions. Its throughput has never been redistributed. One physical pa
- You have an Azure Cosmos DB for NoSQL container that receives 429 responses, although its total RU consumption is about 40 percent of the provisioned throughput. You suspect that one physical partitio
- 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
- An inventory script for an Azure Cosmos DB for NoSQL account that uses provisioned throughput runs the following code for every container: int? throughput = await container.ReadThroughputAsync(); For
- You are writing a .NET job for an Azure Cosmos DB for NoSQL container named telemetry that uses manual throughput. Each night, the job lowers the throughput to the lowest value that the container allo
- 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
- You have an Azure Cosmos DB for NoSQL database named products that has 1,000 RU/s of shared manual throughput. Eight containers in products use the shared throughput and have no dedicated throughput.
- You have an Azure Cosmos DB for NoSQL container named orders that uses autoscale throughput with a maximum of 4,000 RU/s. Before a sales event, a .NET maintenance tool must raise the autoscale maximum
- 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
- You have an Azure Cosmos DB for NoSQL container that has 12,000 RU/s of manual throughput across three physical partitions, with 4,000 RU/s each. Partition 0 is hot. An engineer runs az cosmosdb sql c
- You have an Azure Cosmos DB for NoSQL container named baskets with 12,000 RU/s of manual throughput across three physical partitions, P0, P1, and P2, each with 4,000 RU/s. P0 is hot and needs 6,000 RU
- 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
- You manage an Azure Cosmos DB for NoSQL container named clickstream with physical partitions that each have 4,000 RU/s. Partition 0 is hot, and its traffic is spread across many logical partition keys
- You have an Azure Cosmos DB for NoSQL container named leaderboard. One physical partition is hot, and diagnostic logs show that a single logical partition key, the current season's global ranking, con
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL database named db1 that contains a container named orders, which is queried on many properties, and a container named audit, which is only written to and read by
- You are creating a container named catalog in an Azure Cosmos DB for NoSQL database. Queries will filter on brand, price, and color, and the product team will add new properties to items over time. Qu
- 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
- You have an Azure Cosmos DB for NoSQL container named container1 whose indexing mode is Consistent. The account uses Session consistency. To reduce RU charges, a developer proposes setting container1'
- You plan to create an Azure Cosmos DB for NoSQL container named sessions that will be used purely as a key-value store. The application performs only point reads and upserts by id and partition key an
- 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
- You have an Azure Cosmos DB for NoSQL container named accounts that uses /tenantId as the partition key and a unique key on /email. A new requirement states that an email address must be unique across
- You are designing a multitenant application that stores user profiles in an Azure Cosmos DB for NoSQL container named users. Every query filters on the tenant ID and must be served from a single logic
- 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
- You plan to create a container named contacts in an Azure Cosmos DB for NoSQL account. The partition key is /companyId. Within a company, two contacts can share a first name or a last name, but the sa
- You have an Azure Cosmos DB for NoSQL container named contacts that uses /companyId as the partition key. The requirement is that no company stores two contacts with the same full name. A teammate pro
- 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
- You have an Azure Cosmos DB for NoSQL container named customers that has 2 TB of data and no unique key policy. A new requirement states that customer numbers must be unique within each partition key
- You have an Azure Cosmos DB for NoSQL container named orders1 that has no unique key policy. You created a container named orders2 with a unique key on /orderNumber and the same partition key. You ver
- 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
- You have an Azure Cosmos DB for NoSQL container named members that has a unique key on /email. Items store the address in a property named Email. The first insert in a logical partition succeeds, but
- You have an Azure Cosmos DB for NoSQL container named customers with /storeId as the partition key and a unique key policy on /phone. In store S7, an existing customer item has no phone property. An a
- 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
- You plan to create an Azure Cosmos DB for NoSQL container that has the following unique key policy: - one composite key on /firstName, /lastName, and /email - one composite key on /badgeId and /siteId
- You plan to create an Azure Cosmos DB for NoSQL container whose unique key policy already includes two composite keys that each group five property paths. You want to add as many additional single-pat
- You are designing an Azure Cosmos DB for NoSQL container for a government registry. Twelve different identifier properties must each be independently unique within a logical partition, so they can't b
- 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
- You plan to create an Azure Cosmos DB for NoSQL container named people for an HR application. To prevent duplicate records, the proposed unique key policy defines five composite unique keys. Each comp
- You plan to create an Azure Cosmos DB for NoSQL container whose unique key policy already includes two composite keys that each group five property paths. You want to add as many additional single-pat
- 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
- You have an Azure Cosmos DB for NoSQL container named catalog that receives 50,000 point reads and 200 item updates per hour. You plan to recreate catalog with a unique key on /sku and copy the data.
- You are estimating the throughput for an Azure Cosmos DB for NoSQL container named registrations. Load testing measured the RU charge of creates, updates, and deletes on a test container that had no u
- 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
- You plan to store orders and customer profiles for an online store in an Azure Cosmos DB for NoSQL account. Orders and profiles have different properties, and every item includes a type property that
- You are designing an Azure Cosmos DB for NoSQL solution for an IoT telemetry platform. The telemetry data will grow from 50 GB to 40 TB, and the ingestion rate is expected to increase tenfold. You mus
- 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
- You have a .NET application that uses the Azure Cosmos DB .NET SDK v3. At startup it calls CreateDatabaseAsync to create a database named db1. The first deployment succeeds, but every later restart fa
- You have an ASP.NET Core API that uses the Azure Cosmos DB .NET SDK v3. For every point read, the API calls CreateContainerIfNotExistsAsync to get a Container object and then calls ReadItemAsync. Unde
- 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
- You are writing a .NET method that creates a container named products in a database by using the Azure Cosmos DB .NET SDK v3. Items include a category property whose values include bikes and helmets,
- You are writing a .NET deployment script that uses the Azure Cosmos DB .NET SDK v3 to create a container named tenants. The container must use a hierarchical partition key on /tenantId and /userId, an
- 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
- You are designing a SaaS application on an Azure Cosmos DB for NoSQL account. The plan is to create one database for each of 300 customers and two containers in each database, for a total of 600 conta
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET API lists all containers in database db1 at the start of every request to find the container it needs. During peak hours, the API r
- You have an ASP.NET Core API that uses the Azure Cosmos DB .NET SDK v3. For every point read, the API calls CreateContainerIfNotExistsAsync to get a Container object and then calls ReadItemAsync. Unde
- 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
- You have an Azure Cosmos DB for NoSQL container named orders that has 400 RU/s of manual throughput. A deployment pipeline runs the following .NET code to raise the throughput to 4,000 RU/s: await dat
- You have a .NET setup routine that calls CreateContainerIfNotExistsAsync for a container named carts and then must log whether the container was created during this run or already existed. The routine
- 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
- You have a .NET monitoring job that uses the Azure Cosmos DB .NET SDK v3. The job must report whether a container named audit exists in database db1. It must not create the container if it's missing,
- You have a .NET health check that uses the Azure Cosmos DB .NET SDK v3. The check calls client.GetContainer("db1", "orders") and reports healthy when the returned object isn't null. After an operator
- 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
- You have an Azure Cosmos DB for NoSQL database named db1 that contains containers named orders, customers, and temp. The temp container is no longer needed, and its throughput and configuration must b
- You have an Azure Cosmos DB for NoSQL container named staging that has 1,000 RU/s of dedicated throughput. To decommission it, a script iterated through all items and called DeleteItemAsync for each o
- 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
- Your team created an Azure Cosmos DB for NoSQL account named account1 with standard pricing and loaded 5 GB of test data. No other account in the subscription uses free tier. The team now wants the fr
- You have an Azure Cosmos DB for NoSQL account named account1 that was created with free tier in a single region. account1 has container A with 600 RU/s and container B with 700 RU/s of dedicated manua
- 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
- You have a B2B application that gives each of 40 customers a dedicated Azure Cosmos DB for NoSQL account so that each customer can have its own regions and keys. One instance of the application serves
- You have a multitenant .NET API that stores each of 40 tenants in its own database, with one container per database, in a single Azure Cosmos DB for NoSQL account. The API creates a CosmosClient for e
- 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
- You have a .NET service on Azure virtual machines that uses the Azure Cosmos DB .NET SDK v3. The virtual machines have no outbound port restrictions, and the service must minimize the latency of point
- You have a Python application that uses the Azure Cosmos DB Python SDK and runs on a virtual machine with all outbound ports open. A developer proposes switching the client to Direct mode to remove th
- 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
- You have a .NET application that uses Direct mode against an Azure Cosmos DB for NoSQL account. During a network review, an architect asks which requests the client still sends through the gateway ove
- You have a .NET service that uses Direct mode against an Azure Cosmos DB for NoSQL account through its public endpoint. The service has been running for a day and has cached its container and routing
- 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
- You have an Azure Cosmos DB for NoSQL account with regions in West US, East US, and West Europe. A .NET application runs in East US 2, but for compliance reasons its reads must prefer West Europe firs
- You have an Azure Cosmos DB for NoSQL account named account1 with regions in West US and East US. A .NET application deployed in Japan East sets CosmosClientOptions.ApplicationRegion to Regions.JapanE
- 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
- You have a .NET application that uses the Azure Cosmos DB .NET SDK v3 with a custom CosmosSerializer set in CosmosClientOptions.Serializer. The serializer converts every property name to PascalCase. A
- You have a .NET application that uses the Azure Cosmos DB .NET SDK v3. You set CosmosClientOptions.Serializer to a custom CosmosSerializer that renames properties and omits null values. The applicatio
- 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
- You have a .NET bulk import job that uses the Azure Cosmos DB .NET SDK v3. Logs show that throttled requests fail after the SDK has made its maximum number of rate-limited retries, while the cumulativ
- You have a .NET service that uses the Azure Cosmos DB .NET SDK v3 with default client options. During peaks, the service receives 429 responses whose retry-after values are about 8 seconds. Logs show
- 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
- You have hundreds of .NET worker instances that each use the Azure Cosmos DB .NET SDK v3 in Direct mode and send a few requests every hour. The hosts are running out of ephemeral ports. A developer pr
- You have a .NET application that uses Direct mode for sparse traffic and sets PortReuseMode to PrivatePortPool. You plan to set CosmosClientOptions.IdleTcpConnectionTimeout so that unused connections
- 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
- You have a .NET API that reads items by calling ReadItemAsync on an Azure Cosmos DB for NoSQL container. A single read can include several network requests because of retries. The team wants an approx
- You have a .NET application that sets CosmosClientOptions.RequestTimeout to 5 seconds. During a regional network issue, some ReadItemAsync calls take more than 15 seconds before they return, and the l
- 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
- You have an ASP.NET Core API whose repository methods await the Azure Cosmos DB .NET SDK, but the controller actions call repository.GetOrderAsync(id).Result. Under load, requests queue and latency cl
- You have a .NET worker that calls the Azure Cosmos DB .NET SDK by using .Result on each ReadItemAsync call, and the worker suffers thread pool starvation under load. In a code review, a developer prop
- 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
- You have a .NET service that will use Direct mode against an Azure Cosmos DB for NoSQL account through its public endpoint. The network team needs the complete list of outbound ports to allow from the
- You have a .NET service that runs in a network that allows only outbound HTTPS traffic on port 443 to Azure. The service uses the Azure Cosmos DB .NET SDK v3 against an account's public endpoint, and
- 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
- https://learn.microsoft.com/en-us/azure/cosmos-db/set-throughput
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclient
- https://learn.microsoft.com/en-us/azure/cosmos-db/concepts-limits
- https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/dp-420
- https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels
- https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning-overview
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-consistency
- https://learn.microsoft.com/en-us/azure/cosmos-db/request-units
- https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/best-practice-dotnet
- https://learn.microsoft.com/en-us/azure/cosmos-db/find-request-unit-charge
- https://learn.microsoft.com/en-us/azure/cosmos-db/serverless
- https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/conceptual-resilient-sdk-applications
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions
- https://learn.microsoft.com/en-us/azure/cosmos-db/throughput-serverless
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-change-capacity-mode
- https://learn.microsoft.com/en-us/azure/cosmos-db/provision-throughput-autoscale
- https://learn.microsoft.com/en-us/azure/architecture/patterns/deployment-stamp
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.container
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-provision-autoscale-throughput
- https://learn.microsoft.com/en-us/cli/azure/cosmosdb/sql/container/throughput
- https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/distribute-throughput-across-partitions
- https://learn.microsoft.com/en-us/azure/cosmos-db/priority-based-execution
- https://learn.microsoft.com/en-us/azure/cosmos-db/throughput-buckets
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-database-account
- https://learn.microsoft.com/en-us/azure/cosmos-db/free-tier
- https://learn.microsoft.com/en-us/azure/cosmos-db/index-policy
- https://learn.microsoft.com/en-us/azure/cosmos-db/index-overview
- https://learn.microsoft.com/en-us/azure/cosmos-db/unique-keys
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.database
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.cosmosclient.getcontainer
- https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/sdk-connection-modes
- https://learn.microsoft.com/en-us/azure/cosmos-db/dedicated-gateway