Azure Cosmos DB Tutorial: Learn Multi-Model Database from Scratch (2026)
I have built globally distributed applications on Azure Cosmos DB, and its turnkey global distribution is unique. Cosmos DB is a multi-model NoSQL database with guaranteed single-digit-millisecond latencies.
We will cover the resource model, consistency levels, global distribution, querying with SQL API, and indexing policies.
Resource Model: Databases, Containers, and Items
A database account contains databases, each with containers, each with JSON items. Throughput provisioned in RUs at the container level.
Partition key is the most important design decision. High cardinality and even distribution. Common choices: user_id, device_id, synthetic key.
az cosmosdb create --name mycosmosdb --resource-group myapp-rg --kind GlobalDocumentDB --default-consistency-level Session
const { CosmosClient } = require('@azure/cosmos');
const client = new CosmosClient({ endpoint, key });
const { container } = await client.database('mydb').containers.createIfNotExists({ id: 'users', partitionKey: '/user_id' });Consistency Levels: From Strong to Eventual
Five levels: Strong, Bounded Staleness, Session, Consistent Prefix, Eventual. Session is the default.
Strong is expensive (quorum reads). Strong not available for multi-region writes. Choose the weakest that meets your correctness requirements.
const client = new CosmosClient({ endpoint, key, consistencyLevel: 'Session' });
const { resource: item } = await container.item(id, partitionKey).read({ consistencyLevel: 'Strong' });
az cosmosdb show --name mycosmosdb --resource-group myapp-rg --query 'consistencyPolicy'Global Distribution with Multi-Region Writes
Only database service supporting multi-region writes without application changes. Conflict resolution via LWW or custom policy.
Add/remove regions with zero downtime. Automatic failover with priority ordering for disaster recovery.
az cosmosdb update --name mycosmosdb --resource-group myapp-rg --enable-multiple-write-locations true
az cosmosdb update --name mycosmosdb --resource-group myapp-rg --locations regionName=eastus failoverPriority=0 regionName=westus failoverPriority=1Querying with SQL API
SQL-like queries against JSON documents: SELECT, JOIN, WHERE, ORDER BY, GROUP BY. JOIN unrolls arrays within items.
Queries on partition key are most efficient. Cross-partition queries fan out to all partitions, consuming more RUs.
SELECT * FROM users WHERE user_id = 'alice@example.com'
SELECT u.name, o.order_id, o.total FROM users u JOIN o IN u.orders WHERE u.user_id = 'alice@example.com'
SELECT VALUE COUNT(1) FROM users WHERE role = 'admin'Indexing Policies and Optimization
By default, every property is indexed. Customize indexing policy to exclude never-queried paths, reducing RU cost and storage.
Composite indexes improve queries with multiple filters or ORDER BY multiple columns. Spatial indexes enable geo queries.
indexingPolicy: { automatic: true, indexingMode: 'consistent', includedPaths: [{ path: '/name/?' }], excludedPaths: [{ path: '/raw_data/*' }] }Change Feed and Real-Time Processing
Persistent, ordered log of all changes in a container. Read sequentially for inserts, updates, deletes in real-time.
Foundation for event-driven architectures: sync to cache, index to Search, stream to Synapse. At-least-once delivery with checkpointing.
const processor = container.items.changeFeed('/leaseContainer', (context, changes) => { changes.forEach(change => { console.log('Change:', change.id); }); context.checkpoint(); }, { startFromBeginning: true });
processor.start();Frequently Asked Questions
What is a Request Unit (RU)?
RU is normalized measure of compute, memory, and I/O. A point read (1 KB by ID) costs ~1 RU. A query can cost 10-100+ RUs.
Can Cosmos DB do JOINs?
Supports JOIN for unrolling arrays within a single item. Cross-item JOINs are not supported. Embed related data or use change feed for denormalized views.
What is the maximum item size?
Maximum 2 MB. For larger documents, compress or split across items. Use change feed to maintain a combined view if needed.
How do I monitor and troubleshoot performance?
Use Azure Monitor for metrics (RU consumption, throttled requests). Enable diagnostic logs for query details. Metrics blade shows partition-level hot spots.
Originally published on Ayodhyyya. Last updated June 1, 2026.