Functional Differences: Amazon DocumentDB and MongoDB - Amazon DocumentDB

Functional Differences: Amazon DocumentDB and MongoDB

The following are the functional differences between Amazon DocumentDB (with MongoDB compatibility) and MongoDB.

Functional Benefits of Amazon DocumentDB

Implicit Transactions

In Amazon DocumentDB, all CRUD statements (findAndModify, update, insert, delete) guarantee atomicity and consistency, even for operations that modify multiple documents. This behavior is different than MongoDB 3.6, which only provides atomic guarantees for commands that modify a single document. The following are examples of operations in Amazon DocumentDB that modify multiple documents that satisfy both atomic and consistent behaviors.

db.miles.update( { "credit_card": { $eq: true } }, { $mul: { "flight_miles.$[]": NumberInt(2) } }, { multi: true } )
db.miles.updateMany( { "credit_card": { $eq: true } }, { $mul: { "flight_miles.$[]": NumberInt(2) } } )
db.runCommand({ update: "miles", updates: [ { q: { "credit_card": { $eq: true } }, u: { $mul: { "flight_miles.$[]": NumberInt(2) } }, multi: true } ] })
db.products.deleteMany({ "cost": { $gt: 30.00 } })
db.runCommand({ delete: "products", deletes: [{ q: { "cost": { $gt: 30.00 } }, limit: 0 }] })

The individual operations that compose bulk operations such as updateMany and deleteMany are atomic but the entirety of the bulk operation is not atomic. For example, the entirety of the insertMany operation is atomic if the individual insert operations execute successfully without error. If an error is encountered with an insertMany operation, each individual insert statement within the insertMany operation will execute as an atomic operation.

Amazon DocumentDB currently supports implicit transactional semantics for single statement operations, as shown previously. Amazon DocumentDB currently does not support multi-statement transactions.

Updated Functional Differences

Amazon DocumentDB continues to improve compatibility with MongoDB by working backwards from the capabilities our customers ask us to build. This section contains the functional differences that we have removed in Amazon DocumentDB to make migrations and building applications easier for our customers.

Array Indexing

As of April 23, 2020, Amazon DocumentDB now supports the ability to index arrays that are greater than 2,048 bytes. The limit for an individual item in an array still remains as 2,048 bytes, which is consistent with MongoDB.

If you are creating a new index, no action is needed to take advantage of the improved functionality. If you have an existing index, you can take advantage of the improved functionality by dropping the index and then recreating it. The current index version with the improved capabilities is "v" : 3.

Note

For production clusters, the dropping of the index may have an impact on your application performance. We recommend that you first test and proceed with caution when making changes to a production system. In addition, the time it will take to recreate the index will be a function of the overall data size of the collection.

You can query for the version of your indexes using the following command.

db.collection.getIndexes()

Output from this operation looks something like the following. In this output, the version of the index is "v" : 3, which is the most current index version.

[ { "v" : 3, "key" : { "_id" : 1 }, "name" : "_id_", "ns" : "test.test" } ]

Multi-key Indexes

As of April 23, 2020, Amazon DocumentDB now supports the ability to create a compound index with multiple keys in the same array.

If you are creating a new index, no action is needed to take advantage of the improved functionality. If you have an existing index, you can take advantage of the improved functionality by dropping the index and then recreating it. The current index version with the improved capabilities is "v" : 3.

Note

For production clusters, the dropping of the index may have an impact on your application performance. We recommend that you first test and proceed with caution when making changes to a production system. In addition, the time it will take to recreate the index will be a function of the overall data size of the collection.

You can query for the version of your indexes using the following command.

db.collection.getIndexes()

Output from this operation looks something like the following. In this output, the version of the index is "v" : 3, which is the most current index version.

[ { "v" : 3, "key" : { "_id" : 1 }, "name" : "_id_", "ns" : "test.test" } ]

Null Characters in Strings

As of June 22, 2020, Amazon DocumentDB now supports null characters ( '\0' ) in strings.

Role-Based Access Control

As of March 26, 2020, Amazon DocumentDB supports role-based access control (RBAC) for built-in roles. To learn more, see Role-Based Access Control. Amazon DocumentDB does not yet support custom roles for RBAC.

$regex Indexing

As of June 22, 2020, Amazon DocumentDB now supports the ability for $regex operators to utilize an index.

To utilize an index with the $regex operator, you must use the hint() command. When using hint(), you must specify the name of the field you are applying the $regex on. For example, if you have an index on field product with the index name as p_1, db.foo.find({product: /^x.*/}).hint({product:1}) will utilize the p_1 index, but db.foo.find({product: /^x.*/}).hint(“p_1”) will not utilize the index. You can verify if an index is chosen by utilizing the explain() command or using the profiler for logging slow queries. For example, db.foo.find({product: /^x.*/}).hint(“p_1”).explain().

Note

The hint() method can only be used with one index at a time.

The use of an index for a $regex query is optimized for regex queries that utilize a prefix and do not specify the I, m, or o regex options.

When using an index with $regex, it is recommended that you create an index on highly selective fields where the number of duplicate values is less than 1% of the total number of documents in the collection. As an example, if your collection contains 100,000 documents, only create indexes on fields where the same value occurs 1000 times or fewer.

Functional Differences with MongoDB

Admin Databases and Collections

Amazon DocumentDB does not support the admin or local database nor MongoDB system.* or startup_log collections respectively.

explain()

Amazon DocumentDB emulates the MongoDB 3.6 API on a purpose-built database engine that utilizes a distributed, fault-tolerant, self-healing storage system. As a result, query plans and the output of explain() may differ between Amazon DocumentDB and MongoDB. Customers who want control over their query plan can use the $hint operator to enforce selection of a preferred index.

Field Name Restrictions

Amazon DocumentDB does not support dots “.” in a document field name, for example, db.foo.insert({‘x.1’:1}).

Amazon DocumentDB also does not support the $ prefix in field names.

For example, try the following command in Amazon DocumentDB or MongoDB:

rs0:PRIMARY< db.foo.insert({"a":{"$a":1}})

MongoDB will return the following:

WriteResult({ "nInserted" : 1 })

Amazon DocumentDB will return an error:

WriteResult({ "nInserted" : 0, "writeError" : { "code" : 2, "errmsg" : "Document can't have $ prefix field names: $a" } })
Note

There is an exception to this functional difference. The following field names that begin with the $ prefix have been whitelisted and can be successfully used in Amazon DocumentDB: $id, $ref and $db.

Index Builds

Amazon DocumentDB allows only one index build to occur on a collection at any given time (foreground or background). If operations such as createIndex() or dropIndex() occur on the same collection when an index build is currently in progress, the newly attempted operation will fail.

A Time to Live (TTL) index starts expiring documents after the index build (foreground or background) is completed.

MongoDB APIs, Operations, and Data Types

Amazon DocumentDB is compatible with the MongoDB 3.6 API. For an up-to-date list of supported functionality, see Supported MongoDB APIs, Operations, and Data Types.

The mongodump and mongorestore Utilities

Amazon DocumentDB does not support an admin database and thus does not dump or restore the admin database when using the mongodump or mongorestore utilities. When you create a new database in Amazon DocumentDB using mongorestore, you need to re-create the user roles in addition to the restore operation.

Result Ordering

Amazon DocumentDB does not guarantee implicit result sort ordering of result sets. To ensure the ordering of a result set, explicitly specify a sort order using sort().

The following example sorts the items in the inventory collection in descending order based on the stock field.

db.inventory.find().sort({ stock: -1 })

Retryable Writes

Starting with MongoDB 4.2 compatible drivers, retryable writes is enabled by default. However, Amazon DocumentDB does not currently support retryable writes. The functional difference will manifest itself in an error message similar to the following.

{"ok":0,"errmsg":"Unrecognized field: 'txnNumber'","code":9,"name":"MongoError"}

Retryable writes can be disabled via the connection string (for example, MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")) or the MongoClient constructor’s keyword argument (for example, MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)).

The following is a Python example that disables retryable writes in the connection string.

client = pymongo.MongoClient('mongodb://<username>:<password>@docdb-2019-03-17-16-49-12.cluster-ccuszbx3pn5e.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0',w='majority',j=True,retryWrites=False)

Sparse Index

To use a sparse index that you have created in a query, you must use the $exists clause on the fields that cover the index. If you omit $exists, Amazon DocumentDB does not use the sparse index.

The following is an example.

db.inventory.count({ "stock": { $exists: true }})

For sparse, multi-key indexes, Amazon DocumentDB does not support a unique key constraint if the look up of a document results in a set of values and only a subset of the indexed fields is missing. For example, createIndex({"a.b" : 1 }, { unique : true, sparse :true }) is not supported, given the input of "a" : [ { "b" : 2 }, { "c" : 1 } ], as "a.c" is stored in the index.

Storage Compression

Amazon DocumentDB doesn't currently support compression for stored data or indexes. Data sizes for stored data and indexes might be larger than when you use other options.

Using $elemMatch Within an $all Expression

Amazon DocumentDB does not currently support the use of the $elemMatch operator within an $all expression. As a workaround, you can use the $and operator with $elemMatch as follows.

Original operation:

db.col.find({ qty: { $all: [ { "$elemMatch": { part: "xyz", qty: { $lt: 11 } } }, { "$elemMatch": { num: 40, size: "XL" } } ] } })

Updated operation:

db.col.find({ $and: [ { qty: { "$elemMatch": { part: "xyz", qty: { $lt: 11 } } } }, { qty: { "$elemMatch": { qty: 40, size: "XL" } } } ] })

$distinct, $elemMatch, and $lookup Indexing

Amazon DocumentDB does not currently support the ability to use indexes with the $distinct, $elemMatch, and $lookup operators. As a result, utilizing these operators will result in collection scans. Performing a filter or match before utilizing one of these operators will reduce the amount of data that needs to be scanned, and thus can improve performance.

$lookup

Amazon DocumentDB supports the ability to do equality matches (for example, left outer join) but does not support uncorrelated subqueries.

cursormaxTimeMS

In Amazon DocumentDB, cursor.maxTimeMS resets the counter for each getMore request. Thus, if a 3000MS maxTimeMS is specified, the query takes 2800MS, and each subsequent getMore request takes 300MS, then the cursor will not timeout. The cursor will only timeout when a single operations, either the query or an individual getMore request, takes more than the specified maxTimeMS. Further, the sweeper that checks cursor execution time runs at a minute granularity.