Povratne informacije Uredi

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

  • Članak
  • 9 min. za čitanje

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:

Query and write operation commands

Command Supported
change streams Yes
delete Yes
eval No
find Yes
findAndModify Yes
getLastError Yes
getMore Yes
getPrevError No
insert Yes
parallelCollectionScan No
resetError No
update Yes

Transaction commands

Note

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 (preview)

Retryable writes enables MongoDB drivers to automatically retry certain write operations in case of 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 = "NYC", the application will need to execute the operation for all shard key (country) values if Retryable writes is enabled.

db.coll.deleteMany({"country": "USA", "city": "NYC"}) – Success

db.coll.deleteMany({"city": "NYC"})- Fails with error ShardKeyNotFound(61)

To enable the feature, add the EnableMongoRetryableWrites capability to your database account.

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