Recent from talks
Nothing was collected or created yet.
Cosmos DB
View on WikipediaThis article may rely excessively on sources too closely associated with the subject, potentially preventing the article from being verifiable and neutral. (July 2015) |
| Azure Cosmos DB | |
|---|---|
| Developer | Microsoft |
| Initial release | 2017 |
| Available in | English |
| Type | Multi-model database |
| Website | learn |
Azure Cosmos DB is a globally distributed, multi-model database service offered by Microsoft. It is designed to provide high availability, scalability, and low-latency access to data for modern applications. Unlike traditional relational databases, Cosmos DB is a NoSQL (meaning "Not only SQL", rather than "zero SQL") and vector database,[1] which means it can handle unstructured, semi-structured, structured, and vector data types.[2]
Data model
[edit]Internally, Cosmos DB stores "items" in "containers",[3] with these two concepts being surfaced differently depending on the API used (these would be "documents" in "collections" when using the MongoDB-compatible API, for example). Containers are grouped in "databases", which are analogous to namespaces above containers. Containers are schema-agnostic, which means that no schema is enforced when adding items.
By default, every field in each item is automatically indexed, generally providing good performance without tuning to specific query patterns. These defaults can be modified by setting an indexing policy which can specify, for each field, the index type and precision desired. Cosmos DB offers two types of indexes:
- range, supporting range and ORDER BY queries
- spatial, supporting spatial queries from points, polygons, and line strings encoded in standard GeoJSON fragments
Containers can also enforce unique key constraints to ensure data integrity.[4]
Each Cosmos DB container exposes a change feed, which clients can subscribe to in order to get notified of new items being added or updated in the container.[5] As of 7 June 2021, item deletions are currently not exposed by the change feed. Changes are persisted by Cosmos DB, which makes it possible to request changes from any point in time since the creation of the container.
A "Time to Live" (or TTL) can be specified at the container level to let Cosmos DB automatically delete items after a certain amount of time expressed in seconds. This countdown starts after the last update of the item. If needed, the TTL can also be overloaded at the item level.
Multi-model APIs
[edit]The internal data model described in the previous section is exposed through:
- a proprietary SQL API.
- five different compatibility APIs, exposing endpoints that are partially compatible with the wire protocols of MongoDB, Gremlin, Cassandra, Azure Table Storage, and etcd; these compatibility APIs make it possible for any compatible application to connect to and use Cosmos DB through standard drivers or SDKs, while also benefiting from Cosmos DB's core features like partitioning and global distribution.
| API | Internal mapping | Compatibility status and remarks | |
|---|---|---|---|
| Containers | Items | ||
| MongoDB | Collections | Documents | Compatible with wire protocol version 6 and server version 3.6 of the MongoDB.[6] |
| Gremlin | Graphs | Nodes and edges | Compatible with version 3.2 of the Gremlin specification. |
| Apache Cassandra | Table | Row | Compatible with version 4 of the Cassandra Query Language (CQL) wire protocol. |
| Azure Table Storage | Table | Item | |
| etcd | Key | Value | Compatible with version 3 of etcd.[7] |
SQL API
[edit]The SQL API lets clients create, update and delete containers and items. Items can be queried with a read-only, JSON-friendly SQL dialect.[8] As Cosmos DB embeds a JavaScript engine, the SQL API also enables:
- Stored procedures. Functions that bundle an arbitrarily complex set of operations and logic into an ACID-compliant transaction. They are isolated from changes made while the stored procedure is executing and either all write operations succeed or they all fail, leaving the database in a consistent state. Stored procedures are executed in a single partition. Therefore, the caller must provide a partition key when calling into a partitioned collection. Stored procedures can be used to make up for the lack of certain functionality. For instance, the lack of aggregation capability is made up for by the implementation of an OLAP cube as a stored procedure in the open sourced documentdb-lumenize[9] project.
- Triggers. Functions that get executed before or after specific operations (like on a document insertion for example) that can either alter the operation or cancel it. Triggers are only executed on request.
- User-defined functions (UDF). Functions that can be called from and augment the SQL query language making up for limited SQL features.
The SQL API is exposed as a REST API, which itself is implemented in various SDKs that are officially supported by Microsoft and available for .NET Framework, .NET,[10] Node.js (JavaScript), Java and Python.
Partitioning
[edit]Cosmos DB added automatic partitioning capability in 2016 with the introduction of partitioned containers. Behind the scenes, partitioned containers span multiple physical partitions with items distributed by a client-supplied partition key. Cosmos DB automatically decides how many partitions to spread data across depending on the size and throughput needs. When partitions are added or removed, the operation is performed without any downtime so data remains available while it is re-balanced across the new or remaining partitions.
Before partitioned containers were available, it was common to write custom code to partition data and some of the Cosmos DB SDKs explicitly supported several different partitioning schemes. That mode is still available but only recommended when storage and throughput requirements do not exceed the capacity of one container, or when the built-in partitioning capability does not otherwise meet the application's needs.
Tunable throughput
[edit]Developers can specify desired throughput to match the application's expected load. Cosmos DB reserves resources (memory, CPU and IOPS) to guarantee the requested throughput while maintaining request latency below 10ms for both reads and writes at the 99th percentile. Throughput is specified in Request Units (RUs) per second. The cost to read a 1 KB item is 1 Request Unit (or 1 RU). Select by 'id' operations consume lower number of RUs compared to Delete, Update, and Insert operations for the same document. Large queries (e.g. aggregations like count) and stored procedure executions can consume hundreds to thousands of RUs depending on the complexity of the operations needed.[11] The minimum billing is per hour.
Throughput can be provisioned at either the container or the database level. When provisioned at the database level, the throughput is shared across all the containers within that database, with the additional ability to have dedicated throughput for some containers. The throughput provisioned on an Azure Cosmos container is exclusively reserved for that container.[12] The default maximum RUs that can be provisioned per database and per container are 1,000,000 RUs, but customers can get this limit increased by contacting customer support.
As an example of costing, using a single region instance, a count of 1,000,000 records of 1k each in 5s requires 1,000,000 RUs At $0.008/h, which would equal $800. Two regions double the cost.
Global distribution
[edit]Cosmos DB databases can be configured to be available in any of the Microsoft Azure regions (54 regions as of December 2018), letting application developers place their data closer to where their users are.[13] Each container's data gets transparently replicated across all configured regions. Adding or removing regions is performed without any downtime or impact on performance. By leveraging Cosmos DB's multi-homing API, applications don't have to be updated or redeployed when regions are added or removed, as Cosmos DB will automatically route their requests to the regions that are available and closest to their location.
Consistency levels
[edit]Data consistency is configurable on Cosmos DB, letting application developers choose among five different levels:[14]
- Eventual does not guarantee any ordering and only ensures that replicas will eventually converge
- Consistent prefix adds ordering guarantees on top of eventual
- Session is scoped to a single client connection and basically ensures a read-your-own-writes consistency for each client; it is the default consistency level[15]
- Bounded staleness augments consistent prefix by ensuring that reads won't lag beyond x versions of an item or some specified time window
- Strong consistency (or linearizable) ensures that clients always read the latest globally committed write
The desired consistency level is defined at the account level but can be overridden on a per request basis by using a specific HTTP header or the corresponding feature exposed by the SDKs. All five consistency levels have been specified and verified using the TLA+ specification language, with the TLA+ model being open-sourced on GitHub.[16]
Multi-master
[edit]Cosmos DB's original distribution model involves one single write region, with all other regions being read-only replicas. In March 2018, Microsoft announced a new multi-master capability for Azure Cosmos DB, allowing multiple regions to serve as write replicas. This feature introduced a significant improvement to its original single write-region model, where other regions were read-only. With multi-master, concurrent writes from different regions can lead to potential conflicts, which can be resolved either using the default "Last Write Wins" (LWW) policy or a custom conflict resolution mechanism, such as a JavaScript function. The LWW policy relies on timestamps to determine the winning write, while the custom option enables developers to handle conflicts through application-defined rule. [17]
Analytical Store
[edit]This feature, announced in May 2020,[18] is a fully isolated column store for enabling large scale analytics against operational data in the Azure Cosmos DB, without any impact to its transactional workloads. This feature addresses the complexity and latency challenges that occur with the traditional ETL pipelines required to have a data repository optimized to execute Online analytical processing by automatically syncing the operational data into a separate column store suitable for large scale analytical queries to be performed in an optimized manner, resulting in improving the latency of such queries.
Using Microsoft Azure Synapse Link[19] for Cosmos DB, it is possible to build no-ETL Hybrid transactional/analytical processing solutions by directly linking to Azure Cosmos DB analytical store from Synapse Analytics. It enables to run near real-time large-scale analytics directly on the operational data.
Real-world use cases
[edit]Microsoft utilizes Cosmos DB in many of its own apps,[20] including Microsoft Office, Skype, Active Directory, Xbox, and MSN.
In building a more globally-resilient application / system, Cosmos DB combines with other Azure services, such as Azure App Services and Azure Traffic Manager.[21]
Cosmos DB Profiler
[edit]The Cosmos DB Profiler cloud cost optimization tool detects inefficient data queries in the interactions between an application and its Cosmos DB database. The profiler alerts users to wasted performance and excessive cloud expenditures. It also recommends how to resolve them by isolating and analyzing the code and directing its users to the exact location.[22]
Limitations
[edit]- SQL is limited. Aggregations limited to COUNT, SUM, MIN, MAX, AVG functions but no support for GROUP BY or other aggregation functionality found in database systems. However, stored procedures can be used to implement in-the-database aggregation capability.[23]
- SQL joins between "tables" are not possible,
- Support only for pure JSON data types. Most notably, Cosmos DB lacks support for date-time data requiring that you store this data using the available data types. For instance, it can be stored as an ISO-8601 string or epoch integer. MongoDB, the database to which Cosmos DB is most often compared, extended JSON in their BSON binary serialization specification to cover date-time data as well as traditional number types, regular expressions, and Undefined.
References
[edit]- ^ "Vector Database". learn.microsoft.com. Retrieved 30 March 2024.
- ^ Kumar, Chandan (7 March 2023). "Azure Cosmos DB and NoSQL databases". skillzcafe. Retrieved 2023-04-11.
- ^ "Working with Azure Cosmos DB databases, containers and items". docs.microsoft.com. Retrieved 2018-12-13.
- ^ "Unique keys in Azure Cosmos DB". Dibran's Blog. 3 July 2018. Retrieved 2018-12-13.
- ^ "Working with the change feed support in Azure Cosmos DB". docs.microsoft.com. Retrieved 2021-07-03.
- ^ "Azure Cosmos DB API now supports MongoDB version 3.6". azure.microsoft.com. Retrieved 2020-02-11.
- ^ "Introduction to the Azure Cosmos DB etcd API". docs.microsoft.com. Retrieved 2020-06-10.
- ^ "SQL language syntax in Azure Cosmos DB". docs.microsoft.com. Retrieved 2018-12-13.
- ^ Maccherone, Larry. "Announcing documentdb-lumenize". blog.lumenize.com. Retrieved 2016-12-11.
- ^ "Using Azure DocumentDB and ASP.NET Core for extreme NoSQL performance". auth0.com.
- ^ "Provisioned Throughput: Request Units in Azure Cosmos DB". docs.microsoft.com. Retrieved 2019-07-21.
- ^ "Provision throughput on containers and databases". docs.microsoft.com. Retrieved 2019-07-21.
- ^ "How to distribute data globally with Azure Cosmos DB". docs.microsoft.com. Retrieved 2017-08-22.
- ^ "Diving Deep Into Different Consistency Levels Of Azure Cosmos DB". www.c-sharpcorner.com. Retrieved 2018-12-13.
- ^ "Tunable data consistency levels in Azure Cosmos DB". docs.microsoft.com. Microsoft. Retrieved 2017-08-22.
- ^ GitHub - Azure/azure-cosmos-tla: Azure Cosmos TLA+ specifications., Microsoft Azure, 2018-12-09, retrieved 2018-12-13
- ^ "Cosmos DB Multi-Master support now generally available | Azure updates | Microsoft Azure".
- ^ "Microsoft Announces a New Pricing Model Option for Azure Cosmos DB and More Capabilities". www.infoq.com. Retrieved 2020-06-20.
- ^ "A closer look at Azure Synapse Link". ZDNet. Retrieved 2017-04-15.
- ^ http://www.vldb.org/pvldb/vol8/p1668-shukla.pdf [bare URL PDF]
- ^ Pietschmann, Chris (28 June 2017). "Building Globally Resilient Apps with Azure App Service and Cosmos DB". Build5Nines.com. Opsgility. Retrieved 30 January 2018.
- ^ "Cosmos DB Profiler". hibernatingrhinos.com. Hibernating Rhinos. Retrieved 2020-05-20.
- ^ "Add Group By support for Aggregate Functions". feedback.azure.com. Retrieved 2019-03-31.
External links
[edit]Cosmos DB
View on GrokipediaHistory and Overview
Development History
Azure Cosmos DB originated as Project Florence in 2010, an internal Microsoft initiative designed to resolve scalability challenges encountered in large-scale applications, such as elastic scaling of throughput and storage to manage unpredictable workload spikes.[4] This project addressed pain points in services requiring high availability and global distribution, evolving through internal iterations to support Microsoft's own workloads before external release.[4] The technology underlying Cosmos DB saw extensive internal deployment at Microsoft for nearly a decade prior to its public launch, powering critical systems and refining its multi-model and distributed capabilities in production environments.[7] On May 10, 2017, Microsoft officially announced Azure Cosmos DB and made it generally available as a fully managed, globally distributed, multi-model database service, building on the foundations of the earlier Azure DocumentDB while introducing turnkey global replication and multiple consistency models.[8][9] Key milestones in its evolution include the introduction of serverless mode in 2020, which enabled on-demand throughput provisioning without fixed capacity commitments, simplifying development for bursty workloads.[10] In 2023, Cosmos DB added vector search capabilities, initially for the MongoDB vCore API, allowing efficient storage, indexing, and querying of high-dimensional vectors to support AI-driven applications.[11] That same year, support for the PostgreSQL API reached general availability in October 2022, extending Cosmos DB's relational capabilities with distributed scaling via the Citus extension; however, as of October 2025, Azure Cosmos DB for PostgreSQL is no longer supported for new projects, with Microsoft recommending alternatives such as Azure Database for PostgreSQL.[12][13] By 2025, Cosmos DB continued to advance with integrations to Microsoft Fabric and enhanced support for AI workloads, announced at Microsoft Build in May, including automatic scaling optimizations tailored for generative AI scenarios.[14] These updates featured expanded vector indexing, such as the general availability of DiskANN for large-scale similarity searches up to 4,096 dimensions, further embedding Cosmos DB in AI ecosystems.[15]Key Features and Benefits
Azure Cosmos DB provides turnkey global distribution, enabling automatic data replication to any number of Azure regions with a 99.999% availability service level agreement (SLA) for both reads and writes in multi-region configurations.[16] This high availability is maintained even during regional outages, ensuring business continuity without manual intervention.[16] The service guarantees read latency under 10 ms and write latency under 15 ms at the 99th percentile using direct connectivity, delivering low-latency performance worldwide.[17] Elastic scalability allows seamless adjustment of throughput and storage capacity without downtime, supporting instant scaling to meet varying workloads.[18] Multi-model support accommodates diverse data types, including document, key-value, graph, column-family, and vector models, without enforcing schemas for flexible storage and querying via multiple APIs.[18] Built-in security features encompass encryption at rest and in transit, role-based access control (RBAC) via Microsoft Entra ID, and private endpoints for secure connectivity.[19] For cost efficiency, Azure Cosmos DB offers serverless throughput, which charges only for consumed request units, and provisioned throughput modes with autoscale options to match predictable or variable demands.[20] It integrates deeply with the Azure ecosystem, facilitating serverless computing via Azure Functions, real-time analytics with Azure Synapse Link, and AI workloads through vector search capabilities.[18]Architecture and Data Model
Resource Model
Azure Cosmos DB organizes its resources in a hierarchical model, with the account serving as the top-level resource that scopes and manages all underlying databases and containers. An account represents a unit of administrative division within an Azure subscription, enabling features such as multi-region replication and consistency configuration. By default, a subscription supports up to 250 accounts, though this limit can be increased to 1,000 via a support request.[21] Accounts are created and managed through the Azure portal, Resource Manager templates, PowerShell, CLI, SDKs, or REST API.[22] Databases function as logical namespaces within an account, grouping one or more containers to provide isolation and organization for related data sets. Each database can optionally provision shared throughput, allowing up to 25 containers to draw from a common pool of request units (RUs) per second, with a maximum of 1,000,000 RUs (increasable via support). This shared model simplifies provisioning for workloads with varying demands across containers, while dedicated throughput can be assigned directly to individual containers outside of databases. Databases map to concepts like keyspaces in the Cassandra API but are not applicable in the Table API.[22][21] Containers represent the core scalable units for data storage and operations in Cosmos DB, holding items and supporting horizontal scaling through partitioning. Each container requires a partition key to distribute data across logical partitions, with no upper limit on total storage capacity per container—enabling petabyte-scale datasets when properly partitioned. However, individual logical partitions are capped at 20 GB of storage (temporarily increasable via support), and physical partitions, which are managed internally, hold up to 50 GB. Containers support schema-agnostic data ingestion, automatic indexing, time-to-live (TTL) policies, change feeds, and server-side programmability via stored procedures, triggers, and user-defined functions. Throughput for containers can be provisioned as dedicated (standard or autoscale) or shared via the parent database.[22][21][23] Items are the atomic units of data within containers, typically represented as JSON documents in the NoSQL API or equivalents such as rows in the Table API, documents in MongoDB, or vertices/edges in Gremlin. Each item must have a uniqueid (user-provided, up to 1,023 bytes) within its logical partition and an optional partition key value (up to 2,048 bytes). The maximum size for an item is 2 MB (measured by the UTF-8 length of its JSON representation), beyond which performance and cost efficiency may degrade. Cosmos DB automatically adds system-generated properties to items for management and operations: _rid provides a unique resource identifier, _ts records the last update timestamp (in Unix epoch seconds), and _etag enables optimistic concurrency control by tagging resource versions. Items support standard CRUD operations (create, read, update, delete, upsert) across all APIs.[22][21]
Multi-model Support
Azure Cosmos DB provides multi-model support by natively accommodating various data models within a single, globally distributed database service, allowing developers to select the most suitable model and API for their applications without managing multiple disparate databases.[18] This capability is enabled through compatibility with multiple open-source APIs, each tailored to specific data paradigms, while leveraging a shared infrastructure for storage and operations.[24] The service supports a document model using JSON-like structures for handling semi-structured data, primarily via the API for NoSQL, which stores items as flexible, hierarchical documents.[18] For simple, high-performance lookups, it offers a key-value model through the Table API, where data is stored and retrieved using unique keys without complex querying needs.[24] The column-family model, suited for wide-column stores and analytical workloads, is provided by the Apache Cassandra API, enabling efficient handling of sparse, multidimensional data.[18] In addition, the graph model represents interconnected data as vertices and edges, supported by the Apache Gremlin API for traversing relationships in social networks, recommendation engines, or fraud detection systems.[24] Cosmos DB also extends compatibility to MongoDB's BSON documents via the MongoDB API (in both request unit and vCore modes), preserving the binary JSON format for document-oriented applications, and to PostgreSQL's relational structures through the PostgreSQL API, allowing SQL-based relational modeling with ACID transactions; as of November 2025, the PostgreSQL API is no longer supported for new projects, though existing deployments remain supported—Microsoft recommends Azure Database for PostgreSQL Flexible Server for new relational workloads.[18] For the NoSQL-compatible APIs (NoSQL, MongoDB, Cassandra, Gremlin, and Table), Cosmos DB employs a unified storage engine built on an atoms-records-sequences (ARS) design, which abstracts the underlying storage to map diverse data models seamlessly without requiring separate physical databases.[24] The PostgreSQL API, however, uses a separate distributed engine based on Citus and native PostgreSQL storage. This enables developers to choose and switch among the NoSQL-compatible APIs per container—units within the resource hierarchy that hold model-specific items—without data migration, as the same data can be accessed via different APIs by adjusting the client configuration.[22] For instance, a container provisioned for the NoSQL API stores JSON items, while one for Cassandra stores rows, yet both reside in the same account and share global distribution features.[18] The PostgreSQL API follows a distinct resource model with clusters, databases, schemas, and distributed tables. The following table illustrates how containers adapt to different models by defining the entity types for data storage:| API | Container Entity | Data Entity |
|---|---|---|
| API for NoSQL | Container | Item (JSON) |
| API for Cassandra | Table | Row |
| API for MongoDB | Collection | Document (BSON) |
| API for Gremlin | Graph | Node or Edge |
| API for Table | Table | Item (key-value) |
| API for PostgreSQL | Table | Row (relational) |
APIs and Query Languages
Core (SQL) API
The Core (SQL) API in Azure Cosmos DB provides a JSON-based querying interface inspired by ANSI SQL, enabling developers to query semi-structured data stored as JSON documents in containers. This API supports core SQL clauses such as SELECT for projecting specific properties or entire documents, FROM to specify the container as the data source, and WHERE for filtering based on conditions like equality, range, or logical operators. Aggregate functions like COUNT, SUM, MIN, MAX, AVG, and DISTINCT are also available to perform computations over document sets, facilitating common analytical operations directly within queries. JOIN operations are supported but limited to intra-partition joins, allowing correlations between documents sharing the same partition key without cross-partition overhead.[27] Indexing policies in the Core (SQL) API ensure efficient query performance by default applying range indexing to all paths in JSON documents, which supports equality, range, and order-by queries on strings and numbers. This default policy automatically indexes every property unless customized, promoting broad query flexibility. For optimization, users can define exclusion paths to omit non-queryable properties from indexing, reducing storage costs, write latency, and Request Unit (RU) consumption— for example, excluding system-generated fields like _etag. Custom policies may also include spatial or composite indexes for specialized queries, but the core focus remains on range indexing for general-purpose performance tuning.[28] Server-side programmability in the Core (SQL) API allows execution of JavaScript-based stored procedures, triggers, and user-defined functions (UDFs) to encapsulate business logic within the database. Stored procedures enable transactional operations across multiple items in a single partition, such as bulk imports or updates, ensuring atomicity via optimistic concurrency control. Pre-triggers execute before document operations (e.g., validation), while post-triggers run afterward (e.g., logging), both participating in the same transaction to maintain consistency. UDFs extend query capabilities by allowing custom scalar functions invoked within SELECT clauses, such as complex calculations, without affecting transactions.[29] Full-text search capabilities in the Core (SQL) API are integrated with Azure AI Search (formerly Azure Cognitive Search), enabling advanced text indexing and querying of JSON documents as a data source. This integration supports features like semantic ranking, faceting, and AI-enriched search (e.g., entity recognition), where Cosmos DB containers are indexed via an indexer to power relevance-based retrieval. Queries can combine full-text with SQL filters for hybrid scenarios, such as searching product descriptions while filtering by category.[30] Query metrics provide detailed insights into execution performance, including total elapsed time (broken down by document load, index lookup, and VM execution phases), RU consumption per query, and the number of documents scanned or retrieved. These metrics help identify bottlenecks, such as inefficient filters leading to full scans, and include optimization recommendations like adding indexes or rewriting predicates. Access is available through SDK diagnostics or REST API responses, with index metrics specifically highlighting utilized versus missing indexes for query improvement.[31] Geospatial queries in the Core (SQL) API support GeoJSON data types, including Point, LineString, Polygon, and MultiPolygon, adhering to the WGS-84 coordinate reference system for real-world location representation. Built-in functions like ST_DISTANCE, ST_WITHIN, and ST_INTERSECTS enable proximity searches, bounding box filters, and polygon containment checks, such as finding points within a radius or intersecting regions. Indexing for geospatial data is handled via the container's policy, with spatial indexes automatically applied to GeoJSON paths to ensure efficient query resolution without full scans.[32]MongoDB, Cassandra, Gremlin, and Table APIs
Azure Cosmos DB provides multiple APIs beyond its core SQL interface to ensure compatibility with popular open-source databases and ecosystems, allowing developers to use existing applications, drivers, and tools with minimal modifications. These include the API for MongoDB, API for Apache Cassandra, API for Apache Gremlin, and API for Table, each emulating the wire protocol and query languages of their respective origins while leveraging Cosmos DB's underlying distributed architecture for scalability and global replication. This multi-model support enables seamless integration into diverse workloads, such as document stores, wide-column stores, graph databases, and key-value systems, all mapped to a shared resource model of databases, containers, and items.[26] The API for MongoDB offers full compatibility with the MongoDB wire protocol, supporting versions up to 8.0 in the vCore architecture and enabling the use of standard MongoDB drivers, SDKs, and tools. It accommodates document-oriented workloads with features like aggregation pipelines for complex data processing, automatic sharding for horizontal scaling across partitions, and replica sets for high availability through native replication. For instance, aggregation stages such as$match, $group, and $sort are fully supported, allowing pipelines to perform filtering, grouping, and sorting on large datasets without code changes. However, multi-document transactions are limited to operations within a single non-sharded collection. A key limit is the maximum document size of 16 MB, applicable to collections created after enabling the feature, aligning with MongoDB's standard constraints to prevent oversized payloads.[33][34][33]
Migration from open-source MongoDB to the Cosmos DB API for MongoDB typically involves no application code changes due to wire protocol compatibility, with data transfer facilitated by tools like the Azure Database Migration Service or the Cosmos DB Data Migration Tool, which handle bulk imports from JSON or MongoDB exports while preserving indexes and schemas. Pre-migration assessments focus on verifying compatibility for features like geospatial queries and change streams, ensuring workloads can leverage Cosmos DB's tunable consistency and global distribution post-migration.[35][36]
The API for Apache Cassandra serves as a drop-in replacement for Apache Cassandra versions 3.0 and later, supporting the Cassandra Query Language (CQL) v3.11 with backward compatibility to v2.x, and integrating seamlessly with existing Cassandra client drivers via the CQL Binary Protocol v4. It enables wide-column data modeling with commands like CREATE TABLE, INSERT, SELECT, UPDATE, and DELETE, including support for data types such as bigint, uuid, and aggregates like avg and [count](/page/Count), while offering per-operation tunable consistency levels—such as eventual or strong—for reads and writes. This allows applications to maintain Cassandra-specific patterns, like denormalized tables for high-throughput queries, without refactoring. API-specific limits include restrictions on certain advanced commands, such as CREATE FUNCTION or ALTER ROLE, to align with Cosmos DB's managed service boundaries.[37][37][38]
For migration from Apache Cassandra, paths emphasize zero-downtime options using dual-write proxies or Spark-based ETL processes, where existing CQL queries and drivers connect directly to Cosmos DB endpoints, facilitating live data synchronization from on-premises or cloud clusters while optimizing for Cosmos DB's partitioning model. Tools like cqlsh's COPY command or Azure Databricks enable bulk data movement, with post-migration adjustments primarily for throughput provisioning to match Cassandra's eventual consistency defaults.[39][40]
The API for Apache Gremlin provides graph database capabilities compliant with Apache TinkerPop 3.4, supporting the Gremlin traversal language for querying property graphs with vertices, edges, and properties through operations like addV(), addE(), out(), and in(). It enables complex relationship traversals, such as pathfinding and pattern matching, using breadth-first search for optimized performance in distributed environments, and integrates with open-source Gremlin SDKs via wire protocol support. Key features include automatic indexing of graph elements and compatibility with graph analytics tools, though it diverges from pure TinkerPop in traversal strategy to prioritize scalability. Limits include a maximum operator depth of 400 unique steps per traversal and a repeat limit of 32 iterations for loops like .repeat(), capping effective traversal depth at 32 hops to manage resource consumption in large graphs. Recommended client libraries are version 3.4.13.[41][42][42]
Migration from open-source Gremlin graphs to Cosmos DB involves exporting data in formats like GraphSON or CSV and importing via the Bulk Executor library or Spark connectors, with no changes required for Gremlin query syntax due to protocol compatibility; this path supports gradual cutover by running parallel traversals during data sync.[43]
The API for Table emulates Azure Table Storage for simple key-value and tabular data operations, supporting existing SDKs and tools with wire protocol compatibility for tasks like entity insertion, updates, and deletions using partition keys and row keys. It facilitates OData querying for filtering, sorting, and selecting properties—such as $filter=PartitionKey eq 'value' and $orderby=RowKey—along with LINQ support in .NET, enabling efficient lookups on semi-structured data without schema enforcement. This API is suited for scenarios like IoT telemetry or session stores, with automatic indexing on all properties to accelerate queries. Unlike other APIs, it enforces a 2 MB limit per entity to maintain performance, distinct from MongoDB's larger document allowance.[44][45][21]
Migration from Azure Table Storage or similar key-value systems requires no code alterations, with the Cosmos DB Data Migration Tool handling bulk imports from CSV or direct connections, optimizing for Cosmos DB's global distribution while preserving OData query patterns for seamless application portability.[36]
PostgreSQL API
Azure Cosmos DB for PostgreSQL provided a distributed relational database service compatible with PostgreSQL, supporting standard SQL queries and extensions like Citus for horizontal scaling across nodes. It allowed developers to use familiar PostgreSQL tools, drivers, and applications for relational workloads with Cosmos DB's global distribution and scalability. As of October 2025, Azure Cosmos DB for PostgreSQL is no longer supported for new projects; existing deployments continue, but Microsoft recommends migrating to Azure Database for PostgreSQL flexible server or Azure SQL Database for new relational applications.[46]Scaling and Partitioning
Logical Partitioning
In Azure Cosmos DB, logical partitioning organizes data by grouping items that share the same partition key value into a logical partition, which serves as the unit of distribution and scalability. A partition key, such as/userId, is a JSON property path defined when creating a container, ensuring all items with the same key value (e.g., "user123") are stored together in one logical partition. This design enables efficient single-partition transactions and queries, as operations within a logical partition do not require cross-partition coordination.[23]
Physical partitions are the underlying storage units managed by Azure Cosmos DB, each capable of holding up to 50 GB of data and providing up to 10,000 request units per second (RU/s) of throughput. Multiple logical partitions are distributed across these physical partitions based on an internal hashing mechanism, with the system automatically splitting physical partitions when they exceed storage or throughput limits to maintain performance and availability. Each logical partition itself is limited to 20 GB of storage and 10,000 RU/s, preventing any single partition from becoming a bottleneck.[23][21]
Selecting an effective partition key is crucial for optimal performance and involves choosing a property with high cardinality to ensure even data and workload distribution across logical partitions, thereby avoiding hotspots where one partition receives disproportionate traffic. The key should also be immutable throughout the item's lifecycle to prevent costly data movement between partitions, and it must align with common query patterns to minimize cross-partition operations. For example, using /customerId for e-commerce orders distributes load evenly if customer activity is balanced, while avoiding low-cardinality keys like /region that could concentrate data in few partitions.[23]
Cross-partition queries, which span multiple logical partitions, are supported but less efficient than single-partition queries, as they require fan-out to all relevant physical partitions, increasing latency and RU consumption (typically 2-3 additional RU/s per physical partition involved). To optimize, queries should include the partition key in the filter whenever possible. For legacy datasets lacking a natural high-cardinality key, synthetic partition keys—such as concatenating fields like /customerId_orderDate—can be used to artificially distribute data evenly without altering the original schema.[23][47]
Throughput provisioned to a container is distributed evenly across physical partitions, with each logical partition capped at 10,000 RU/s to enforce balanced scaling.[23]