Hubbry Logo
Cosmos DBCosmos DBMain
Open search
Cosmos DB
Community hub
Cosmos DB
logo
8 pages, 0 posts
0 subscribers
Be the first to start a discussion here.
Be the first to start a discussion here.
Cosmos DB
Cosmos DB
from Wikipedia
Azure Cosmos DB
DeveloperMicrosoft
Initial release2017; 8 years ago (2017)
Available inEnglish
TypeMulti-model database
Websitelearn.microsoft.com/en-us/azure/cosmos-db/introduction

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]
[edit]
Revisions and contributorsEdit on WikipediaRead on Wikipedia
from Grokipedia
Azure Cosmos DB is the Microsoft Azure equivalent to Amazon DynamoDB. It is a fully managed, globally distributed, multi-model database service developed by as part of the Azure cloud platform, offering seamless scalability, low-latency access, high availability, and support for multiple data models including document, key-value, graph, column-family, and vector data to enable modern application development. Microsoft provides official migration guidance and tools for transitioning applications and data from DynamoDB to Azure Cosmos DB. Launched in general availability on May 10, 2017, it evolved from the earlier Azure DocumentDB service and was announced at 2017 as the industry's first globally distributed, . 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 (SQL querying), compatibility with vCore and API for , , Apache Gremlin for graph data, Azure Table API for key-value, and Azure Cosmos DB for , 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 and low-latency access worldwide. Azure Cosmos DB guarantees 99.999% 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. Notably, it powers high-scale workloads for organizations like , supporting the reliability and scalability of applications such as . 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.

History and Overview

Development History

Azure Cosmos DB originated as Project Florence in 2010, an internal initiative designed to resolve scalability challenges encountered in large-scale applications, such as elastic scaling of throughput and storage to manage unpredictable workload spikes. This project addressed pain points in services requiring and global distribution, evolving through internal iterations to support 's own workloads before external release. The technology underlying Cosmos DB saw extensive internal deployment at for nearly a decade prior to its public launch, powering critical systems and refining its and distributed capabilities in production environments. On May 10, 2017, officially announced Azure Cosmos DB and made it generally available as a fully managed, globally distributed, service, building on the foundations of the earlier Azure DocumentDB while introducing turnkey global replication and multiple consistency models. 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. In 2023, Cosmos DB added vector search capabilities, initially for the vCore API, allowing efficient storage, indexing, and querying of high-dimensional vectors to support AI-driven applications. That same year, support for the 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 is no longer supported for new projects, with recommending alternatives such as Azure Database for . By 2025, Cosmos DB continued to advance with integrations to Microsoft Fabric and enhanced support for AI workloads, announced at in May, including automatic scaling optimizations tailored for generative AI scenarios. 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.

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 (SLA) for both reads and writes in multi-region configurations. This is maintained even during regional outages, ensuring business continuity without manual intervention. The service guarantees read latency under 10 ms and write latency under 15 ms at the 99th using direct connectivity, delivering low-latency performance worldwide. Elastic scalability allows seamless adjustment of throughput and storage capacity without , supporting instant scaling to meet varying workloads. Multi-model support accommodates diverse data types, including , key-value, graph, column-family, and vector models, without enforcing schemas for flexible storage and querying via multiple APIs. Built-in features encompass at rest and in transit, role-based access control (RBAC) via , and private endpoints for secure connectivity. 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. 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.

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 and containers. An account represents a unit of 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. Accounts are created and managed through the Azure portal, Resource Manager templates, , CLI, SDKs, or REST API. 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 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 but are not applicable in the . Containers represent the core scalable units for and operations in Cosmos DB, holding items and supporting horizontal scaling through partitioning. Each container requires a partition key to distribute 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 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. 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 , or vertices/edges in . Each item must have a unique id (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 by tagging resource versions. Items support standard CRUD operations (create, read, update, delete, upsert) across all APIs.

Multi-model Support

Azure Cosmos DB provides multi-model support by natively accommodating various 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. This capability is enabled through compatibility with multiple open-source APIs, each tailored to specific paradigms, while leveraging a shared infrastructure for storage and operations. The service supports a document model using JSON-like structures for handling , primarily via the for , which stores items as flexible, hierarchical documents. For simple, high-performance lookups, it offers a key-value model through the Table , where data is stored and retrieved using unique keys without complex querying needs. The column-family model, suited for wide-column stores and analytical workloads, is provided by the , enabling efficient handling of sparse, multidimensional data. In addition, the graph model represents interconnected data as vertices and edges, supported by the for traversing relationships in social networks, recommendation engines, or detection systems. Cosmos DB also extends compatibility to MongoDB's BSON documents via the (in both request unit and vCore modes), preserving the binary format for document-oriented applications, and to PostgreSQL's relational structures through the , allowing SQL-based relational modeling with transactions; as of November 2025, the is no longer supported for new projects, though existing deployments remain supported—Microsoft recommends Azure Database for Flexible Server for new relational workloads. For the NoSQL-compatible APIs (NoSQL, , , , and Table), Cosmos DB employs a unified storage built on an atoms-records-sequences (ARS) , which abstracts the underlying storage to diverse models seamlessly without requiring separate physical . The API, however, uses a separate distributed based on Citus and native storage. This enables developers to choose and switch among the NoSQL-compatible APIs per —units within the resource hierarchy that hold model-specific items—without , as the same can be accessed via different APIs by adjusting the client configuration. For instance, a provisioned for the NoSQL API stores JSON items, while one for stores rows, yet both reside in the same account and share global distribution features. The API follows a distinct resource model with clusters, , schemas, and distributed tables. The following table illustrates how containers adapt to different models by defining the entity types for data storage:
APIContainer EntityData Entity
for NoSQLItem (JSON)
for CassandraTableRow
for MongoDBCollection (BSON)
for GremlinGraphNode or Edge
for TableTableItem (key-value)
for PostgreSQLTableRow (relational)
Cosmos DB's schema-agnostic approach further enhances flexibility, permitting mixed data types and evolving schemas within the same container, as all data is automatically indexed regardless of structure to support fast queries and development agility. This design is particularly beneficial for scenarios, where applications require multiple data models to coexist efficiently.

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 stored as documents in . 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 , 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. Indexing policies in the Core (SQL) API ensure efficient query performance by default applying range indexing to all paths in documents, which supports equality, range, and order-by queries on strings and numbers. This default automatically indexes every 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 . Server-side programmability in the Core (SQL) API allows execution of JavaScript-based stored procedures, triggers, and user-defined functions (UDFs) to encapsulate within the database. Stored procedures enable transactional operations across multiple items in a single partition, such as bulk imports or updates, ensuring atomicity via . 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. 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. 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 API responses, with index metrics specifically highlighting utilized versus missing indexes for query improvement. Geospatial queries in the Core (SQL) API support data types, including Point, LineString, , 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 or intersecting regions. Indexing for geospatial data is handled via the container's policy, with spatial indexes automatically applied to paths to ensure efficient query resolution without full scans.

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 , API for , API for , 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 stores, wide-column stores, graph databases, and key-value systems, all mapped to a shared resource model of databases, containers, and items. The API for 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 , automatic sharding for horizontal scaling across partitions, and replica sets for 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. Migration from open-source to the for typically involves no application code changes due to 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 or 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. The API for serves as a for Apache Cassandra versions 3.0 and later, supporting the Cassandra Query Language (CQL) v3.11 with to v2.x, and integrating seamlessly with existing Cassandra client drivers via the CQL Binary Protocol v4. It enables wide-column 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 —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. For migration from , 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 enable bulk data movement, with post-migration adjustments primarily for throughput provisioning to match Cassandra's defaults. The API for Apache provides 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 and , using for optimized performance in distributed environments, and integrates with open-source Gremlin SDKs via support. Key features include automatic indexing of graph elements and compatibility with graph analytics tools, though it diverges from pure TinkerPop in traversal to prioritize . 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. 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 query syntax due to protocol compatibility; this path supports gradual cutover by running parallel traversals during data sync. 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 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 support in .NET, enabling efficient lookups on 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 to maintain performance, distinct from MongoDB's larger document allowance. 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.

PostgreSQL API

Azure Cosmos DB for provided a distributed service compatible with , supporting standard SQL queries and extensions like Citus for horizontal scaling across nodes. It allowed developers to use familiar tools, drivers, and applications for relational workloads with Cosmos DB's global distribution and scalability. As of October 2025, Azure Cosmos DB for is no longer supported for new projects; existing deployments continue, but recommends migrating to Azure Database for flexible server or Azure SQL Database for new relational applications.

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 property path defined when creating a , 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. Physical partitions are the underlying storage units managed by Azure Cosmos DB, each capable of holding up to 50 GB of 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 and . Each logical partition itself is limited to 20 GB of storage and 10,000 RU/s, preventing any single partition from becoming a bottleneck. Selecting an effective partition key is crucial for optimal performance and involves choosing a property with high 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 orders distributes load evenly if activity is balanced, while avoiding low- keys like /region that could concentrate data in few partitions. 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. Throughput provisioned to a is distributed evenly across physical partitions, with each logical partition capped at 10,000 RU/s to enforce balanced scaling.

Throughput Provisioning Models

Azure Cosmos DB uses Request Units (RUs) as a normalized measure of throughput, representing the resources required for read and write operations regardless of the underlying such as CPU, , and . For example, a point read of a 1 KB item costs 1 RU, while costs for indexed reads and writes vary based on item size, indexing policies, and query complexity. In the provisioned throughput model, users allocate a fixed amount of RU/s to either databases or containers, ensuring predictable performance for steady workloads. Throughput can be provisioned at the database level, where it is shared across up to 25 containers without per-container guarantees, or at the container level for dedicated allocation. This model supports two variants: standard (manual) throughput, which maintains a fixed RU/s rate (minimum 400 RU/s), and autoscale throughput, which automatically scales between 10% and 100% of a defined maximum RU/s (up to 10x the base), making it suitable for workloads with variable demand. Provisioned throughput is billed hourly based on the allocated or highest scaled RU/s, providing cost efficiency for consistent, high-volume applications. Serverless mode offers an alternative by eliminating upfront provisioning, charging only for RUs consumed per request, which is ideal for bursty, unpredictable, or low-traffic workloads such as development, testing, or sporadic usage. In this mode, operations are limited to a maximum of 5,000 RU/s per request, with billing at the end of the period (e.g., approximately $0.25 per million RUs). Unlike provisioned throughput, serverless does not support multi-region distribution and is more cost-effective when average traffic is below 10% of peak. RU consumption follows deterministic formulas: point reads cost 1 RU per KB, indexed reads vary with the number of properties and index coverage (e.g., up to 10+ RUs for complex queries), and writes typically cost 5-10 RUs per KB depending on storage overhead. Throughput limits include a maximum of 1,000,000 RU/s per container or database (increasable via support), with no more than 10,000 RU/s per logical partition to ensure even distribution. For shared database provisioning, the total RU/s applies across all containers, potentially requiring careful workload balancing. Overall, provisioned throughput suits steady, production loads with reserved capacity, while serverless minimizes costs for intermittent access without idle-time charges.

Global Distribution

Multi-region Replication

Azure Cosmos DB provides multi-region replication to distribute globally across Azure regions, ensuring low-latency access for applications serving users worldwide. This feature automatically replicates to all regions associated with the account, supporting both single-write and multi-write configurations. In single-write setups, one region handles all writes while others serve reads; multi-write mode enables active-active replication where multiple regions accept writes. Replication occurs synchronously within a local region to a of replicas for , followed by asynchronous propagation to other regions. This approach balances and , with writes acknowledging after local commitment while background processes sync changes across regions. In multi-master configurations, any writable region can process writes, distributing load and reducing latency for global users; enabling this involves adding regions via the Azure portal and activating multi-region writes, which can be done without . In multi-region write accounts, use Session, Consistent Prefix, or for optimal , as and Bounded Staleness have limitations. When concurrent writes to the same item occur across regions, conflicts are resolved using built-in policies. The default last-writer-wins mechanism uses timestamps to determine the prevailing version, while custom handlers allow applications to define resolution logic, such as merging or selecting based on business rules. Read regions operate independently, enabling targeted placement for optimal access speeds without affecting write locations. Failover and recovery mechanisms include manual intervention or automatic service-managed failover during outages. For strong consistency, the recovery point objective (RPO) is effectively zero, as operations commit only after quorum acknowledgment across replicas. Accounts support adding multiple regions—up to the number available in Azure—for linear throughput scaling; each additional write region multiplies the effective write capacity proportionally to provisioned request units per second (RU/s).

Tunable Consistency Models

Azure Cosmos DB provides five tunable consistency levels for read operations, allowing developers to balance data freshness, performance, and availability based on application needs. These levels—Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual—are configurable at the account level or overridden per request, with Session as the default. This tunability is enabled by Cosmos DB's multi-region replication, which supports varied quorum requirements across replicas. consistency is available only for single-region write accounts. Strong consistency offers , ensuring reads always return the most recent committed version of an item with full guarantees, including no dirty reads, non-repeatable reads, or phantom reads. It requires a global majority for writes and a local minority for reads, resulting in the highest latency (approximately twice the round-trip time plus 10 ms at the 99th for writes) and reduced during network partitions. Performance-wise, it consumes more request units (RUs), roughly twice as many for reads compared to weaker levels, due to minority reads. Bounded Staleness provides a form of session-like consistency with bounded lag, guaranteeing monotonic reads and writes where data is no older than a specified number of versions (minimum K=10 for single-region accounts) of an item or a time interval (minimum T=5 seconds), with higher minima for multi-region accounts (K=100,000, T=300 seconds). Bounded Staleness is not recommended for multi-region write configurations. It ensures reads reflect the newest committed writes within the staleness bounds and supports consistent prefix reads within the region. This level uses minority reads and local majority writes, offering near-strong consistency but with higher RU consumption for reads (about twice that of eventual) and potential write throttling if lag exceeds limits. Latency is higher than weaker levels but lower than Strong. Session consistency ensures monotonic reads and monotonic writes within a client session, identified by a session token, making it ideal for user-specific sessions where read-your-writes and write-follows-reads semantics are needed. It prevents reading intermediate or uncommitted states across session operations but allows different sessions to see different views. This level achieves low latency (under 10 ms at the 99th for reads) and using single-replica reads and local majority writes, with efficient RU usage similar to weaker levels. Session tokens must be managed by the application to maintain consistency across requests. Consistent Prefix guarantees that reads never see writes from aborted transactions or "tombstones" (deleted items), preserving a partial order where updates appear in the order they were committed, especially for transactional batches. It does not provide monotonicity or bounded staleness but avoids out-of-order reads for single-item operations under . With single-replica reads and local majority writes, it offers low latency and high throughput, consuming fewer RUs than Strong or Bounded Staleness. Eventual consistency provides the weakest guarantees, with no ordering or monotonicity, where replicas may return stale data that eventually converges without bounds on freshness. It supports the highest and lowest latency (under 10 ms at the 99th for reads) using single-replica reads and local majority writes, resulting in the lowest RU consumption for reads. This level is suitable for scenarios where occasional staleness is acceptable, such as non-critical caches. The default consistency level is Session, set at the account level and applying to all operations unless overridden for individual read requests via SDK headers or parameters; changes to the default require application redeployment. and Bounded Staleness incur higher RU costs for reads due to stricter quorums, while Session, Consistent Prefix, and Eventual optimize for speed and cost efficiency.

Advanced Capabilities

Analytical Store

The Azure Cosmos DB analytical store is a fully managed, isolated columnar designed to enable hybrid transactional and analytical processing (HTAP) directly on operational data without requiring (ETL) pipelines or data movement. Integrated via Azure Link, it allows organizations to perform large-scale analytics on the same dataset used for real-time transactions, ensuring performance isolation between operational and analytical workloads. This capability supports APIs such as , , and (in preview), with data automatically synchronized in a one-way manner from the row-oriented transactional store to the analytical store. The synchronization process exports changes continuously and automatically to the analytical store in format, a columnar storage optimized for compression and query performance, resulting in a significantly smaller storage footprint compared to the transactional store due to the columnar compression in format. This near real-time export leverages change detection mechanisms to capture inserts, updates, and deletes with low latency, typically making data available for within minutes. Users can query the analytical store using for distributed processing or T-SQL via serverless SQL pools in Azure , facilitating complex aggregations, joins, and historical analysis on operational data without impacting application performance. Retention in the analytical store is governed by the Analytical Time-to-Live (ATTL) property, configurable at the container level with a default value of -1 indicating infinite retention; setting a positive value in seconds enforces automatic expiration of beyond that period, with storage costs applying based on the retained volume. The analytical store preserves time-to-live (TTL) settings from the transactional store, ensuring that expired items are removed from both stores to maintain consistency. It also handles schema evolution seamlessly, accommodating changes in structure over time without requiring manual interventions or breaking existing queries, thanks to its schema-agnostic design that infers and adapts to evolving documents. As of July 2025, in public preview, the analytical store integrates with Fabric through a feature, enabling zero-ETL replication of Cosmos DB data directly into Fabric's OneLake for unified across lakehouse, warehouse, and real-time intelligence workloads. This integration extends Synapse Link capabilities within Fabric, allowing seamless access to operational data for advanced while maintaining and security.

Vector Search and Change Feed

Azure Cosmos DB provides built-in vector search capabilities designed for handling high-dimensional vectors in AI-driven applications. This feature enables efficient indexing and querying of vector embeddings, supporting up to 4,096 dimensions using algorithms such as DiskANN, a Microsoft Research-developed approximate nearest neighbor index that optimizes for low-latency searches on large-scale datasets. DiskANN facilitates disk-based storage and retrieval, reducing compute overhead by up to 95% compared to traditional in-memory methods while maintaining high recall rates for similarity searches. Vector search in Cosmos DB supports hybrid queries that combine k-nearest neighbors (kNN) algorithms with , allowing developers to filter results using structured queries alongside based on metrics like , , or . This integration enhances applications in generative AI by storing embeddings directly within documents, enabling over such as text or images. Cosmos DB integrates natively with Azure for generating these embeddings, streamlining workflows for retrieval-augmented generation (RAG) scenarios where relevant context is fetched to inform AI models. The Change Feed in Azure Cosmos DB serves as a time-ordered, persistent log capturing all changes to items in a container, including inserts, updates, and deletes, processed in the exact sequence they occur to ensure reliable event ordering. This feed can be consumed through various mechanisms, such as the Cosmos DB SDK for custom applications, Azure Functions for serverless event handling, or for distributed processing in analytics pipelines. To support distributed consumers, the Change Feed Processor library manages leases on feed progress, enabling multiple instances to share workload without duplication or loss, with configurable parallelism based on logical partitions. Consumers can filter the feed starting from a specific sequence number, allowing resumption from a known point in the change history for fault-tolerant processing. Reactive triggers in Azure Functions automatically invoke code on new changes, facilitating real-time serverless architectures for tasks like or notifications. Announced on July 14, 2025, as part of the public preview of in Fabric, enhancements to vector search include improved DiskANN indexing for scalable deployments and deeper integration with pipelines via for version-controlled management of vector indexes. These updates also expanded hybrid search to incorporate full-text scoring models like BM25 alongside vector kNN, boosting in mixed-query scenarios for AI applications.

Materialized Views

Materialized views in Azure Cosmos DB enable the creation of pre-computed, query-optimized views of data to enhance performance for complex queries. The feature employs a pull-based model that automatically keeps views synchronized with the source container without impacting write performance on the source. A dedicated materialized views builder, hosted on the gateway, manages the synchronization process, ensuring efficient updates through a separate compute layer. This approach supports APIs such as NoSQL and Cassandra, allowing developers to define views based on query patterns for faster read operations while maintaining data consistency.

Monitoring and Use Cases

Diagnostics and Tools

Azure Cosmos DB provides a suite of built-in diagnostics and tools to facilitate , , and , enabling developers to monitor resource utilization, query efficiency, and operational health without external dependencies. These tools integrate seamlessly with the Azure portal and SDKs, offering granular insights into request processing and system behavior to optimize workloads and troubleshoot issues proactively. Query metrics deliver a detailed per-query breakdown, including Request Unit (RU) consumption, execution time, and index utilization, accessible directly through the Azure portal or via SDK methods such as ServerSideCumulativeMetrics in the .NET SDK. This allows users to analyze query performance at both aggregate and partitioned levels, identifying bottlenecks like inefficient indexing or suboptimal query patterns that impact RU usage in provisioned throughput models. Diagnostics logs capture comprehensive data on requests, errors, and resource metrics, with native integration into Azure Monitor for real-time and historical analysis. By enabling diagnostic settings, users can route these logs to storage accounts, event hubs, or directly to Azure Monitor Logs, providing visibility into data plane operations such as activities. As of June 2025, diagnostics logging has been enhanced for Azure Cosmos DB for MongoDB vCore, supporting advanced querying via Azure Monitor Log Analytics. The Capacity Planner serves as a predictive tool for estimating required RU throughput based on workload characteristics, including document size, read/write ratios, and query complexity, helping to provision cost-effective resources. Available in the Azure portal, it simulates scenarios to forecast RU/s needs and associated costs, supporting informed scaling decisions for various models like or . Early profiling capabilities in Cosmos DB have evolved, with the legacy profiler tool largely supplanted by modern Azure Cosmos DB Insights in the Azure portal, which highlight query hot spots, latency trends, and failure patterns through interactive visualizations. These insights consolidate metrics from multiple sources, offering a unified for debugging performance anomalies without requiring SDK instrumentation. Alerting mechanisms within Azure Monitor enable proactive notifications for key metrics such as throughput utilization, request latency, and failure rates, configured via metric-based rules in the Azure portal. Users can define thresholds for conditions like high RU consumption or availability drops, triggering actions such as email notifications or automated remediation through Azure Logic Apps. For advanced analysis, diagnostics logs can be exported to Log Analytics workspaces, where Kusto Query Language (KQL) enables complex querying of operational data, including filtering by request type, status codes, or geographic regions. This integration supports custom dashboards and long-term retention, enhancing for large-scale deployments. The Azure Cosmos DB Extension for Visual Studio Code (VS Code) enables developers to connect directly to Cosmos DB accounts, query data, and edit NoSQL documents within the VS Code environment, eliminating the need to switch tools during development and debugging workflows.

Real-world Applications

Cosmos DB has been widely adopted in the gaming industry for managing high-throughput workloads such as leaderboards and player profiles. Microsoft's Xbox services leverage Cosmos DB to handle real-time updates for multiplayer games, supporting millions of writes per second during peak events like global tournaments. This capability ensures low-latency access to player statistics and session data, enabling seamless experiences for millions of concurrent users across distributed regions, facilitated by Cosmos DB's global distribution features. In the retail sector, Cosmos DB powers platforms by storing dynamic catalogs and enabling personalized recommendations. It supports rapid querying of and behavior data, helping businesses handle seasonal spikes in traffic without performance degradation, as demonstrated in various retail workloads. For (IoT) applications, Cosmos DB excels in ingesting and processing data from connected devices. It facilitates event logging for vehicle fleets and smart sensors, where high-velocity streams of location, sensor readings, and diagnostics are stored and analyzed in real time. Automotive companies use this for and route optimization, accommodating billions of events daily through automatic scaling. Social media platforms utilize Cosmos DB for handling and dynamic feeds. LinkedIn employs it to store and retrieve profiles, posts, and connections, supporting personalized newsfeeds for over a billion users with consistent low-latency access worldwide. The database's multi-model support allows efficient modeling of graph-like relationships, such as social graphs, ensuring reliable delivery of real-time notifications and content updates. In artificial intelligence applications, Cosmos DB serves as a vector store for retrieval-augmented generation (RAG) in chatbots and generative AI tools. Demonstrations at Microsoft Build 2025 showcased its vector search capabilities for embedding storage and similarity queries, enabling context-aware responses in enterprise AI scenarios like knowledge retrieval systems. This integration with Azure AI services supports scalable RAG pipelines, improving accuracy in applications from customer support bots to content generation. As of April 2025, real-world AI use cases were highlighted at Azure Cosmos DB Conf, including change feed for real-time AI apps. Financial services firms apply Cosmos DB for real-time fraud detection, processing transaction streams with sub-millisecond query latencies. It stores payment events and user patterns, allowing machine learning models to flag anomalies instantly during high-volume operations like online banking. This approach enhances security by correlating global transaction data across regions for comprehensive risk assessment. As of 2025, over 3,600 companies across industries, including finance, utilize Cosmos DB for mission-critical workloads.

Limitations and Considerations

Performance Constraints

Azure Cosmos DB imposes a maximum size limit of 2 MB per item, measured as the length of its representation, to ensure efficient storage and query performance across its distributed architecture. This constraint applies uniformly to documents in the API, preventing oversized items that could degrade replication and indexing processes. Transactions in Azure Cosmos DB are strictly limited to operations within a single logical partition, providing full compliance with snapshot isolation for reads and writes confined to that scope. Multi-item transactions, such as those executed via stored procedures or triggers, must involve items sharing the same partition key; attempts to span multiple logical partitions require client-side coordination, as native support for distributed transactions across partitions is not available. This design prioritizes consistency within partitions while leveraging horizontal scaling for overall throughput. Azure Cosmos DB does not support native joins across partitions, necessitating data denormalization or application-level logic to assemble related information from multiple documents or containers. Similarly, there is no enforcement of complex relationships or foreign keys, as the service lacks constraints; instead, it favors related within documents to minimize query latency, though referencing patterns can be used for frequently updated or unbounded relationships at the cost of additional read operations. These approaches encourage denormalized models to optimize performance in a distributed environment. Throughput in Azure Cosmos DB is constrained by the capacity of physical partitions, each of which can handle up to 10,000 request units per second (RU/s), effectively capping throughput based on the number of partitions allocated—typically allowing up to 100,000 RU/s for a with 10 physical partitions, though higher scales are possible with more partitions and no strict account-level upper limit beyond practical distribution. Accounts can provision up to 1 million RU/s or more, but exceeding default thresholds may require support requests to adjust quotas. In serverless mode, additional constraints apply, including a maximum of 20,000 RU/s per and lack of support for features such as multi-region writes. By default, Azure Cosmos DB indexes all property paths in items using an structure, which incurs additional overhead on write operations as each property must be processed and stored in the index. This automatic indexing enhances query efficiency for range scans and lookups but can increase request unit consumption for inserts and updates, particularly in documents with many or complex properties; custom indexing policies allow exclusion of unused paths to mitigate this impact. Partitioning strategies can help distribute these loads evenly, reducing hotspots and enabling higher overall performance within the defined constraints.

Cost and Best Practices

Azure Cosmos DB employs a consumption-based pricing model centered on Request Units (RUs), which measure the computational resources required for database operations, along with separate charges for storage and data transfer. For provisioned throughput, users are billed at $0.008 per 100 RU/s per hour for standard configurations, with autoscale options offering equivalent monthly rates such as $5.84 per 100 RU/s per month for general-purpose workloads in a single region. In serverless mode, suitable for intermittent workloads, billing occurs per request at $0.25 per 1,000,000 RUs consumed, without minimum commitments. Storage is charged at $0.25 per GB per month for transactional data across replicated regions, while analytical storage costs $0.03 per GB per month; a free tier provides 1,000 RU/s and 25 GB of storage monthly for one account per subscription. To optimize costs, developers should select partition keys that distribute data and workload evenly, preventing hotspots that lead to inefficient RU consumption and potential throttling. Point reads, which retrieve a single item by its ID and partition key, consume minimal RUs—typically 1 RU for a 1 KB item—and are preferable over queries for known items. Enabling (TTL) on items automates cleanup of expired data, reducing storage charges without manual intervention. Denormalizing data to align with common query patterns minimizes cross-partition operations, which can increase RU usage, while customizing indexing policies excludes unnecessary paths to lower both storage and query costs. Best practices include continuous monitoring of RU consumption via Azure Monitor to identify over-provisioning, where unused throughput results in wasted expenditure, and scaling provisioned RU/s dynamically to match workload patterns. Selecting consistency levels per operation—such as for reads to halve RU costs compared to —balances performance and expense without compromising application needs. For multi-tenant applications, allocating dedicated throughput to individual tenants or using logical partitioning isolates resource usage, avoiding interference and enabling precise cost attribution. Common pitfalls involve hot partitions, where uneven data distribution concentrates requests on few partitions, inflating RU demands and triggering throttling that indirectly raises costs through retries. Over-provisioning throughput beyond actual needs leads to unnecessary hourly charges, while neglecting to optimize queries can multiply RU usage for complex operations. In 2025, integrations like autoscale throughput in Fabric (in preview as of July 2025) enable automatic scaling for lakehouse workloads by provisioning resources only during active use, enhancing cost efficiency for variable patterns compared to fixed provisioning.

References

Add your contribution
Related Hubs
User Avatar
No comments yet.