Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Functional Differences: Amazon DocumentDB and MongoDB

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

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 })

Implicit Transactions

In Amazon DocumentDB, all CRUD statements (findAndModify, update, insert, delete) guarantee atomicity and consistency, even for operations that modify multiple documents. Following are examples of operations in Amazon DocumentDB that modify multiple documents that satisfy both atomic and consistent behaviors.

db.inventory.update( { stock: { $lt: 100 } }, { $set: { restock: true } }, { multi: true } ){}, {$inc: {review: 1}})
db.pets.insertMany( [ {item: "duck", qty: 20 }, {item: "rabbit", qty: 55 }, {item: "gold fish", qty: 30 } ] );
db.products.deleteMany( { "cost" : { $gt : 30.00 } } );
db.miles.findAndModify({ query: {member_since: {$lte: ISODate("1990-01-01T00:00:00Z")}}, update: {$set: {"flight_miles.$[element]": 2000}}, arrayFilters: [{"element": {$lt:2000}}] })

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

Admin Databases and Collections

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

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 using mongorestore, when you create a new database in Amazon DocumentDB, you need to re-create the user roles in addition to the restore operation.

Background Indexes

Amazon DocumentDB allows only one background index build to occur on a collection at any given time. If data definition language (DDL) operations such as createIndex() or dropIndex() occur on the same collection during a background index build, the background index build fails.

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


Amazon DocumentDB does not allow null characters ( '\0' ) in strings.

db.inventory.insert( {"description": "\0"} ) WriteResult({ "writeError": { "code": 303, "errmsg": "Unsupported BSON : has null character in string" } })

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 }})

Multi-key Index

Amazon DocumentDB does not yet support creating a compound index with multiple keys on the same array. A workaround is to create individual indexes on the desired array fields, as the Amazon DocumentDB query planner can use multiple indexes in a single query.

Array Indexing

Amazon DocumentDB indexes an array as a single entry. Arrays larger than 2048 bytes cannot currently be indexed.

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.

Field Name Restrictions

Amazon DocumentDB does not support dots “.” in a document field name, e.g.,{‘x.1’: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 (e.g. MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")) or the MongoClient constructor’s keyword argument (e.g. MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)).

Following is a Python example that disables retryable writes in the connection string:

client = pymongo.MongoClient('mongodb://<username>:<password>',w='majority',j=True,retryWrites=False)

MongoDB APIs, Operations, and Data Types

Amazon DocumentDB supports a subset of MongoDB APIs, operations, and data types, and we are continually adding more. To see what is currently supported, see Supported MongoDB APIs, Operations, and Data Types.