Supported features and syntax in Azure Cosmos DB for MongoDB 5.0 server version

Azure Cosmos DB for MongoDB 5.0 enables you to use familiar MongoDB features with enterprise-grade capabilities such as global distribution, automatic sharding, and high availability. This article describes the supported features, syntax, and benefits of using Azure Cosmos DB for MongoDB 5.0.

Protocol support

The supported operators and any limitations or exceptions are listed in this article. 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+ version of accounts has an endpoint in the format *.mongo.cosmos.azure.com. The 3.2 version of accounts has an endpoint in the format *.documents.azure.com.

Query language support

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

Database commands

Azure Cosmos DB for MongoDB supports the following database commands.

Query and write operation commands

Transaction commands

Authentication commands

Administration commands

Diagnostics commands

Aggregation pipeline

Azure Cosmos DB for MongoDB supports the following aggregation commands.

Aggregation commands

Aggregation stages

Boolean expressions

Conversion expressions

Set expressions

Comparison expressions

Arithmetic expressions

Trigonometry expressions

String expressions

Text search operator

Array expressions

Variable operators

System variables

Literal operator

Date expressions

Conditional expressions

Data type operator

Accumulator expressions

Merge operator

Data types

Azure Cosmos DB for MongoDB supports documents that are encoded in MongoDB binary JSON (BSON) format. Versions 4.0 and later (4.0+) enhance the internal usage of this format to improve performance and reduce costs. Documents that are written or updated through an endpoint running 4.0+ benefit from this optimization.

In an upgrade scenario to version 4.0 or later, documents created before upgrading don't immediately benefit from the enhanced performance. To take advantage of the improvements, update these documents through a write operation using the 4.0 endpoint.

16-MB document support raises the size limit for documents from 2 MB to 16 MB. This limit applies only to collections created after enabling the feature. After you enable this feature for a database account, it can't be disabled.

To enable 16-MB document support, change the setting on the Features tab for the resource in the Azure portal or programmatically add the EnableMongo16MBDocumentSupport capability.

We recommend that you enable Server Side Retry and avoid using wildcard indexes to ensure that requests in larger documents succeed. Raising your database or collection request units might also help performance.

Indexes and index properties

Azure Cosmos DB for MongoDB supports the following index commands and index properties.

Indexes

Index properties

Operators

Azure Cosmos DB for MongoDB supports the following operators.

Logical operators

Element operators

Evaluation query operators

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

When there's a need to include $ or |, it's best to create two (or more) $regex queries.

For example, change the following original query:

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

To this query:

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

The first part of the modified query uses the index to restrict the search to documents that begin with ^abc. The second part of the query matches 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 use the index, break the query into two separate queries and join them with the $or operator: find({$or: [{x: {$regex: /^abc/}}, {x: {$regex: /^def/}}]}).

Array operators

Comment operator

Projection operators

Update operators

Field update operators

Array update operators

Update modifiers

Bitwise update operator

Geospatial operators

Sort operations

When you use the findOneAndUpdate operation, sort operations on a single field are supported. Sort operations on multiple fields aren't supported.

Indexing

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

Client-side field-level encryption

Client-level field encryption is a driver feature and works with Azure Cosmos DB for MongoDB. Explicit encryption, where the driver encrypts each field during write operations, is supported. Automatic encryption isn't supported. Explicit decryption and automatic decryption are supported.

The mongocryptd shouldn't be run because it isn't needed to perform any of the supported operations.

GridFS

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

Replication

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

Retryable writes

The retryable writes feature enables MongoDB drivers to automatically retry certain write operations. The feature results in more stringent requirements for certain operations, which match MongoDB protocol requirements. With this feature enabled, update operations, including deletes, in sharded collections require the shard key to be included in the query filter or update statement.

For example, with a sharded collection, sharded on key region: To delete all the documents with the field city = "NYC", the application needs to execute the operation for all shard key (region) values if Retryable writes are enabled.

• db.coll.deleteMany({"region": "USA", "city": "NYC"}) - Succeeds with message Success
• db.coll.deleteMany({"city": "NYC"}) - Fails with error ShardKeyNotFound(61)

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

Sharding

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

Sessions

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

Time to Live

Azure Cosmos DB provides a Time to Live (TTL) feature based on the document's time stamp. Enable TTL for a collection in the Azure portal.

Custom TTL

This feature lets you specify a custom TTL value on a single field within a collection. Documents expire based on the value of this field.

On a collection that has TTL enabled on a field:

• Acceptable types are the binary JSON (BSON) data type and numeric types (integer, long, or double), which are interpreted as a Unix millisecond time stamp to determine expiration.

• If the TTL field is an array, then the smallest element of the array that is of an acceptable type is considered for document expiry.

• If the TTL field is missing from a document, the document doesn’t expire.

• If the TTL field isn't an acceptable type, the document doesn't expire.

Limitations of a custom TTL

• Only one field in a collection can have a TTL set on it.

• With a custom TTL field set, the \_ts field can't be used for document expiration.

• You can't use the \_ts field in addition.

Configuration

You can enable a custom TTL by updating the EnableTtlOnCustomPath capability for the account. Learn how to configure capabilities.

Set up the TTL

To set up the TTL, run this command: db.coll.createIndex({"YOUR_CUSTOM_TTL_FIELD":1}, {expireAfterSeconds: 10})

Transactions

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.

Manage users and roles

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

Write concerns

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