4.2.2. Selecting the Right API (SQL, Mongo, Gremlin, etc.)
💡 First Principle: Cosmos DB is a multi-model database. The API you choose determines the data model and query language. Selecting the correct API depends on whether you're migrating an existing application (match the existing API) or building new (usually Core SQL for flexibility).
API Selection Guide
| Workload / Requirement | Cosmos DB API | Data Model |
|---|---|---|
| New development, general purpose | API for NoSQL | Documents (JSON) |
| Existing MongoDB application | MongoDB API | Documents (BSON) |
| Graph relationships (social networks) | Gremlin API | Nodes and edges |
| Simple key-value storage | Table API | Key-value entities |
| Existing Cassandra application | Cassandra API | Wide-column |
Visual: Cosmos DB API Selection
⚠️ Exam Trap: If a question mentions "nodes and edges" or "relationships between entities" (like friends in a social network), the answer is Gremlin API—not Core SQL.
Throughput Modes and Time to Live
Cosmos DB bills by Request Unit (RU/s), and there are three ways to buy them:
| Mode | How it bills | Best for |
|---|---|---|
| Standard (manual) provisioned | You set an RU/s figure and pay for it continuously | Steady, predictable traffic |
| Autoscale | You set a maximum; Cosmos scales instantly between 10% and 100% of it | Variable or spiky traffic where you cannot predict the peak |
| Serverless | Pay only for the RUs actually consumed — no traffic, no compute charge | Sporadic development, test, or genuinely intermittent workloads |
Time to Live (TTL) is a separate lifecycle feature: set it on a container (or an individual item) and Cosmos DB deletes items automatically once they reach that age. It is the standard way to expire session state, logs, or cached data without writing and operating a clean-up job. TTL is about expiry — it is not a backup setting, a throughput setting, or a consistency setting.
A Note on the API Names
Microsoft renamed this family: what older material calls the Core (SQL) API or SQL API is now Azure Cosmos DB for NoSQL. The rename matters because the old name misled people into thinking it was a relational, SQL-server-like API — it is a JSON document store that happens to offer a SQL-like query language. You may still meet either name in the wild; they are the same thing.
The API Choice Is Permanent
You select the API when the account is created, and it cannot be changed afterwards — moving to a different API means creating a new account and migrating the data. This is why the exam frames API selection as a design decision rather than a setting.
Each API Brings Its Own Query Language
| API | Query language | Comes from |
|---|---|---|
| API for NoSQL | SQL-like syntax over JSON | Cosmos DB's native API |
| MongoDB | MongoDB Query Language (MQL) | Wire-protocol compatible with MongoDB |
| Cassandra | CQL (Cassandra Query Language) | Wire-protocol compatible with Apache Cassandra |
| Gremlin | Gremlin traversals | Apache TinkerPop graph standard |
| Table | OData-style key lookups | Compatible with Azure Table Storage |
⚠️ Exam Trap: "Cosmos DB supports SQL" is only true of the API for NoSQL. Candidates who assume every API accepts SQL get caught by questions that name CQL, MQL or a graph traversal — each of those names points at exactly one API, and that is usually the whole question.
