Cosmos DB APIs and Consistency Levels

Azure Cosmos DB is unique among databases in offering multiple wire-protocol-compatible APIs and five tuneable consistency levels. This lesson explores each API, when to use it, and how consistency levels let you make precise trade-offs between performance, availability, and data freshness.

---

Cosmos DB APIs

When you create a Cosmos DB account, you choose an API. This choice is permanent — it cannot be changed after account creation.

NoSQL API (Native)

The NoSQL API (formerly called the SQL API or Core API) is Cosmos DB's native API. It stores data as JSON documents and uses a SQL-like query language:

SELECT c.name, c.email
FROM customers c
WHERE c.city = 'London'
ORDER BY c.name

Feature	Detail
Data format	JSON documents
Query language	SQL-like syntax with extensions
SDK support	.NET, Java, Python, Node.js, Go
Best for	New applications, general purpose
Unique features	Change feed, stored procedures, UDFs, triggers

The NoSQL API offers the broadest feature set and is the recommended choice for new applications.

MongoDB API

Wire-protocol compatible with MongoDB, allowing existing MongoDB applications and tools to connect to Cosmos DB without code changes:

db.customers.find({ city: "London" }).sort({ name: 1 })

Feature	Detail
Data format	BSON documents
Compatibility	MongoDB 4.2, 5.0, 6.0, 7.0
Tools	mongosh, MongoDB Compass, Mongoose
Best for	Migrating existing MongoDB workloads
Benefit	No code changes for MongoDB applications

PostgreSQL API

Based on the Citus distributed database engine, this API brings PostgreSQL compatibility to Cosmos DB:

Feature	Detail
Data format	Relational tables (distributed)
Query language	PostgreSQL SQL
Distribution	Shards tables across nodes using a distribution column
Best for	Distributed PostgreSQL workloads, multi-tenant applications
Extensions	PostGIS, pg_cron, and many PostgreSQL extensions

Cassandra API

Wire-protocol compatible with Apache Cassandra (CQL v4):

SELECT name, email FROM customers WHERE city = 'London';

Feature	Detail
Data format	Wide-column (keyspaces, tables, rows)
Query language	CQL (Cassandra Query Language)
Tools	cqlsh, DataStax drivers
Best for	Migrating Apache Cassandra workloads

Gremlin API

For graph data — modelling entities as vertices and relationships as edges:

g.V().hasLabel('customer').has('city', 'London').out('ordered').values('product')

Feature	Detail
Data format	Graph (vertices and edges)
Query language	Apache TinkerPop Gremlin traversal language
Best for	Relationship-heavy data: social networks, fraud detection, recommendation engines
Benefit	Graph traversals with Cosmos DB's global distribution and low latency

Table API

Wire-protocol compatible with Azure Table Storage, but with Cosmos DB's premium features:

Feature	Detail
Data format	Key-value (PartitionKey + RowKey)
Query language	OData filter expressions
Best for	Migrating from Azure Table Storage with better performance and global distribution
Benefit	Drop-in replacement with turnkey global distribution and single-digit ms latency

---

Choosing an API

Scenario	Recommended API
New application, no existing database	NoSQL (broadest features, best SDK support)
Existing MongoDB application	MongoDB
Distributed PostgreSQL / multi-tenant SaaS	PostgreSQL
Existing Apache Cassandra workload	Cassandra
Graph data (social networks, fraud detection)	Gremlin
Migrating from Azure Table Storage	Table

---

Consistency Levels