A shared throughput database is a Cosmos DB database where containers share one pool of provisioned request units. Instead of assigning each container its own throughput, the database owns the RU/s budget and eligible containers spend from it. This can be a smart fit for many small, predictable containers that rarely peak at the same time. It is a poor fit when containers have strict performance isolation needs, uneven tenants, or unpredictable spikes. The term is really about pooling capacity, not sharing data or permissions.
Cosmos DB shared throughput database, database-level throughput, shared database throughput, database RU/s pool
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-24
Microsoft Learn
An Azure Cosmos DB shared throughput database provisions request units at the database level so multiple containers draw from one RU/s pool. This can reduce cost for many small containers, but busy containers can consume shared capacity and cause throttling for quieter workloads.
Technically, this concept sits in the Cosmos DB control plane and data plane. The database resource has provisioned throughput, either manual or autoscale, and containers inside it can use that shared pool unless configured with dedicated throughput. Operators see it in database throughput settings, container lists, Azure Monitor metrics, and CLI output from Cosmos DB SQL database throughput commands. The account, API, partition keys, regions, consistency level, indexing policy, and workload mix still determine how well the shared pool behaves under pressure.
Why it matters
A shared throughput database matters because it looks like a simple cost optimization but changes capacity isolation. For development, pilots, small tenant collections, or low-volume reference data, sharing RU/s can avoid paying a minimum for every container. In production, the same choice can create noisy-neighbor throttling when one container burns the pool and other containers receive 429 responses. Architects need to decide whether cost pooling is worth the loss of predictable container-level capacity. Good use of this pattern requires monitoring by container, clear promotion rules to dedicated throughput, and honest expectations about which workloads are allowed to compete. early.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
The Cosmos DB database Scale blade shows provisioned throughput on the database resource, while individual containers do not have their own dedicated throughput setting today.
Signal 02
CLI output from database throughput show returns manual RU/s or autoscale max throughput, confirming capacity is pooled above containers in that database during reviews.
Signal 03
Azure Monitor metrics show normalized RU consumption and throttled requests rising for the database while multiple containers report activity during the same time window regularly.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Run multiple low-traffic containers in development, test, or pilot environments without paying a throughput minimum per container.
Pool small tenant containers where tenants have similar low activity and no strict performance-isolation requirement.
Start a new product with database-level autoscale while monitoring containers before splitting busy workloads out.
Detect a noisy container and migrate it to dedicated throughput after repeated 429 or latency incidents.
Consolidate low-write reference, configuration, or lookup containers that update infrequently and tolerate shared capacity.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Language-learning startup pools early curriculum containers
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A language-learning startup stored lessons, quizzes, badges, and localized prompts in separate Cosmos DB containers. Traffic was tiny outside evening study hours, but dedicated throughput for every container was consuming the seed budget.
🎯Business/Technical Objectives
Cut database cost without merging unrelated application data.
Keep enough capacity for evening quiz spikes.
Measure when a container should graduate to dedicated throughput.
Avoid developer time spent tuning a premature production model.
✅Solution Using Shared throughput database
Architects created a Cosmos DB database with autoscale shared throughput and placed low-volume curriculum containers in the shared pool. CLI checks showed database throughput, listed containers, and exported the pool membership before every release. Azure Monitor tracked normalized RU consumption, 429 counts, and per-container request patterns. The quiz-attempt container was given an exit threshold based on sustained RU usage and user-facing latency. When a new placement-test feature created a short spike, operators raised the autoscale ceiling for one week, then reviewed metrics rather than permanently over-scaling the database.
📈Results & Business Impact
Monthly Cosmos DB spend fell 54 percent during the first two product quarters.
Evening quiz latency stayed under 140 milliseconds at the 95th percentile.
One container graduated to dedicated throughput after crossing the agreed threshold.
Engineering avoided about 80 hours of premature capacity modeling work.
💡Key Takeaway for Glossary Readers
A shared throughput database is strongest when it is paired with metrics and explicit rules for when containers leave the pool.
Case study 02
Transit analytics team isolates a noisy vehicle-feed container
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A public transit analytics platform used one Cosmos DB database for vehicle positions, route metadata, and operator alerts. A new partner feed suddenly produced bursts that throttled unrelated route lookups.
🎯Business/Technical Objectives
Identify which container was consuming the shared RU/s pool.
Restore route lookup performance before morning commute.
Decide whether to scale the pool or isolate the noisy workload.
Create a repeatable incident process for future feeds.
✅Solution Using Shared throughput database
Operators used CLI to confirm throughput was configured at the database level, then listed containers and correlated the partner feed deployment with Azure Monitor 429 metrics. Instead of permanently doubling shared RU/s, they moved the vehicle-feed container to dedicated throughput and left quiet route metadata containers in the shared database pool. Query diagnostics also showed one alert query scanning too many partitions, so developers fixed the filter. The runbook was updated with a decision tree: identify noisy container, test query cost, consider temporary scaling, and migrate to dedicated throughput when contention repeats.
📈Results & Business Impact
Route lookup 95th percentile latency dropped from 920 milliseconds to 180 milliseconds.
Morning commute alerts returned to normal before the next service window.
Shared database RU/s was increased temporarily for only 36 hours, avoiding a permanent cost jump.
The next partner onboarding used the new contention checklist and had no throttling incident.
💡Key Takeaway for Glossary Readers
Shared throughput saves money, but noisy containers need isolation before one feed becomes everyone else’s outage.
Case study 03
Museum archive keeps collection containers affordable
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A national museum digitized small collections from departments that worked independently: textiles, maps, recordings, and restoration notes. Each collection needed its own container, but most changed only a few times per week.
🎯Business/Technical Objectives
Keep separate containers for curator ownership and indexing differences.
Avoid paying dedicated throughput minimums for quiet collections.
Support occasional public-release bursts after exhibit announcements.
Give the archive team a clear cost and performance review cadence.
✅Solution Using Shared throughput database
The archive team used a shared throughput Cosmos DB database for low-write collection containers and documented which departments owned each one. Manual throughput was enough most weeks, while a planned autoscale migration was prepared for exhibit launches. CLI reports listed containers, current throughput, and resource IDs for monthly governance reviews. Azure Monitor alerted on 429s and normalized RU consumption, and public-release checklists included temporary throughput increases when marketing expected traffic. The maps collection later moved to dedicated throughput after a viral exhibit caused repeated spikes, while quieter collections stayed pooled.
📈Results & Business Impact
Throughput cost was 47 percent lower than the dedicated-container estimate.
Curators kept separate data ownership without needing separate databases.
Two exhibit launches ran with no sustained 429s after temporary scaling was scheduled.
Monthly reviews identified the maps container for dedicated throughput before the next launch.
💡Key Takeaway for Glossary Readers
A shared throughput database can support many quiet collections when ownership, launch planning, and exit criteria are not left to chance.
Why use Azure CLI for this?
As an Azure engineer, I use Azure CLI for shared throughput databases because capacity decisions need inventory, not guesses. CLI lets me show database throughput, list containers, detect which containers have dedicated throughput, and compare RU/s settings between environments. It is also useful during incidents because I can pull the database throughput state quickly while another operator checks metrics and application errors. Portal views are fine for one database, but scripted checks catch drift across accounts. Before scaling, I want CLI evidence showing whether the bottleneck is the shared pool, a hot partition, indexing work, or an application retry pattern.
CLI use cases
Show database throughput to confirm whether RU/s is provisioned at the database level instead of on each container.
List containers under the database and identify which workloads are competing for the shared capacity pool.
Compare throughput settings across development, test, and production accounts before promoting a workload design.
Increase or decrease database throughput during an approved change and capture before-and-after evidence.
Investigate throttling by correlating shared database throughput with container activity and Azure Monitor metrics.
Before you run CLI
Confirm subscription, resource group, Cosmos DB account, API type, database name, region, and output format before querying throughput.
Check whether the database uses manual or autoscale throughput, because update commands and cost expectations differ.
List containers and owners before scaling so one noisy workload does not quietly shift cost onto every container.
Understand that throughput updates can increase cost immediately and may not fix hot partitions or inefficient queries.
Use read-only commands during incident diagnosis until the owner approves scaling, migration, or dedicated throughput changes.
What output tells you
Throughput show output identifies the database-level RU/s or autoscale maximum that eligible containers share.
Container list output shows which containers belong to the database and may compete for the shared pool.
Dedicated container throughput settings reveal exceptions that are not drawing from the shared database capacity.
Provisioning state and resource IDs confirm whether the command targeted the intended account, database, and subscription.
Metrics combined with CLI output show whether throttling is caused by pool size, hot partitions, or workload spikes.
Mapped Azure CLI commands
Cosmos DB shared database throughput operations
direct
az cosmosdb sql database throughput show --account-name <account-name> --resource-group <resource-group> --name <database-name>
az cosmosdb sql database throughputdiscoverDatabases
az cosmosdb sql container list --account-name <account-name> --resource-group <resource-group> --database-name <database-name> --output table
az cosmosdb sql database throughputoperateDatabases
az monitor metrics list --resource <database-resource-id> --metric TotalRequestUnits,TotalRequests --interval PT5M
az monitor metricsdiscoverDatabases
Architecture context
Architecturally, I use a shared throughput database as a pooling pattern for Cosmos DB, usually near early-stage products, multi-container development databases, small tenant groups, or operational data with low write volume. It should not be the default for every production container. The design decision sits beside partition-key strategy, autoscale versus manual throughput, regional writes, consistency, indexing, and tenant isolation. I like explicit rules: which containers may join the pool, which metrics trigger migration to dedicated throughput, and who approves throughput changes. Without those rules, shared throughput slowly turns into an invisible contention domain that nobody owns until the first throttling incident.
Security
Security impact is indirect because shared throughput does not grant access to data. Containers can still have separate partition keys, application logic, and authorization paths. The risk appears when capacity isolation is mistaken for security isolation. A compromised or buggy client with legitimate access to one container can consume the shared RU/s pool and create denial-of-service pressure for other containers. Security reviews should include keys, managed identities, RBAC, network controls, and private endpoints, but they should also ask whether one workload can starve another. For regulated or tenant-sensitive workloads, dedicated throughput may be part of the isolation story.
Cost
Cost impact is direct and often the main reason this pattern exists. A shared throughput database can reduce spend when many containers are quiet, because the team avoids dedicated minimum throughput on each one. The risk is over-scaling the shared pool to satisfy one busy container, which makes every quiet container appear more expensive than planned. Autoscale changes the shape of the bill but still requires monitoring. FinOps owners should compare database-level throughput with container-level alternatives, include regional replication costs, and review throttling data. The cheapest design is not the one with the lowest RU/s setting; it is the one that avoids waste without causing rework.
Reliability
Reliability impact is direct at the workload level. Cosmos DB remains a resilient service, but the shared RU/s pool becomes a common failure domain for containers inside the database. If one container spikes, runs an expensive query, or receives a retry storm, other containers may be throttled. Reliable designs watch normalized RU consumption, 429 counts, partition hot spots, and per-container traffic. Autoscale can help with bursts, but it does not remove competition. Runbooks should include temporary throughput increases, moving a container to dedicated throughput, reducing query cost, and communicating that database-level capacity is shared by design. before customers notice.
Performance
Performance impact is direct. All eligible containers compete for the same RU/s pool, so latency and throttling can change even when the container workload code has not changed. A large query, hot partition, bulk import, or retry storm in one container can consume capacity that another container expected. Partition-key design still matters because shared throughput cannot fix hot logical partitions. Performance testing should include concurrent container traffic, not just isolated tests. Operators should watch 429 errors, normalized RU consumption, query metrics, and autoscale ceilings. If one workload requires predictable throughput, move it to dedicated container throughput. before users complain.
Operations
Operators manage a shared throughput database by treating the database pool and containers as one operating unit. Routine checks include showing throughput, listing containers, checking which containers use dedicated throughput, reviewing 429 errors, and correlating RU consumption with deployment or traffic changes. During incidents, operators should identify the noisy container before raising throughput, because scaling the pool may hide an application bug. Documentation should list owners for every container in the pool, promotion thresholds, and escalation contacts. Change records should capture before-and-after RU/s, autoscale settings, affected containers, and expected cost impact. Owners should review trends weekly and after major deployments.
Common mistakes
Putting production containers with different tenants or priority levels into one shared throughput database without isolation rules.
Increasing shared RU/s after every incident instead of finding the noisy container or expensive query pattern.
Assuming autoscale removes contention when containers still compete inside the same database-level pool.
Forgetting to document which containers should move to dedicated throughput when traffic or compliance requirements change.
Testing containers one at a time and missing throttling that appears only when several containers run concurrently.