MongoDB 4.0 Compatibility - Amazon DocumentDB

MongoDB 4.0 Compatibility

Amazon DocumentDB supports MongoDB 4.0 compatibility including ACID transactions. MongoDB 4.0 compatibility means that a vast majority of the applications, drivers, and tools you already use today with your MongoDB 4.0 databases can be used with Amazon DocumentDB 4.0 with little or no change. This section describes everything you need to know about Amazon DocumentDB 4.0 including new capabilities and features, getting started, migrations paths, and functional differences.

What's new in Amazon DocumentDB 4.0

Amazon DocumentDB 4.0 introduces many new features and capabilities that include ACID transactions and improvements to change streams. The summary below introduces some of major features that were introduced in Amazon DocumentDB 4.0. To see a full list of the new capabilities, see the Release Notes.

  • ACID Transactions: Amazon DocumentDB now supports the ability to perform transactions across multiple documents, statements, collections, and databases. Transactions simplify application development by enabling you to perform atomic, consistent, isolated, and durable (ACID) operations across one or more documents within an Amazon DocumentDB cluster. For more information, see Transactions.

  • Change streams: You now have the ability to open a change stream at the cluster level ( or and the database (, you can specify a startAtOperationTime to open a change stream cursor, and lastly you can now extend your change stream retention period to 7 days (previously 24 hours). For more information, see Using Change Streams with Amazon DocumentDB.

  • AWS Database Migration Service (AWS DMS): You can now use AWS DMS to migrate your MongoDB 4.0 workloads to Amazon DocumentDB. AWS DMS now supports a MongoDB 4.0 source, Amazon DocumentDB 4.0 target, and an Amazon DocumentDB 3.6 source for performing upgrades between Amazon DocumentDB 3.6 and 4.0. For more information, see AWS DMS Documentation.

  • Performance and indexing: You can now utilize an index with $lookup, find queries with a projection that contain one field or one field and the _id field can be served direct from the index and without needing to read from the collection (covered query), the ability to hint() with findAndModify, performance optimizations for $addToSet, and improvements to reduce overall index sizes. For more information, see Release Notes.

  • Operators: Amazon DocumentDB 4.0 now supports a number of new aggregation operators: $ifNull, $replaceRoot, $setIsSubset, $setInstersection, $setUnion, $setEquals. You can see all the MongoDB APIs, Operations, and Data Types that we support at Supported MongoDB APIs, Operations, and Data Types.

  • Role based access control (RBAC): With both ListCollection and ListDatabase commands you can now optionally use the authorizedCollections and authorizedDatabases parameters to allow users to list the collections and databases that they have permission to access without requiring the listCollections and listDatabase roles, respectively. You also have the ability to kill your own cursors without requiring the KillCursor role.

Amazon DocumentDB does not support every MongoDB 4.0 feature. When we built Amazon DocumentDB 4.0, we worked backwards from the feature and capabilities that our customers asked us to build the most. We will continue to add additional MongoDB 4.0 capabilities based on what customers ask us to build. For example, Amazon DocumentDB 4.0 does not currently support the type conversion operators or the string operators that were introduced in MongoDB 4.0. For the latest list of supported APIs, please see Supported MongoDB APIs, Operations, and Data Types.

Get Started with Amazon DocumentDB 4.0

To get started with Amazon DocumentDB 4.0, please see the Get Started Guide. You can create a new Amazon DocumentDB 4.0 cluster using the AWS Management Console or the AWS SDK, AWS CLI, or AWS CloudFormation. When connecting to Amazon DocumentDB, it is required that you use a MongoDB driver or utility that is compatible with MongoDB 4.0 or higher.


When using the AWS SDK, AWS CLI, or AWS CloudFormation, the engine version will default to 3.6. You must explicitly specify the parameter engineVersion=4.0 to create a new Amazon DocumentDB 4.0.0 cluster. For a given Amazon DocumentDB cluster, you can determine the cluster version using the AWS CLI to call describe-db-clusters or use the Amazon DocumentDB management console to view the engine version number for a particular cluster.

Amazon DocumentDB 4.0 supports r5 and t3.medium instance types for your clusters and is available in all supported regions. There is no additional cost for using Amazon DocumentDB 4.0. For more information on pricing, see Amazon DocumentDB (with MongoDB compatibility) Pricing.

Upgrade or Migrate to Amazon DocumentDB 4.0

You can migrate from MongoDB 3.6 or MongoDB 4.0 to Amazon DocumentDB 4.0 utilizing the AWS DMS or utilities like mongodump, mongorestore, mongoimport, and mongoexport. Similarly, you can use the same tools to upgrade from Amazon DocumentDB 3.6 to Amazon DocumentDB 4.0. For instructions on how to migrate, see Upgrading your Amazon DocumentDB cluster from 3.6 to 4.0 using AWS Database Migration Service.

Functional Differences

Functional Differences Between Amazon DocumentDB 3.6 and 4.0

With the release of Amazon DocumentDB 4.0, there are functional differences between Amazon DocumentDB 3.6 and Amazon DocumentDB 4.0:

  • Projection for nested documents: Amazon DocumentDB 3.6 considers the first field in a nested document when applying a projection. However, Amazon DocumentDB 4.0 will parse subdocuments and apply the projection to each sub document as well. For example: if the projection is "a.b.c": 1, then the behavior in both versions is identical. However, if the projection is {a:{b:{c:1}}} then Amazon DocumentDB 3.6 will only apply the projection to 'a' and not 'b' or 'c'.

  • Behavior for minKey, maxKey: In Amazon DocumentDB 4.0, the behavior for {x:{$gt:MaxKey}} returns nothing, and for {x:{$lt:MaxKey}} returns everything.

  • Document comparison differences: Comparing numerical values of different types (double, int, long) in subdocuments (e.g., b in {"_id" :1, "a" :{"b":1}}) now provides a consistent output across numerical data types and for each level of a document.

Functional Differences Between Amazon DocumentDB 4.0 and MongoDB 4.0

Below are functional differences between Amazon DocumentDB 4.0 and MongoDB 4.0.

  • Lookup with empty key in path: When a collection contains a document with empty key inside the array (e.g. {"x" : [ { "" : 10 }, { "b" : 20 } ]}), and when the key used in the query ends in an empty string (e.g. x.), then Amazon DocumentDB will return that document since it traverses all the documents in the array whereas MongoDB will not return that document.

  • $setOnInsert along with $ in the path: The field operator $setOnInsert will not work in combination with $ in the path in Amazon DocumentDB, which is also consistent with MongoDB 4.0.