Azure Cosmos DB API for MongoDB (4.2 server version): supported features and syntax
Article
9 minutes to read
APPLIES TO:
Azure Cosmos DB API for MongoDB
Azure Cosmos DB is Microsoft's globally distributed multi-model database service, offering multiple database APIs. You can communicate with the Azure Cosmos DB API for MongoDB using any of the open-source MongoDB client drivers. The Azure Cosmos DB API for MongoDB enables the use of existing client drivers by adhering to the MongoDB wire protocol.
By using the Azure Cosmos DB API for MongoDB, you can enjoy the benefits of the MongoDB you're used to, with all of the enterprise capabilities that Cosmos DB provides: global distribution, automatic sharding, availability and latency guarantees, encryption at rest, backups, and much more.
Protocol Support
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 API for MongoDB. When using Azure Cosmos DB API for MongoDB accounts, the 3.6+ versions of accounts have the endpoint in the format *.mongo.cosmos.azure.com whereas the 3.2 version of accounts has the endpoint in the format *.documents.azure.com.
Note
This article only lists the supported server commands, and excludes client-side wrapper functions. Client-side wrapper functions such as deleteMany() and updateMany() internally utilize the delete() and update() server commands. Functions utilizing supported server commands are compatible with the Azure Cosmos DB API for MongoDB.
Query language support
Azure Cosmos DB API 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.
Database commands
Azure Cosmos DB API for MongoDB supports the following database commands:
Multi-document transactions are only supported within a single non-sharded collection. Cross-collection and cross-shard multi-document transactions are not yet supported in the API for MongoDB.
Command
Supported
abortTransaction
Yes
commitTransaction
Yes
Authentication commands
Command
Supported
authenticate
Yes
getnonce
Yes
logout
Yes
Administration commands
Command
Supported
cloneCollectionAsCapped
No
collMod
No
connectionStatus
No
convertToCapped
No
copydb
No
create
Yes
createIndexes
Yes
currentOp
Yes
drop
Yes
dropDatabase
Yes
dropIndexes
Yes
filemd5
Yes
killCursors
Yes
killOp
No
listCollections
Yes
listDatabases
Yes
listIndexes
Yes
reIndex
Yes
renameCollection
No
Diagnostics commands
Command
Supported
buildInfo
Yes
collStats
Yes
connPoolStats
No
connectionStatus
No
dataSize
No
dbHash
No
dbStats
Yes
explain
Yes
features
No
hostInfo
Yes
listDatabases
Yes
listCommands
No
profiler
No
serverStatus
No
top
No
whatsmyuri
Yes
Aggregation pipeline
Aggregation commands
Command
Supported
aggregate
Yes
count
Yes
distinct
Yes
mapReduce
No
Aggregation stages
Command
Supported
$addFields
Yes
$bucket
No
$bucketAuto
No
$changeStream
Yes
$collStats
No
$count
Yes
$currentOp
No
$facet
Yes
$geoNear
Yes
$graphLookup
Yes
$group
Yes
$indexStats
No
$limit
Yes
$listLocalSessions
No
$listSessions
No
$lookup
Partial
$match
Yes
$merge
Yes
$out
Yes
$planCacheStats
Yes
$project
Yes
$redact
Yes
$regexFind
Yes
$regexFindAll
Yes
$regexMatch
Yes
$replaceRoot
Yes
$replaceWith
Yes
$sample
Yes
$set
Yes
$skip
Yes
$sort
Yes
$sortByCount
Yes
$unset
Yes
$unwind
Yes
Note
The $lookup aggregation does not yet support the uncorrelated subqueries feature introduced in server version 3.6. You will receive an error with a message containing let is not supported if you attempt to use the $lookup operator with let and pipeline fields.
Boolean expressions
Command
Supported
$and
Yes
$not
Yes
$or
Yes
Conversion expressions
Command
Supported
$convert
Yes
$toBool
Yes
$toDate
Yes
$toDecimal
Yes
$toDouble
Yes
$toInt
Yes
$toLong
Yes
$toObjectId
Yes
$toString
Yes
Set expressions
Command
Supported
$setEquals
Yes
$setIntersection
Yes
$setUnion
Yes
$setDifference
Yes
$setIsSubset
Yes
$anyElementTrue
Yes
$allElementsTrue
Yes
Comparison expressions
Note
The API for MongoDB does not support comparison expressions with an array literal in the query.
Command
Supported
$cmp
Yes
$eq
Yes
$gt
Yes
$gte
Yes
$lt
Yes
$lte
Yes
$ne
Yes
$in
Yes
$nin
Yes
Arithmetic expressions
Command
Supported
$abs
Yes
$add
Yes
$ceil
Yes
$divide
Yes
$exp
Yes
$floor
Yes
$ln
Yes
$log
Yes
$log10
Yes
$mod
Yes
$multiply
Yes
$pow
Yes
$round
Yes
$sqrt
Yes
$subtract
Yes
$trunc
Yes
Trigonometry expressions
Command
Supported
$acos
Yes
$acosh
Yes
$asin
Yes
$asinh
Yes
$atan
Yes
$atan2
Yes
$atanh
Yes
$cos
Yes
$cosh
Yes
$degreesToRadians
Yes
$radiansToDegrees
Yes
$sin
Yes
$sinh
Yes
$tan
Yes
$tanh
Yes
String expressions
Command
Supported
$concat
Yes
$indexOfBytes
Yes
$indexOfCP
Yes
$ltrim
Yes
$rtrim
Yes
$trim
Yes
$split
Yes
$strLenBytes
Yes
$strLenCP
Yes
$strcasecmp
Yes
$substr
Yes
$substrBytes
Yes
$substrCP
Yes
$toLower
Yes
$toUpper
Yes
Text search operator
Command
Supported
$meta
No
Array expressions
Command
Supported
$arrayElemAt
Yes
$arrayToObject
Yes
$concatArrays
Yes
$filter
Yes
$indexOfArray
Yes
$isArray
Yes
$objectToArray
Yes
$range
Yes
$reverseArray
Yes
$reduce
Yes
$size
Yes
$slice
Yes
$zip
Yes
$in
Yes
Variable operators
Command
Supported
$map
Yes
$let
Yes
System variables
Command
Supported
$$CLUSTERTIME
Yes
$$CURRENT
Yes
$$DESCEND
Yes
$$KEEP
Yes
$$NOW
Yes
$$PRUNE
Yes
$$REMOVE
Yes
$$ROOT
Yes
Literal operator
Command
Supported
$literal
Yes
Date expressions
Command
Supported
$dayOfYear
Yes
$dayOfMonth
Yes
$dayOfWeek
Yes
$year
Yes
$month
Yes
$week
Yes
$hour
Yes
$minute
Yes
$second
Yes
$millisecond
Yes
$dateToString
Yes
$isoDayOfWeek
Yes
$isoWeek
Yes
$dateFromParts
Yes
$dateToParts
Yes
$dateFromString
Yes
$isoWeekYear
Yes
Conditional expressions
Command
Supported
$cond
Yes
$ifNull
Yes
$switch
Yes
Data type operator
Command
Supported
$type
Yes
Accumulator expressions
Command
Supported
$sum
Yes
$avg
Yes
$first
Yes
$last
Yes
$max
Yes
$min
Yes
$push
Yes
$addToSet
Yes
$stdDevPop
Yes
$stdDevSamp
Yes
Merge operator
Command
Supported
$mergeObjects
Yes
Data types
Azure Cosmos DB API for MongoDB supports documents encoded in MongoDB BSON format. The 4.2 API version enhances the internal usage of this format to improve performance and reduce costs. Documents written or updated through an endpoint running 4.2 benefit from this.
In an upgrade scenario, documents written prior to the upgrade to version 4.2 will not benefit from the enhanced performance until they are updated via a write operation through the 4.2 endpoint.
Command
Supported
Double
Yes
String
Yes
Object
Yes
Array
Yes
Binary Data
Yes
ObjectId
Yes
Boolean
Yes
Date
Yes
Null
Yes
32-bit Integer (int)
Yes
Timestamp
Yes
64-bit Integer (long)
Yes
MinKey
Yes
MaxKey
Yes
Decimal128
Yes
Regular Expression
Yes
JavaScript
Yes
JavaScript (with scope)
Yes
Undefined
Yes
Indexes and index properties
Indexes
Command
Supported
Single Field Index
Yes
Compound Index
Yes
Multikey Index
Yes
Text Index
No
2dsphere
Yes
2d Index
No
Hashed Index
Yes
Index properties
Command
Supported
TTL
Yes
Unique
Yes
Partial
Only supported with unique indexes
Case Insensitive
No
Sparse
No
Background
Yes
Operators
Logical operators
Command
Supported
$or
Yes
$and
Yes
$not
Yes
$nor
Yes
Element operators
Command
Supported
$exists
Yes
$type
Yes
Evaluation query operators
Command
Supported
$expr
Yes
$jsonSchema
No
$mod
Yes
$regex
Yes
$text
No (Not supported. Use $regex instead.)
$where
No
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 is 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/}] }).
Array operators
Command
Supported
$all
Yes
$elemMatch
Yes
$size
Yes
Comment operator
Command
Supported
$comment
Yes
Projection operators
Command
Supported
$elemMatch
Yes
$meta
No
$slice
Yes
Update operators
Field update operators
Command
Supported
$inc
Yes
$mul
Yes
$rename
Yes
$setOnInsert
Yes
$set
Yes
$unset
Yes
$min
Yes
$max
Yes
$currentDate
Yes
Array update operators
Command
Supported
$
Yes
$[]
Yes
$[<identifier>]
Yes
$addToSet
Yes
$pop
Yes
$pullAll
Yes
$pull
Yes
$push
Yes
$pushAll
Yes
Update modifiers
Command
Supported
$each
Yes
$slice
Yes
$sort
Yes
$position
Yes
Bitwise update operator
Command
Supported
$bit
Yes
$bitsAllSet
No
$bitsAnySet
No
$bitsAllClear
No
$bitsAnyClear
No
Geospatial operators
Operator
Supported
$geoWithin
Yes
$geoIntersects
Yes
$near
Yes
$nearSphere
Yes
$geometry
Yes
$minDistance
Yes
$maxDistance
Yes
$center
No
$centerSphere
No
$box
No
$polygon
No
Sort operations
When using the findOneAndUpdate operation, sort operations on a single field are supported but sort operations on multiple fields are not supported.
Indexing
The API for MongoDB supports a variety of 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 is compatible with the API for MongoDB. Explicit encryption - were the driver explicitly encrypts each field when written is supported. Automatic encryption is not supported. Explicit decryption and automatic decryption is supported.
The mongocryptd should not be run since it is not 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 extended out to achieve low-latency, global replication as well. Cosmos DB does not support manual replication commands.
Retryable Writes
Cosmos DB does not yet support retryable writes. Client drivers must add the 'retryWrites=false' URL parameter to their connection string. More URL parameters can be added by prefixing them with an '&'.
Sharding
Azure Cosmos DB supports automatic, server-side sharding. It manages shard creation, placement, and balancing automatically. Azure Cosmos DB does not 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.
Sessions
Azure Cosmos DB does not yet support server-side sessions commands.
Time-to-live (TTL)
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.
Transactions
Multi-document transactions are supported within an unsharded collection. Multi-document transactions are not supported across collections or in sharded collections. The timeout for transactions is a fixed 5 seconds.
User and role management
Azure Cosmos DB does not yet support users and roles. However, 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).
Write Concern
Some applications rely on a Write Concern, which specifies the number of responses required during a write operation. Due to how Cosmos DB handles replication in the background all writes are all 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.
Next steps
Learn how to use Studio 3T with Azure Cosmos DB API for MongoDB.
Learn how to use Robo 3T with Azure Cosmos DB API for MongoDB.
Explore MongoDB samples with Azure Cosmos DB API 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.
Azure Cosmos DB API for MongoDB