Azure Cosmos DB for MongoDB (4.0 server version): supported features and syntax

APPLIES TO: MongoDB

Azure Cosmos DB is Azure's multiple-regionally distributed multi-model database service. You can communicate with the Azure Cosmos DB for MongoDB using any of the open-source MongoDB client drivers. The Azure Cosmos DB for MongoDB enables the use of existing client drivers by adhering to the MongoDB wire protocol.

By using the Azure Cosmos DB for MongoDB, you can enjoy the benefits of the MongoDB you're used to, with all of the enterprise capabilities that Azure Cosmos DB provides: multiple-region distribution, automatic sharding, availability and latency guarantees, encryption at rest, backups, and much more.

The supported operators and any limitations or exceptions are listed below. Any client driver that understands these protocols should be able to connect to Azure Cosmos DB for MongoDB. When you create Azure Cosmos DB for MongoDB accounts, the 3.6+ versions of accounts have the endpoint in the format *.mongo.cosmos.azure.cn whereas the 3.2 version of accounts has the endpoint in the format *.documents.azure.cn.

Azure Cosmos DB for MongoDB provides comprehensive support for MongoDB query language constructs. Below you can find the detailed list of currently supported operations, operators, stages, commands, and options.

Azure Cosmos DB for MongoDB supports the following database commands:

Azure Cosmos DB for MongoDB supports documents encoded in MongoDB BSON format. The 4.0 API version enhances the internal usage of this format to improve performance and reduce costs. Documents written or updated through an endpoint running 4.0+ benefit from optimization.

In an upgrade scenario, documents written prior to the upgrade to version 4.0+ won't benefit from the enhanced performance until they're updated via a write operation through the 4.0+ endpoint.

16-MB document support raises the size limit for your documents from 2 MB to 16 MB. This limit only applies to collections created after this feature has been enabled. Once this feature is enabled for your database account, it can't be disabled.

Enabling 16 MB can be done in the features tab in the Azure portal or programmatically by adding the "EnableMongo16MBDocumentSupport" capability.

We recommend enabling Server Side Retry and avoiding wildcard indexes to ensure requests with larger documents succeed. If necessary, raising your DB/Collection RUs may also help performance.

In the $regex queries, left-anchored expressions allow index search. However, using 'i' modifier (case-insensitivity) and 'm' modifier (multiline) causes the collection scan in all expressions.

When there's a need to include '$' or '|', it's best to create two (or more) regex queries. For example, given the following original query: find({x:{$regex: /^abc$/}), it has to be modified as follows:

find({x:{$regex: /^abc/, x:{$regex:/^abc$/}})

The first part will use the index to restrict the search to those documents beginning with ^abc and the second part will match the exact entries. The bar operator '|' acts as an "or" function - the query find({x:{$regex: /^abc |^def/}) matches the documents in which field 'x' has values that begin with "abc" or "def". To utilize the index, it's recommended to break the query into two different queries joined by the $or operator: find( {$or : [{x: $regex: /^abc/}, {$regex: /^def/}] }).

When you use the findOneAndUpdate operation with API for MongoDB version 4.0, sort operations on a single field and multiple fields are supported. Sort operations on multiple fields were a limitation of previous wire protocols.

The API for MongoDB supports various indexes to enable sorting on multiple fields, improve query performance, and enforce uniqueness.

Azure Cosmos DB supports GridFS through any GridFS-compatible Mongo driver.

Azure Cosmos DB supports automatic, native replication at the lowest layers. This logic is extended out to achieve low-latency, multiple-region replication as well. Azure Cosmos DB doesn't support manual replication commands.

Retryable writes enable MongoDB drivers to automatically retry certain write operations if there was failure, but results in more stringent requirements for certain operations, which match MongoDB protocol requirements. With this feature enabled, update operations, including deletes, in sharded collections will require the shard key to be included in the query filter or update statement.

For example, with a sharded collection, sharded on key “country”: To delete all the documents with the field city = "Shanghai", the application will need to execute the operation for all shard key (country) values if Retryable writes are enabled.

• db.coll.deleteMany({"country": "China", "city": "Shanghai"}) - Success
• db.coll.deleteMany({"city": "Shanghai"}) - Fails with error ShardKeyNotFound(61)

To enable the feature, add the EnableMongoRetryableWrites capability to your database account. This feature can also be enabled in the features tab in the Azure portal.

Azure Cosmos DB supports automatic, server-side sharding. It manages shard creation, placement, and balancing automatically. Azure Cosmos DB doesn't support manual sharding commands, which means you don't have to invoke commands such as addShard, balancerStart, moveChunk etc. You only need to specify the shard key while creating the containers or querying the data.

Azure Cosmos DB doesn't yet support server-side sessions commands.

Azure Cosmos DB supports a time-to-live (TTL) based on the timestamp of the document. TTL can be enabled for collections from the Azure portal.

Multi-document transactions are supported within an unsharded collection. Multi-document transactions aren't supported across collections or in sharded collections. The timeout for transactions is a fixed 5 seconds.

Azure Cosmos DB doesn't yet support users and roles. However, Azure Cosmos DB supports Azure role-based access control (Azure RBAC) and read-write and read-only passwords/keys that can be obtained through the Azure portal (Connection String page).

Some applications rely on a Write Concern, which specifies the number of responses required during a write operation. Due to how Azure Cosmos DB handles replication in the background all writes are automatically Quorum by default. Any write concern specified by the client code is ignored. Learn more in Using consistency levels to maximize availability and performance.

• Learn how to use Studio 3T with Azure Cosmos DB for MongoDB.
• Learn how to use Robo 3T with Azure Cosmos DB for MongoDB.
• Explore MongoDB samples with Azure Cosmos DB for MongoDB.
• Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
  • If all you know is the number of vCores and servers in your existing database cluster, read about estimating request units using vCores or vCPUs
  • If you know typical request rates for your current database workload, read about estimating request units using Azure Cosmos DB capacity planner