Cosmos DB
Azure Cosmos DB is a fully managed, globally distributed, multi-model NoSQL database service developed by Microsoft as part of the Azure cloud platform, offering seamless scalability, low-latency access, and support for multiple data models including document, key-value, graph, column-family, and vector data to enable modern application development.[1] Launched in general availability on May 10, 2017, it evolved from the earlier Azure DocumentDB service and was announced at Microsoft Build 2017 as the industry's first globally distributed, multi-model database.[2] The service provides single-digit millisecond response times at any scale through automatic and independent partitioning, with throughput and storage scaling elastically to handle petabyte-scale workloads. It supports multiple APIs for flexibility, including the native Azure Cosmos DB API for NoSQL (SQL querying), compatibility with MongoDB vCore and API for MongoDB, Apache Cassandra, Apache Gremlin for graph data, Azure Table API for key-value, and Azure Cosmos DB for PostgreSQL, allowing developers to use familiar tools without data migration. A core strength is its turnkey global distribution, enabling data replication across any number of Azure regions with configurable consistency levels (strong, bounded staleness, session, consistent prefix, or eventual) and multi-region writes for active-active architectures, ensuring data sovereignty and low-latency access worldwide. Azure Cosmos DB guarantees 99.999% high availability via a comprehensive SLA, enterprise-grade security features like customer-managed keys, private endpoints, and compliance with standards such as GDPR, HIPAA, and ISO 27001, and integrates with Azure AI services for vector search and generative AI applications.[1] Notably, it powers high-scale workloads for organizations like OpenAI, supporting the reliability and scalability of applications such as ChatGPT.[3] Recent enhancements include serverless throughput options for cost efficiency and the general availability of Cosmos DB in Microsoft Fabric, announced in November 2025, extending its capabilities to data analytics workflows.[4]History 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.[2] 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.[2] 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.[5] 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.[6][7] 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.[8] 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.[9] 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.[10][11] 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.[12] 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.[13]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.[14] This high availability is maintained even during regional outages, ensuring business continuity without manual intervention.[14] 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.[15] Elastic scalability allows seamless adjustment of throughput and storage capacity without downtime, supporting instant scaling to meet varying workloads.[16] 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.[16] 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.[17] 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.[18] 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.[16]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.[19] Accounts are created and managed through the Azure portal, Resource Manager templates, PowerShell, CLI, SDKs, or REST API.[20] 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.[20][19] 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.[20][19][21] 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.[20][19]
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.[16] 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.[22] 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.[16] 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.[22] 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.[16] 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.[22] 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.[16] 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.[22] 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.[20] 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.[16] 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.[25] 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.[26] 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.[27] 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.[28] 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.[29] 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.[30]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.[24] 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.[31][32][31]
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.[33][34]
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](/page/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.[35][35][36]
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.[37][38]
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.[39][40][40]
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.[41]
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.[42][43][19]
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.[34]
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.[44]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.[21]
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.[21][19]
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.[21]
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.[21][45]
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.[21]