Azure Cosmos DB API Modes Explained: NoSQL, MongoDB, Cassandra, PostgreSQL, Gremlin, and Table

Scenario context

Cosmos DB's six API modes are wire-protocol compatibility layers over one shared ARS storage engine — except PostgreSQL (Citus), which is genuinely different. Every API emulates its native database incompletely, and those gaps are structural, not bugs. API mode is permanent and cannot be changed after account creation. NoSQL API is the only one with full Cosmos DB feature access. MongoDB API fails silently on comple…

This walkthrough focuses on Cosmos DB's Deceptive Promise: Six APIs, One Underlying Engine.

Before making a design choice, clarify:

• A backend team at a mid-sized SaaS company spent three months migrating their MongoDB application to Azure Cosmos DB using the MongoDB API.
• The pitch was compelling: keep your existing MongoDB drivers, point them at a new connection string, and get Azure-managed global distribution and SLAs without any rewrite.
• It worked perfectly in staging.

Concepts in play: database-indexing, btree-vs-lsmtree, consistency-replication, database-sharding

Stage 1 — Wire-Protocol Translation: How Cosmos DB's API Modes Actually Work

• Before diving into individual APIs, it helps to understand the mechanism.
• Cosmos DB is not six separate databases that happen to share a cloud control plane.
• It is one storage engine with six protocol adapters bolted on top.
• The storage engine is called ARS — Atom-Record-Sequence .

Observable outcome: The storage engine is called ARS — Atom-Record-Sequence .

Stage 2 — The Six API Modes: Capabilities, Scope, and Migration Fit

• Each API mode targets a different category of workload and migration scenario.
• Here is the ground-level map before the deep-dive on individual gaps.
• NoSQL API (formerly Core/SQL API) is Cosmos DB's native interface.
• There is no translation layer — ARS speaks this dialect directly.

Observable outcome: There is no translation layer — ARS speaks this dialect directly.

Stage 3 — Anatomy of the Compatibility Gaps: Internals and Performance Impact

• Understanding where the gaps come from — not just what they are — prevents you from designing workarounds that will also fail.
• Internals: How the ARS Engine Creates Structural Gaps ARS manages data as a hierarchy: database → container → logical partition → physical partition .
• Every operation in ARS is scoped to a logical partition, identified by the partition key value.
• Within a single logical partition, ARS can provide ACID guarantees: reads see a consistent snapshot, writes are ordered, and multi-document transactions commit atomically.

flowchart TD
    DB["Database
(WAL/Log)"]
    Capture["Capture Engine"]
    Transform["Transform"]
    Sink["Sink/Destination"]

    DB -->|"Change Log"| Capture
    Capture -->|"CDC Event"| Transform
    Transform -->|"Normalized"| Sink

Observable outcome: Within a single logical partition, ARS can provide ACID guarantees: reads see a consistent snapshot, writes are ordered, and multi-document transactions commit atomically.

Stage 4 — The Full Architecture: From Client to Storage Across Every API

• The diagram below shows how each API mode sits as a protocol translation layer between the client and the underlying ARS storage engine.
• The PostgreSQL API (Citus) is shown separately because it does not share the ARS engine.
• The diagram makes the structural split visible.
• Five of the six API modes (MongoDB, Cassandra, NoSQL, Gremlin, Table) are protocol adapters routing into the same ARS storage engine — which is why they share the same partition model, the same consistency levels, and t…

flowchart TD
    subgraph Clients
        A[MongoDB Driver]
        B[Cassandra Driver / cqlsh]
        C[Azure SDK / NoSQL SDK]
        D[Gremlin Client / TinkerPop]
        E[Azure Table Storage SDK]
        F[PostgreSQL Client / psql]
    end

    subgraph CosmosDB_ARS[Cosmos DB  ARS Engine]
        direction TB
        M[MongoDB Protocol Adapter]
        K[Cassandra CQL Adapter]
        N[NoSQL Native Layer]
        G[Gremlin TinkerPop Adapter]
        T[Table OData Adapter]
        ARS[(ARS Storage Engine Partitioned JSON atoms Multi-region replication 5 consistency levels)]

        M --> ARS
        K --> ARS
        N --> ARS
        G --> ARS
        T --> ARS
    end

    subgraph CosmosDB_PG[Cosmos DB for PostgreSQL]
        direction TB
        PG[PostgreSQL / Citus Distributed query executor Full ACID  JOINs  Extensions]
    end

    A --> M
    B --> K
    C --> N
    D --> G
    E --> T
    F --> PG

    style ARS fill:#1e3a5f,color:#fff
    style PG fill:#336791,color:#fff
    style CosmosDB_ARS fill:#0f2540,color:#ccc
    style CosmosDB_PG fill:#1a3a5c,color:#ccc

Observable outcome: Five of the six API modes (MongoDB, Cassandra, NoSQL, Gremlin, Table) are protocol adapters routing into the same ARS storage engine — which is why they share the same partition model, the same consistency levels, and t…

Stage 5 — Where Each API Succeeds and Fails in Production Migrations

• Real-world migration outcomes fall into three categories: clean migrations where the API covers all required functionality, conditional migrations where the API works but requires query pattern changes, and blocked migr…
• MongoDB API — Conditional for most, blocked for complex aggregation: Teams migrating MongoDB 3.6/4.0 apps that use CRUD and simple aggregation ( $match , $group , $project , $sort , $limit ) consistently report clean mi…
• The driver reconnects, basic features work, and RU provisioning replaces ops overhead.
• The migration fails when the app uses $lookup across collections, $graphLookup , $facet , $bucket , text search ( $text index), or change streams with precise resume-token semantics.

Observable outcome: The migration fails when the app uses $lookup across collections, $graphLookup , $facet , $bucket , text search ( $text index), or change streams with precise resume-token semantics.

Stage 6 — The Compatibility Gap Tables: What Each API Cannot Do

• These tables cover the gaps that most frequently block or complicate production migrations.
• The "Impact" column describes the real consequence teams encounter.
• MongoDB API Gaps Cassandra API Gaps Gremlin API Gaps

Observable outcome: MongoDB API Gaps Cassandra API Gaps Gremlin API Gaps

End-to-end outcome

After working through the stages, you should be able to explain:

• The "looks like MongoDB" assumption is the most dangerous.
• Teams that evaluate Cosmos DB's MongoDB API by running their basic test suite almost always get a green signal.

Alternatives considered

The source focuses on one primary design. A second architecture is not compared, so no alternative is invented here.

Failure and degraded modes

The source does not isolate a separate failure mode. Limits that matter for the scenario are called out in the stage decisions above.