Azure Cosmos DB APIs

Why multiple APIs

When you create a Cosmos DB account, you choose the API. That choice determines how the application interacts: what format it sends, what query language it uses, and which client libraries it works with. Internally, Cosmos DB stores data in its own format; the API is an abstraction layer on top.

The five supported APIs are NoSQL, MongoDB, Table, Apache Cassandra, and Apache Gremlin. Azure Cosmos DB for PostgreSQL is a separate offering on a retirement path, not recommended for new projects.

API for NoSQL

It's Cosmos DB's native API. It stores data as JSON documents and lets you query it with SQL-like syntax. It was previously called the SQL API: if older documentation says "SQL API", it's the same service.

SELECT *
FROM customers c
WHERE c.id = "joe@litware.com"

-- Result: a JSON document
{
  "id": "joe@litware.com",
  "name": "Joe Jones",
  "address": { "street": "1 Main St.", "city": "Seattle" }
}

• Microsoft recommends it for high-scale scenarios that need a 99.999% SLA, instant autoscale, and automatic failover across regions.
• It supports Fabric mirroring: it replicates operational data into Microsoft Fabric with no ETL pipeline, to analyze it in near real time without consuming RUs or affecting the transactional workload.

API for MongoDB

Compatible with MongoDB drivers and client libraries, so existing applications connect without significant changes. Data is stored in BSON (binary JSON) and queried with MQL (MongoDB Query Language), an object-oriented syntax where you call methods on collections.

db.products.find({id: 123})

-- Result
{ "id": 123, "name": "Hammer", "price": 2.99 }

API for Table

It stores key-value pairs in tables with the same programming model as Azure Table Storage. A Table Storage app connects with minimal changes and gains scalability, global distribution, and automatic indexing on every property.

Each row is identified by PartitionKey + RowKey and retrieved through a REST-style endpoint, for example Customers(PartitionKey='1',RowKey='124').

API for Apache Cassandra

Compatible with Apache Cassandra, an open-source database with a column-family storage model: rows don't have to contain the same columns, unlike a relational table.

SELECT * FROM Employees WHERE ID = 2

It uses CQL (Cassandra Query Language), with SQL-like syntax. It fits when migrating a Cassandra workload to a managed cloud database.

API for Apache Gremlin

Designed for graph data: entities are vertices (nodes) and relationships are edges. Useful when the connections matter as much as the data: social networks, recommendation engines, fraud detection, and organizational hierarchies.

g.addV('employee').property('id', '3').property('firstName', 'Alice')
g.V('3').addE('reports to').to(g.V('1'))

g.V().hasLabel('employee').order().by('id')

Gremlin is the language for traversing and manipulating the graph: the example adds an employee, connects her to her manager, and then lists employees in order.

How to choose the API

Exam scenarios

Common exam traps