Start with the one-sentence idea, then build up the picture slowly.

Azure Cosmos DB is a fully managed database service from Microsoft, built to store and retrieve data very quickly at almost any size, and to spread that data across the world. A database is an organised store of information that programs can add to, search, change, and delete. The word managed means Microsoft runs the machines, the software, the copies, and the repairs, while you simply create the database and use it.

Cosmos DB belongs to a family called NoSQL databases. The name is often explained as “not only SQL”. SQL is the traditional language for talking to relational databases, which store information in tables with rows and columns, like a spreadsheet. NoSQL databases store data in other shapes. In Cosmos DB’s main form, data is stored as documents, which are small bundles of information written in a format called JSON. JSON is a simple text style that groups named pieces of data together, for example a customer’s name, city, and list of orders, all in one neat package.

What makes Cosmos DB special is not only the document idea. It is designed from the start to be globally distributed, which means your data can live in many Azure regions at once, so users in Mumbai, London, and Sydney all talk to a nearby copy. It is also built to scale horizontally, which means it grows by spreading data over more and more machines instead of making one machine bigger. And it publishes clear promises about speed, availability, and data freshness.

It is also helpful to say what Cosmos DB is not. It is not a replacement for every database. It is not the best choice for heavy reporting across many tables, or for programs that rely on complicated relationships between dozens of tables. It shines when an application needs fast reads and writes for many users, flexible data shapes, and a worldwide reach.

To see why Cosmos DB exists, look at what came before it.

For many years the standard way to store application data was a relational database running on one powerful server. It worked wonderfully for a long time. The server held all the tables, the program asked it questions in SQL, and answers came back fast. Relational databases also give strong guarantees about correctness, such as making sure that moving money from one account to another either fully happens or does not happen at all.

When one server is not enough

Trouble begins when an application becomes popular. A single server has limits on how much data it can store and how many requests it can handle each second. The usual first answer is to buy a bigger server, which is called scaling up. This works for a while, but bigger servers get very expensive, and eventually there is no bigger server to buy. The next answer is to split the data across several servers, which is called sharding. Sharding a traditional database by hand is hard work. Programmers must decide which data goes where, keep the pieces balanced, and rewrite queries that now touch several servers.

When users are everywhere

There is a second problem, which is distance. Information travels through cables at a speed limited by physics, so a user in Australia talking to a database in Europe waits a noticeable fraction of a second for every request. Copying a traditional database to other continents, and keeping all the copies in step, is complicated and error-prone. Many companies tried and found the work expensive and fragile.

When data does not fit the table

Modern applications also deal with data that does not fit neatly into fixed columns: product catalogues where each product has different attributes, game profiles that change shape with every update, readings from thousands of devices. Changing a table’s structure on a huge live database is slow and risky. Document databases let each item carry its own shape, so the program can evolve without a painful redesign.

Every service exists because somebody had a painful problem. Here are the main ones.

Traffic that arrives in waves

Many applications have unpredictable traffic. A ticket-selling site is quiet for weeks and then receives a flood of visitors when a popular concert goes on sale. With a fixed server you must buy for the peak and waste money the rest of the time. Cosmos DB lets you raise and lower the throughput you pay for, and it even offers an automatic mode that adjusts within a range you choose.

Many different kinds of clients

Some teams already have programs written for other popular databases. Cosmos DB offers several APIs, meaning interfaces that programs use to talk to it, so that some existing programs can connect with few changes. We look at these in the next chapter.

Seven building blocks. Learn these and the rest of the topic becomes easy to follow.

Account, database, container, item

Cosmos DB organises data in four levels. The account is the top-level resource, tied to your Azure subscription, where you choose settings such as the API and the regions. Inside an account you create one or more databases, which are named groups. Inside a database you create containers, which hold the actual data and carry the throughput and partitioning settings. Inside a container live items, which are the individual documents. In the main API the container is the unit that is scaled, so most design decisions are made at the container level.

The APIs

An API is a way for programs to talk to a service. Cosmos DB offers several. The NoSQL API is the native one, using JSON documents and a query language that looks like SQL. Other APIs let programs written for other well-known databases connect, including ones compatible with MongoDB, Apache Cassandra, Apache Gremlin for graph data, and a table-style API. Microsoft also offers a PostgreSQL flavour under the Cosmos DB name. The set of options and their feature coverage change over time, so check the current documentation before choosing. Importantly, you choose the API when you create the account, and it is not easily changed afterwards.

Request Units

Cosmos DB measures work in a currency called the Request Unit, or RU. Instead of asking how many processors or how much memory you want, you think in RUs per second, written RU/s. Every operation has a cost in RUs. A simple read of a small item costs very little, while a complicated search across much data costs more. We cover this in detail in Chapter 10.

Partition key

Each item has a partition key, which is a property of the item, such as a customer identifier, that decides which group the item belongs to. Items with the same key value live together. This single choice is the most important design decision in Cosmos DB, and we give it a whole chapter.

Consistency level

Consistency describes how up to date the data is that you read, when several copies exist. Cosmos DB offers five levels, from very strict to very relaxed, so you can trade freshness against speed and cost. Chapter 8 explains them.

Regions and replication

A region is a geographic location with Azure data centres. Replication means keeping copies of data in several places. In Cosmos DB you simply add regions to your account, and the service copies the data and keeps the copies in step.

How the pieces fit together, from your application down to the stored copies.

Look at the diagram below from top to bottom. Your application uses a software kit called an SDK, which is a ready-made library that makes talking to the service easy. The SDK sends requests to the Cosmos DB account. Inside the service the data of each container is divided into partitions, and each partition is stored in several copies on different machines. If the account has several regions, each region holds its own full set of copies.

flowchart TD
    APP["Your application with SDK"] --> ACC["Cosmos DB Account"]
    ACC --> DB["Database"]
    DB --> C1["Container - orders"]
    DB --> C2["Container - customers"]
    C1 --> P1["Partition 1"]
    C1 --> P2["Partition 2"]
    C1 --> P3["Partition 3"]
    P1 --> R1["Replica A"]
    P1 --> R2["Replica B"]
    P1 --> R3["Replica C"]

What Microsoft manages and what you manage

Microsoft manages the data centres, the machines, the storage, the copies, the automatic movement of partitions when they grow, the patching, and the failover when something breaks. You manage the account settings, the choice of API and regions, the design of your containers and partition keys, the throughput you provision, the indexing policy, who can access the data, and how your application uses the SDK. This is the shared responsibility model, and it leans heavily toward Microsoft compared with running your own database servers.

The gateway and direct modes

SDKs can talk to Cosmos DB in different ways. In one style, requests go through a front door called the gateway. In another, the SDK connects straight to the machines that hold the data, which usually gives lower delay. The SDK also keeps a small map of where data lives, so it can send each request to the right place without asking every time. You usually let the SDK handle these choices.

Automatic indexing

An index is a helper structure that lets a database find items quickly without reading everything, like the index at the back of a book. Cosmos DB, by default, builds an index over every property of every item automatically. This is a big convenience, since queries are fast without extra work, but it also uses storage and adds a little cost to every write. You can tune the indexing policy to include only what you need.

The machinery that makes growth feel effortless.

When you create a container, Cosmos DB does not store everything on one machine. It splits the data into pieces using the partition key. All items that share a partition key value belong to the same logical partition. A logical partition is a group of items, and it is the unit within which certain operations, such as transactions, are guaranteed. Many logical partitions are then stored together on physical partitions, which are the actual units of storage and processing on real machines.

The hash idea

To decide where an item goes, Cosmos DB runs the partition key value through a mathematical function called a hash, which turns any value into a number in a predictable way. Items with different key values land at seemingly random positions, which spreads them evenly over the physical partitions. Because the function is the same every time, a later request knows exactly where to look.

Splits and growth

As a container receives more data or more throughput, physical partitions fill up. When that happens, the service automatically splits a physical partition into two and moves the data, all while the database stays online. This is why you never have to plan a manual resharding project. There are limits on the size of a logical partition, and on the throughput and storage of a physical partition, so a good partition key that spreads data widely matters. Check the current documentation for the exact numbers.

Replicas and agreement

Each physical partition is stored as several replicas, which are identical copies on different machines, spread over different failure zones where available. One replica acts as the leader for writes. A write is considered successful only after a majority of replicas have stored it. If the leader fails, the remaining replicas choose a new leader within seconds. This approach follows the same idea as many other reliable distributed systems: a group of machines vote, and the majority decides.

flowchart TD
    W["Write request"] --> L["Leader replica"]
    L --> F1["Follower replica 1"]
    L --> F2["Follower replica 2"]
    F1 --> A{"Majority stored it?"}
    F2 --> A
    A -->|"Yes"| OK["Success returned to client"]
    A -->|"No"| RT["Wait or retry"]

Why spreading matters

Total throughput is divided among physical partitions. If your data is spread evenly, every partition does an equal share and all the throughput you pay for is useful. If one partition receives most of the traffic, it hits its limit while the others sit idle, and you start seeing refusals even though your overall usage is low. This situation is called a hot partition, and it is the most common cause of trouble in real systems.

The life of a request, and the life of a Cosmos DB project.

The life of one request

When your program reads an item, the SDK looks at the item’s partition key and works out which partition holds it. It sends the request to a replica in the nearest region. The replica checks your identity, finds the item using its index, reads it, and measures how many RUs the operation used. The answer returns to your program along with the RU charge, which you can log to learn what your operations cost. A read that names both the partition key and the item identifier is called a point read, and it is the cheapest and fastest operation available.

flowchart LR
    A["Plan data model"] --> B["Create account and choose API"]
    B --> C["Create database and containers"]
    C --> D["Choose partition key and throughput"]
    D --> E["Load data and connect application"]
    E --> F["Operate and monitor"]
    F --> G{"Traffic or needs changed?"}
    G -->|"Yes"| H["Adjust throughput, indexing, or regions"]
    H --> F
    G -->|"No"| F

The change feed

Cosmos DB keeps a running record of every change made to a container, called the change feed. It is a list, in order, of items that were created or updated. Other programs can read it to react to changes: sending a notification when an order is placed, updating a search index, or copying data to another system. This turns the database into a source of events without extra machinery.

Expiry of old data

Many kinds of data are only useful for a limited time, such as login sessions or sensor readings. Cosmos DB offers time to live, often written TTL, which automatically deletes items after a set number of seconds. This keeps storage small, cost low, and removes the need for clean-up programs.

The trade-off every distributed database must make, with a dial you can turn.

When data is kept in several places, a change made in one place takes a little time to arrive in the others. During that short time, two people reading from two copies might see slightly different answers. Consistency is the promise a database makes about how different those answers may be. A strict promise gives fresher data but costs speed and sometimes availability. A relaxed promise is faster and cheaper but allows older data to be seen for a moment.

The five levels

Why session is popular

Think of a user who posts a comment and then reloads the page. Nothing is more confusing than the comment vanishing. Session consistency promises that the same user, using the same session, always sees their own change. Other users may see it a moment later, which is usually fine. This gives most of the speed of relaxed levels with the behaviour people naturally expect, which is why it is the default for new accounts.

Choosing a level

Ask what harm a stale read would do. For a bank balance shown before a transfer, strict freshness may matter. For the number of likes on a post, a few seconds of lag is harmless. For a product catalogue, eventual consistency is often fine. You set a default for the account and, in many cases, can relax it, but not tighten it, for individual requests. Start with the default, and move toward the stricter or looser ends only when a specific need appears.

Disks break, buildings lose power, and whole regions occasionally go dark. Good design expects that.

Availability means the database is reachable when you need it. Durability means the data is not lost. Cosmos DB gets both from the copies described in Chapter 6, and then adds more by spreading across zones and regions.

Availability zones

An availability zone is a separate data centre building, or group of buildings, inside one region, with its own power, cooling, and network. Where supported, Cosmos DB can place replicas in different zones, so that the loss of one zone does not interrupt service. This protects against local disasters without any code on your side.

Multiple regions

To go further, you add more regions to your account. With single-region writes, one region accepts writes, and the others hold read copies that your application can use for fast local reads. If the write region is lost, another region can be promoted. With multi-region writes, every region accepts writes, which gives low write delay for users everywhere, but requires you to think about conflicts, which arise when two regions change the same item at the same moment. Cosmos DB provides rules for resolving conflicts, such as the latest write winning.

flowchart TD
    U1["Users in Asia"] --> R1["Region: India - read and write"]
    U2["Users in Europe"] --> R2["Region: Europe - read copy"]
    U3["Users in America"] --> R3["Region: America - read copy"]
    R1 -.->|"Replication"| R2
    R1 -.->|"Replication"| R3
    R2 -.->|"Failover if India is lost"| R1

Service promises

Microsoft publishes service level agreements, or SLAs, which are written promises about availability. The promise is stronger when the account uses multiple regions. Because these numbers and conditions can change, read the current Cosmos DB SLA page rather than relying on a figure from an article.

Failover

Failover means switching to a healthy copy when the usual one fails. Cosmos DB can be set to fail over automatically, following a priority order of regions you choose. You should also practise failover on purpose, using a manual test, so that you know your application reconnects properly and that nobody is surprised during a real event.

Backup and restore

Copies protect against hardware problems, but not against human mistakes. If someone deletes a container, every copy is deleted. For that reason Cosmos DB provides backups. In the default style, backups are taken periodically, and restoring from them is done by asking Microsoft support, within the retention period. In the continuous style, changes are tracked continuously, and you can restore an account to a chosen moment in time yourself, within a retention window. Continuous backup offers finer recovery but has a different cost. Check the current options and their conditions before choosing.

Understanding the currency is the key to a healthy bill.

A Request Unit is a blended measure of the processing, memory, and input and output a request needs. Instead of guessing at machines, you reason about RUs. Reading a small item by its key is the cheapest operation, and it is commonly cited as costing about one RU for a one-kilobyte item. Writes cost more than reads, because they must update the item, its index, and its copies. Searches that look across many items, or across several partitions, cost more again, and the cost rises with the amount of data examined.

Capacity modes

What makes up the bill

The main charges are for throughput, which is the RU/s you provision or consume, and for storage, which is the data and index space you use. If you replicate to several regions, throughput and storage are charged for each region, so adding regions multiplies the cost. Backups, especially continuous ones, and some optional features also carry charges. Use the Azure pricing calculator and your real numbers, because prices differ by region.

Refusals and retries

If your requests need more RUs than you have provisioned in a given second, Cosmos DB refuses the extra requests with a message commonly called 429, meaning “too many requests”, along with a hint about how long to wait. This is not a failure of the database; it is a polite request to slow down. The SDKs automatically retry such requests for a while. Seeing a few is normal. Seeing many means you should raise throughput, reduce the cost of your operations, or fix an uneven partition key.

Ways to save

• Use point reads wherever possible, since they are the cheapest way to fetch an item.
• Tune the index. Exclude properties you never search, so writes cost fewer RUs.
• Keep items small. Reading and writing big items costs more.
• Use autoscale or serverless for uneven traffic instead of paying for a constant peak.
• Use reserved capacity. A reservation is a promise to use a certain amount for one or three years in return for a lower price, suited to steady workloads.
• Expire old data with time to live, so storage does not grow forever.
• Watch for a free tier. Microsoft has offered a limited free allowance for new accounts, so check whether it is currently available and what the limits are.

The two design decisions that decide whether your database is a joy or a headache.

Model for your questions

In a relational database, you usually design the tables first and think about questions later, because joins can answer almost anything. In a document database, you do the opposite. You list the questions your application will ask, and design the documents so that each common question can be answered by reading as few documents as possible. This habit is called query-driven design.

Embedding and referencing

Embedding means placing related information inside the same document. A customer document might include the customer’s addresses, and an order document might include its line items. Reading the order then needs only one read. Referencing means storing just an identifier that points to another document. This keeps documents small and avoids copies, but needs extra reads to follow the pointer. A good rule is to embed data that is read together and changes together, and to reference data that is large, changes often, or is shared widely.

What a good partition key looks like

A good partition key has three qualities. It has high cardinality, meaning it takes many different values, so the data spreads widely. It spreads the traffic evenly, so no value receives most of the requests. And it appears in the queries you run most often, so most operations touch a single partition.

Tricks when no single field works

Sometimes no natural field is ideal. One approach is a synthetic key, made by combining fields, such as a customer identifier together with a month, to spread a very busy customer across several partitions. Another is a hierarchical partition key, a newer feature that lets you use up to a few levels of keys, which helps with large tenants and avoids hitting the size limit of one logical partition. Check the current documentation for details and limits.

Cross-partition queries

A query that does not include the partition key must ask every partition. This is called a cross-partition query. It works, and for rare queries it is fine, but if your main screens depend on it, cost and delay will grow with the container. If an important question cannot be answered inside one partition, consider keeping a second copy of the data in another container, organised with a different key, and keep both in step using the change feed.

Transactions

Cosmos DB supports transactions, which are groups of changes that all succeed or all fail, but only within a single logical partition. This is another reason to put items that must change together under the same partition key.

Who may enter, from where, and how data is protected.

Security for a database has four questions. Who may connect, which is identity. From where they may connect, which is networking. How the data travels, which is encryption in transit. And how it is stored, which is encryption at rest.

Identity and access

The simplest way to connect is with an account key, a long secret that gives broad power over the account. It is like a master key to the building, so it should be guarded and, where possible, avoided. A better approach is role-based access control, usually shortened to RBAC, in which programs and people sign in with Microsoft Entra ID, Microsoft’s identity service, and receive only the permissions their role allows. For programs running inside Azure, a managed identity lets the application sign in without any stored secret. Many organisations switch off key-based access entirely once their applications use identities.

Network protection

By default an account can be reached over the public internet, protected by authentication. For tighter control, use the account firewall to allow only certain addresses, or use a private endpoint, which gives the account a private address inside your own virtual network so traffic never crosses the public internet.

Encryption

Data is encrypted while stored, using keys managed by Microsoft by default, and you may choose to bring your own keys, held in a key vault, if your rules demand it. Connections to the service are encrypted in transit.

Security checklist

• Prefer identities over account keys, and use managed identities for applications in Azure.
• Use least privilege. Give each program only the data permissions it needs, and keep management rights separate from data rights.
• Restrict the network with private endpoints or firewall rules.
• Protect keys. If keys are used, store them in a key vault and rotate them on a schedule.
• Turn on backup with a point-in-time option, and protect the account from accidental deletion with resource locks.
• Enable threat detection so unusual access patterns raise alerts.
• Log access to a central workspace so you can answer who read or changed what.
• Never put secrets in documents. Treat stored data as visible to anyone with read access.

You cannot manage what you cannot see. Here is what to watch.

Monitoring means continuously checking the health and behaviour of your system. Metrics are numbers measured over time, such as requests per minute. Logs are written records of events, such as a failed request. Azure Monitor collects both for Cosmos DB, and you can set alerts, which are automatic messages triggered when a number crosses a line you choose.

Hot partition detection

The overall RU use of a container may look comfortable while one partition is overloaded. This is why the normalised measure, which reports the most heavily used partition, is so valuable. If one partition runs at its limit while the rest are quiet, your partition key is not spreading the load, and adding more throughput will not fix the root problem.

Measure the cost of your own operations

Each response from the service reports the RU charge of the request. Record these figures in your application logs, at least for your most common operations. When someone changes a query or adds an index, the numbers show whether the change helped or hurt. This simple habit prevents most nasty bill surprises.

Azure offers several databases because data comes in different shapes. Compare before you choose.

The managed offerings in this list change over time, so confirm current capabilities and limits in the documentation before you design around any of them.

A simple decision guide

flowchart TD
    Q1{"Data has many related tables and complex joins?"} -->|"Yes"| SQL["Consider a relational database"]
    Q1 -->|"No"| Q2{"Need very high scale and low delay for many users?"}
    Q2 -->|"Yes"| Q3{"Users in several parts of the world?"}
    Q3 -->|"Yes"| COS["Choose Cosmos DB with multiple regions"]
    Q3 -->|"No"| COS2["Cosmos DB in one region may still fit"]
    Q2 -->|"No"| Q4{"Just cheap simple tables or a cache?"}
    Q4 -->|"Yes"| SIM["Consider Table Storage or Redis"]
    Q4 -->|"No"| SQL

Using several databases together

Real systems often combine databases. An online shop might keep its product catalogue and shopping carts in Cosmos DB for speed and scale, its financial records in a relational database for strict reporting, its product images in blob storage, and a cache in front for the hottest pages. Matching each kind of data with the right store is a mark of good architecture, not of indecision.

Every design choice gives something and takes something. Be honest about both sides.

The central trade-off

The big trade-off is flexibility and scale versus relational convenience. Relational databases give you powerful joins and a lifetime of tooling, and let you ask almost any question later. Cosmos DB gives you effortless scale and speed, in return for planning your questions in advance. A good architect chooses by asking which pain is greater for the project in hand.

Consistency versus speed

Stricter consistency means fresher data but more waiting. Relaxed consistency means speed but a small risk of reading older data. There is no best answer for every program. The right level depends on what a stale read would cost the business.

Global reach versus cost

Every extra region improves speed for nearby users and resilience for everyone, but adds to the bill. Teams should add regions where real users live, and not simply everywhere because the option exists.

Proven shapes to copy, and common shapes to avoid.

Patterns that work

Anti-patterns

An anti-pattern is a common solution that looks sensible but causes trouble. Here are the usual ones.

A practical list you can print and keep next to your desk.

Best practices

• Start from the questions. Write down the top queries before choosing the model or partition key.
• Choose the partition key carefully. Test it with realistic data and traffic before you commit.
• Prefer point reads. Keep the item identifier and partition key handy so lookups are direct.
• Keep items small and bounded. Avoid documents that grow without limit.
• Tune the index. Include only the paths you search, and measure the effect on RU cost.
• Use one SDK client per application. Reuse it rather than creating a new one for every request, since it holds connections and a location map.
• Handle refusals gracefully. Rely on the SDK’s retry behaviour, and add your own back-off for bulk jobs.
• Pick the consistency level on purpose. Start with the default and change it only with a clear reason.
• Add regions where users are. Test failover regularly, before it matters.
• Use identities, not keys, and restrict the network.
• Enable backup with point-in-time recovery and test a restore.
• Monitor the busiest partition, log RU charges, and alert on refusals and cost.

Common mistakes

Four typical situations, described as illustrative examples, showing when the service fits.

The stories below are illustrative composites of the kinds of situations where teams commonly use Cosmos DB. They are not claims about any particular company, but they reflect the reasoning real architects use.

Short answers to the questions beginners ask most often.

Everything important, in one place.

Azure Cosmos DB is a fully managed, globally distributed NoSQL database made for speed and scale. Data lives in documents inside containers, is split into partitions by a partition key, is stored in several replicas, and can be copied to many regions. You pay in Request Units for the work your operations need, and you choose a consistency level that balances freshness against speed. Microsoft runs the machines. You supply the design.

Remember the comparison we began with: a notebook that exists in every city at once. It is a wonderful tool, but a good chain still decides how the pages are labelled, who may write in them, how many copies to keep, and how to find an old entry when a customer asks. Treat Cosmos DB in the same way: plan the questions, choose the labels with care, and watch the numbers, and it will serve your application quietly at any size.