This chapter covers Azure Cosmos DB's multiple API options: Core (SQL) API, MongoDB API, Cassandra API, and Gremlin (graph) API. Understanding these APIs is critical for the DP-900 exam because Cosmos DB is a major topic, and questions frequently test your ability to select the appropriate API for a given workload. Approximately 10-15% of exam questions touch on Cosmos DB, with API selection being a key differentiator. You will need to know the data models, query languages, and use cases for each API, as well as how Cosmos DB provides a unified backend.
Jump to a section
Imagine a large warehouse (Cosmos DB) that stores items in a standardized internal format: each item has a unique ID, a timestamp, and a flexible JSON-like structure. The warehouse has four different loading docks, each designed for a different type of delivery truck. The first dock (Core SQL) accepts standard pallets with labels in SQL format. The second dock (MongoDB) accepts crates with BSON documents and uses a specific forklift that understands MongoDB queries. The third dock (Cassandra) accepts wide-column containers and uses a partition-key based sorting system. The fourth dock (Gremlin) accepts graph-shaped packages with vertices and edges. When a truck arrives at its dock, the warehouse staff translates the incoming cargo into the internal standardized format, stores it, and updates a master index. When a customer requests data, the staff retrieves the internal item, translates it back into the format expected by the customer's dock, and loads it onto the appropriate outgoing truck. The warehouse itself remains the same; only the docks change. This means a company can start with MongoDB trucks and later switch to SQL pallets without reorganizing the warehouse — the same data is accessible via any dock. However, each dock has its own set of allowed operations and query capabilities, so not every truck can perform every maneuver. For example, the Gremlin dock can traverse relationships but cannot do aggregate SQL queries efficiently. The warehouse manager must choose the right dock for each type of delivery.
What is Azure Cosmos DB and Why Multiple APIs?
Azure Cosmos DB is a fully managed NoSQL database service designed for globally distributed, low-latency, and highly available applications. It is schema-agnostic and supports multiple data models — document, key-value, wide-column, and graph — through its multi-model, multi-API surface. The fundamental idea is that Cosmos DB provides a single underlying storage engine (based on a write-optimized, log-structured index) that can expose different wire protocols and query interfaces. This allows developers to use familiar APIs (like MongoDB or Cassandra) while benefiting from Cosmos DB's global distribution, automatic indexing, and SLAs.
How It Works Internally
Cosmos DB stores data in containers (called collections in MongoDB API, tables in Cassandra API, or graphs in Gremlin API). Each container has a partition key that determines how data is distributed across physical partitions. The database engine automatically indexes every property by default (except for Cassandra API, which uses a different indexing model). When a client sends a request via any API, the request is translated into Cosmos DB's internal query language and executed against the storage engine. The response is then translated back into the API-specific format. For example, a MongoDB find() operation is converted into a SQL-like query, executed, and the results are converted back to BSON.
Core (SQL) API
The Core API is the native API for Cosmos DB. It uses a SQL-like query language that supports JSON documents. It is the most feature-rich API, offering:
Querying with SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY, and subqueries.
Stored procedures, triggers, and user-defined functions (UDFs) written in JavaScript.
Change feed support for event-driven architectures.
Automatic indexing of all properties with configurable indexing policies.
Default indexing mode is consistent, meaning writes are blocked until the index is updated. You can switch to lazy indexing for higher write throughput at the cost of eventual consistency for queries.
MongoDB API
The MongoDB API provides a wire-protocol-compatible interface for MongoDB drivers (version 3.6 and 4.0). It supports:
CRUD operations using standard MongoDB commands (find, insert, update, delete).
Aggregation pipeline (limited compared to native MongoDB).
Indexes (single field, compound, unique, TTL).
MongoDB query operators ($eq, $gt, $in, $regex, etc.).
Important limitations:
No support for mapReduce, $lookup, $graphLookup, or $facet.
No support for MongoDB's change streams (use Cosmos DB change feed instead).
Maximum document size is 2 MB (same as Core API).
Partition key is mandatory and cannot be changed after creation.
Cassandra API
The Cassandra API provides a wire-protocol-compatible interface for Apache Cassandra (version 4.x). It uses the Cassandra Query Language (CQL) and supports:
Table creation with partition key and clustering columns.
CQL statements: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE.
Secondary indexes (limited to equality queries).
Time-to-live (TTL) at row level.
Key differences from Apache Cassandra:
Cosmos DB automatically manages replication and distribution; you do not configure replication factor or consistency levels per keyspace.
Consistency levels are mapped to Cosmos DB's consistency levels (e.g., Cassandra's QUORUM maps to Cosmos DB's Strong or Bounded Staleness depending on configuration).
No support for materialized views, lightweight transactions (LWT), or Cassandra's native change data capture.
Gremlin (Graph) API
The Gremlin API provides a graph data model and uses the Apache TinkerPop Gremlin traversal language. It supports:
Vertices and edges with properties.
Gremlin steps: V(), E(), addV(), addE(), out(), in(), both(), has(), values(), project(), etc.
Graph queries for relationship traversal (e.g., friends of friends).
Limitations:
No support for Gremlin OLAP (graph analytics).
No support for custom vertex or edge IDs (Cosmos DB auto-generates them).
Partition key is required and is based on a property of the vertex or edge.
Common Features Across APIs
All APIs share:
Global distribution: replicate data to any Azure region with multi-master writes.
Guaranteed low latency: reads under 10 ms at P99, writes under 10 ms at P99 for single-region writes.
Five consistency levels: Strong, Bounded Staleness, Session, Consistent Prefix, Eventual.
Automatic indexing (except Cassandra API where indexing is manual via secondary indexes).
SLAs for availability (99.999% for multi-region writes), throughput (request units per second), and consistency.
Request Units (RUs)
All operations consume Request Units (RUs), which abstract physical resources (CPU, memory, IOPS). The RU cost depends on:
Item size (larger items cost more).
Operation type (reads are cheaper than writes).
Indexing (indexed properties increase write RU cost).
Consistency level (strong consistency costs more).
For example, a 1 KB document read costs 1 RU, while a 1 KB document write costs about 5 RUs with default indexing. A query that scans many documents costs more than a point read.
Choosing the Right API
For the DP-900 exam, you must know when to use each API:
Core SQL API: when you need native Cosmos DB features, SQL querying, stored procedures, or change feed.
MongoDB API: when migrating an existing MongoDB application or when your team is familiar with MongoDB.
Cassandra API: when migrating an existing Cassandra application or when you need a wide-column model with high write throughput.
Gremlin API: when your data is highly connected (social networks, recommendation engines, fraud detection).
Configuration and Verification
To create a Cosmos DB account with a specific API, use the Azure portal, CLI, or PowerShell. For example, using Azure CLI:
az cosmosdb create --name mycosmosdb --resource-group myRG --kind GlobalDocumentDB --capabilities EnableMongoThe --kind parameter specifies the API: GlobalDocumentDB for Core SQL, GlobalDocumentDB with --capabilities EnableMongo for MongoDB, GlobalDocumentDB with --capabilities EnableCassandra for Cassandra, and GlobalDocumentDB with --capabilities EnableGremlin for Gremlin.
To verify the API endpoint, use:
az cosmosdb show --name mycosmosdb --resource-group myRG --query "documentEndpoint"Interaction with Other Azure Services
Cosmos DB integrates with:
Azure Functions (via change feed trigger).
Azure Stream Analytics (as input/output).
Azure Data Factory (for data movement).
Azure Cognitive Search (for indexing).
Azure Synapse Analytics (via analytical store for HTAP).
Exam Traps
Candidates often confuse the APIs with the data model. Remember: Cosmos DB is a multi-model database, but the API determines the wire protocol and query language. The underlying storage is the same. Also, note that the Table API (for Azure Table storage) is a separate API not covered in this chapter (it is part of the Azure Table storage offering). Finally, be aware that the Gremlin API is not the same as the Neo4j API; it uses the Apache TinkerPop standard.
Create a Cosmos DB Account
In the Azure portal, navigate to 'Create a resource' > 'Databases' > 'Azure Cosmos DB'. Choose the API you want: Core (SQL), MongoDB, Cassandra, or Gremlin. For MongoDB, you must also select the server version (3.6 or 4.0). For Cassandra, you can choose a keyspace name. For Gremlin, you create a graph database. Fill in subscription, resource group, account name, location, and capacity mode (provisioned throughput or serverless). Click 'Review + create'. The account creation takes a few minutes. Behind the scenes, Azure deploys the backend infrastructure and configures the wire protocol listener for the chosen API.
Configure Global Distribution
After account creation, go to 'Replicate data globally' under Settings. Add regions for read and write. You can enable multi-region writes (multi-master) for higher availability. Cosmos DB automatically replicates data asynchronously to all configured regions. The replication lag depends on the consistency level. For Strong consistency, writes are acknowledged only after being committed to all regions. For Eventual, writes are propagated asynchronously. The portal shows the replication status and latency metrics. You can also configure failover priorities for automatic failover.
Create a Database and Container
In the Data Explorer, create a new database. For Core SQL, you then create a container (collection) with a partition key (e.g., /userId). For MongoDB, you create a collection similarly. For Cassandra, you create a keyspace and then a table with a primary key definition (partition key and clustering columns). For Gremlin, you create a graph. The partition key is critical for performance and scalability. Choose a property with high cardinality and even distribution. You can set throughput at the database or container level. For provisioned throughput, specify RUs (e.g., 400 RU/s minimum for a container).
Insert and Query Data Using the API
Use the appropriate SDK or tool. For Core SQL, you can use the Azure portal's Data Explorer to run SQL queries. For MongoDB, use a MongoDB client like Compass or the mongo shell with the connection string provided in the portal (including the username and password). For Cassandra, use cqlsh with the contact point and credentials. For Gremlin, use the Gremlin console or SDK. Insert sample data and run queries. Observe the RU consumption for each operation. For example, a point read in Core SQL consumes 1 RU for a 1 KB document. A query scanning many documents may consume hundreds of RUs.
Monitor Performance and Scale
In the portal, go to 'Metrics' to monitor RU consumption, storage, latency, and request rate. You can set alerts for high RU usage. To scale, adjust the provisioned throughput (RUs) or switch to autoscale. Autoscale automatically scales between 10% and 100% of the max RU setting based on traffic. For serverless, you pay per operation (no provisioned throughput). Also monitor the partition-key statistics to ensure even distribution. If a hot partition occurs, consider redesigning the partition key.
Enterprise Scenario 1: E-commerce Product Catalog with MongoDB API
A large e-commerce company uses MongoDB for its product catalog. They want to migrate to Azure without rewriting their application. They choose Cosmos DB's MongoDB API. The migration involves exporting BSON data using mongodump and importing using mongorestore. They configure a Cosmos DB account with a MongoDB API, set the partition key to /categoryId (since products are often queried by category), and provision 10,000 RU/s. During peak shopping seasons, they enable autoscale to handle spikes. They encounter a challenge: MongoDB aggregation pipelines with $lookup are not supported, so they redesign those queries to use application-side joins. They also notice that secondary indexes are limited; they create custom indexes for frequently filtered fields. Performance monitoring shows that 95% of reads complete under 10 ms. The migration saves them operational overhead compared to managing their own MongoDB cluster.
Enterprise Scenario 2: IoT Time-Series Data with Cassandra API
An IoT platform ingests millions of sensor readings per second. They need a wide-column database with high write throughput. They choose Cosmos DB's Cassandra API. They design a table with partition key = deviceId and clustering column = timestamp (in descending order). This allows efficient range queries for recent data. They provision 100,000 RU/s for writes. They configure Cosmos DB for multi-region writes to ensure low latency for devices worldwide. They discover that Cosmos DB does not support Cassandra's LWT (lightweight transactions), so they implement idempotent writes. They also enable analytical store for historical analytics via Synapse. One misconfiguration: they initially set the partition key to sensorType, which caused hot partitions because one sensor type had 90% of the data. After redesigning with deviceId, distribution improved.
Enterprise Scenario 3: Social Network with Gremlin API
A social media startup wants to build a recommendation engine using graph data. They choose Cosmos DB's Gremlin API. They model users as vertices and friendships as edges. They set the partition key to /region to distribute data by geographic region. They use Gremlin queries like g.V().has('region','US').out('friend').groupCount().by('interest') to find popular interests among friends. They face a limitation: Gremlin OLAP is not supported, so they cannot run large-scale graph analytics. They use Azure Data Lake for offline analytics. They also struggle with the 2 MB document size limit: a vertex with many properties can exceed that, so they normalize large properties into separate vertices. The system handles 10,000 queries per second with P99 latency under 15 ms.
What DP-900 Tests on Cosmos DB APIs
The DP-900 exam (objective 2.4) expects you to:
Identify the appropriate API for a given workload (e.g., document, graph, wide-column).
Understand that Cosmos DB is a multi-model database and that the API does not change the underlying storage engine.
Know that the Core (SQL) API is the native API and supports SQL querying.
Recognize that MongoDB API is wire-protocol compatible, not a full MongoDB implementation.
Know that Cassandra API uses CQL and is suitable for high-write scenarios.
Know that Gremlin API is for graph data.
Understand that partition key is required for all APIs except Table API (not covered here).
Know that all APIs support the same consistency levels and global distribution.
Common Wrong Answers and Why
1. Wrong: 'The MongoDB API supports all MongoDB features including mapReduce and $lookup.' Why chosen: Candidates assume wire compatibility means full feature parity. Reality: Cosmos DB MongoDB API does not support mapReduce, $lookup, $graphLookup, $facet, or change streams.
2. Wrong: 'The Cassandra API provides the same replication model as Apache Cassandra, allowing you to set replication factor per keyspace.' Why chosen: Candidates are familiar with Cassandra's tunable replication. Reality: Cosmos DB manages replication globally; you cannot set replication factor. Consistency levels are mapped to Cosmos DB's levels.
3. Wrong: 'You can switch the API of an existing Cosmos DB account.' Why chosen: Candidates think APIs are interchangeable. Reality: The API is chosen at account creation and cannot be changed later. You must create a new account to use a different API.
4. Wrong: 'The Gremlin API supports OLAP queries for graph analytics.' Why chosen: Candidates assume Gremlin implies full TinkerPop support. Reality: Cosmos DB Gremlin API only supports OLTP (transactional) traversals, not OLAP.
Specific Numbers and Terms
Minimum provisioned throughput: 400 RU/s per container (or 100 RU/s per database shared throughput).
Maximum document size: 2 MB (all APIs).
MongoDB server versions: 3.6 and 4.0.
Cassandra API uses CQL version 4.x.
Gremlin API uses Apache TinkerPop 3.x.
Five consistency levels: Strong, Bounded Staleness, Session, Consistent Prefix, Eventual.
Default indexing: automatic for all properties (Core SQL, MongoDB, Gremlin); manual for Cassandra.
Edge Cases and Exceptions
When using MongoDB API, you cannot create a collection with a different partition key than specified at the database level? Actually, you can set partition key per collection, but it's mandatory.
For Cassandra API, secondary indexes are limited to equality queries only (no range queries).
For Gremlin API, vertices and edges can have properties, but property values are limited to primitive types (string, number, boolean, array).
The Table API (for Azure Table storage) is a separate offering and not part of the multi-model Cosmos DB APIs covered here.
How to Eliminate Wrong Answers
If the question mentions 'SQL queries' or 'stored procedures', the answer is Core SQL API.
If the question mentions 'MongoDB drivers' or 'BSON', the answer is MongoDB API.
If the question mentions 'CQL' or 'wide-column', the answer is Cassandra API.
If the question mentions 'graph' or 'relationships', the answer is Gremlin API.
If the question asks about 'change feed', only Core SQL API supports it (though other APIs can use the change feed via the Core API endpoint).
Cosmos DB is a multi-model database with multiple APIs: Core SQL, MongoDB, Cassandra, and Gremlin.
The API is chosen at account creation and cannot be changed later.
All APIs share the same underlying storage engine and consistency levels.
Core SQL API is the native API with full feature support including SQL queries, stored procedures, and change feed.
MongoDB API is wire-protocol compatible but lacks some MongoDB features like mapReduce and $lookup.
Cassandra API uses CQL and is suitable for high-write, wide-column workloads.
Gremlin API is for graph data and supports OLTP traversals only.
Partition key is mandatory for all APIs and critical for performance.
Minimum provisioned throughput is 400 RU/s per container (or 100 RU/s shared).
Maximum document size is 2 MB across all APIs.
These come up on the exam all the time. Here's how to tell them apart.
Core SQL API
Native Cosmos DB API
SQL query language with JOIN, GROUP BY, subqueries
Supports stored procedures, triggers, UDFs
Change feed available
Best for new applications needing full Cosmos DB features
MongoDB API
Wire-protocol compatible with MongoDB 3.6/4.0
Uses MongoDB query operators and aggregation pipeline (limited)
No stored procedures or triggers (use MongoDB scripts)
No change streams (use Cosmos DB change feed via Core API)
Best for migrating existing MongoDB apps
Cassandra API
Wide-column data model
Uses CQL (Cassandra Query Language)
High write throughput, time-series data
No built-in graph traversal
Best for IoT, telemetry, and logging
Gremlin API
Graph data model (vertices and edges)
Uses Gremlin traversal language
Optimized for relationship queries
No support for OLAP
Best for social networks, recommendations, fraud detection
Mistake
Cosmos DB's MongoDB API is a fully compatible MongoDB database.
Correct
It is wire-protocol compatible for version 3.6 and 4.0 but lacks many MongoDB features like mapReduce, $lookup, $graphLookup, $facet, and change streams. It also has a 2 MB document size limit.
Mistake
You can change the API of an existing Cosmos DB account.
Correct
The API is selected at account creation and cannot be changed. To use a different API, you must create a new account and migrate data.
Mistake
The Cassandra API supports all Cassandra features including lightweight transactions and materialized views.
Correct
Cosmos DB Cassandra API does not support LWT, materialized views, or native change data capture. Consistency levels are mapped to Cosmos DB's levels.
Mistake
The Gremlin API supports graph analytics (OLAP) using Spark.
Correct
Cosmos DB Gremlin API only supports OLTP traversals. For OLAP, use Azure Data Lake or other graph analytics tools.
Mistake
All Cosmos DB APIs require automatic indexing of all properties.
Correct
Core SQL, MongoDB, and Gremlin APIs automatically index all properties by default. The Cassandra API does not; you must create secondary indexes manually.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
No, a single Cosmos DB account supports only one API. You must create separate accounts for different APIs. However, you can access the same data via different APIs if you create multiple accounts pointing to the same data? Actually, no — each account has its own data. You would need to replicate data between accounts.
The MongoDB API supports CRUD operations, indexes, and aggregation pipeline (limited). It does not support mapReduce, $lookup, $graphLookup, $facet, change streams, or MongoDB's transaction API. Document size is limited to 2 MB. Partition key is required and cannot be changed after creation.
It supports most CQL DDL and DML commands (CREATE TABLE, SELECT, INSERT, UPDATE, DELETE, etc.). However, it does not support lightweight transactions (LWT), materialized views, or native change data capture. Secondary indexes are limited to equality queries.
The Gremlin API supports OLTP (transactional) graph traversals with low latency. For large-scale graph analytics (OLAP), you would need to use other services like Azure Data Lake or Apache Spark with GraphX.
Provisioned throughput is best for predictable workloads where you need guaranteed performance and can plan capacity. Serverless is suitable for intermittent or unpredictable traffic where you want to pay only for consumed RUs. Serverless has a maximum of 5 TB storage and 10,000 RU/s per container.
The Table API is designed for Azure Table storage workloads and uses a key-value data model. It is not covered in this chapter. The other APIs (Core SQL, MongoDB, Cassandra, Gremlin) are part of Cosmos DB's multi-model offering.
Yes, you can use mongodump/mongorestore or the Azure Data Migration Service. However, you must be aware of feature limitations and may need to modify your application to work around missing features like $lookup.
You've just covered Cosmos DB APIs: Core SQL, MongoDB, Cassandra, Gremlin — now see how well it sticks with free DP-900 practice questions. Full explanations included, no account needed.
Done with this chapter?