MongoDB 5.0 Compatibility MongoDB 4.0 Compatibility

MongoDB Compatibility

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

MongoDB 5.0 Compatibility

Topics

What's new in Amazon DocumentDB 5.0
Get Started with Amazon DocumentDB 5.0
Upgrade or Migrate to Amazon DocumentDB 4.0
Functional Differences

What's new in Amazon DocumentDB 5.0

Amazon DocumentDB 5.0 introduces new features and capabilities that include storage limits and client-side field level encryption. The summary below introduces some of major features that were introduced in Amazon DocumentDB 5.0. To see a full list of the new capabilities, see the Release Notes.

Increased storage limit to 128 TiB for all instance-based Amazon DocumentDB clusters and shard-based elastic clusters.
Introduced Amazon DocumentDB 5.0 Engine Version 3.0.775)
- Support for MongoDB 5.0 API drivers
- Support for Client-side Field Level Encryption (FLE). You can now encrypt fields at the client-side before writing the data to Amazon DocumentDB cluster. For more information, see Client-side field level encryption
- New aggregation operators: $dateAdd, $dateSubtract
- Supports for indexes with $elemMatch operator. As a result, queries having $elemMatch will result in index scans.

Amazon DocumentDB does not support every MongoDB 5.0 feature. When we built Amazon DocumentDB 5.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 5.0 capabilities based on what customers ask us to build. For the latest list of supported APIs, please see Supported MongoDB APIs, operations, and data types.

Get Started with Amazon DocumentDB 5.0

To get started with Amazon DocumentDB 5.0, please see the Get Started Guide. You can create a new Amazon DocumentDB 5.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 5.0 or higher.

Note

When using the AWS SDK, AWS CLI, or AWS CloudFormation, the engine version will default to 5.0.0. You must explicitly specify the parameter engineVersion = 4.0.0 to create a new Amazon DocumentDB 4.0 cluster or engineVersion = 3.6.0 to create a new Amazon DocumentDB 3.6 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 5.0 supports Amazon EC2 Graviton2 processors such as r6g and t4.medium instance types for your clusters and is available in all supported regions. 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 5.0 using the AWS DMS or utilities like mongodump, mongorestore, mongoimport, and mongoexport. For instructions on how to migrate, see Upgrading your Amazon DocumentDB cluster using AWS Database Migration Service.

Functional Differences

Functional Differences Between Amazon DocumentDB 4.0 and 5.0

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

The backup built-in role now supports serverStatus. Action - Developers and applications with backup role can collect statistics about the state of the Amazon DocumentDB cluster.
The SecondaryDelaySecs field replaces slaveDelay in replSetGetConfig output.
The hello command replaces isMaster - hello returns a document that describes the role of a Amazon DocumentDB cluster.

Amazon DocumentDB 5.0 now supports index scans with the $elemMatch operator in the first nesting level. Index scans are supported when the query only filter has one level of the $elemMatch filter but are not supported if a nested $elemMatch query is included.

For example, in Amazon DocumentDB 5.0, if you include the $elemMatch operator in the nested level, it will not return a value as it does in Amazon DocumentDB 4.0:


db.foo.insert(
[
    {a: {b: 5}},
    {a: {b: [5]}},
    {a: {b: [3, 7]}},
    {a: [{b: 5}]},
    {a: [{b: 3}, {b: 7}]},
    {a: [{b: [5]}]},
    {a: [{b: [3, 7]}]},
    {a: [[{b: 5}]]},
    {a: [[{b: 3}, {b: 7}]]},
    {a: [[{b: [5]}]]},
    {a: [[{b: [3, 7]}]]}
]);

// DocumentDB 5.0
> db.foo.find({a: {$elemMatch: {b: {$elemMatch: {$lt: 6, $gt: 4}}}}}, {_id: 0})
{ "a" : [ { "b" : [ 5 ] } ] }

// DocumentDB 4.0
> db.foo.find({a: {$elemMatch: {b: {$elemMatch: {$lt: 6, $gt: 4}}}}}, {_id: 0})
{ "a" : [ { "b" : [ 5 ] } ] }
{ "a" : [ [ { "b" : [ 5 ] } ] ] }

The "$" projection in Amazon DocumentDB 4.0 returns all documents with all fields. With Amazon DocumentDB 5.0, the find command with a "$" projection returns documents that match the query parameter containing only the field that matched the "$" projection.
In Amazon DocumentDB 5.0, the find commands with $regex and $options query parameters return an error: "Cannot set options in both $regex and $options".
With Amazon DocumentDB 5.0, $indexOfCP now returns "-1" when:
- the substring is not found in the string expression, or
- start is a number greater than end, or
- start is a number greater than the byte length of the string.
In Amazon DocumentDB 4.0, $indexOfCP returns "0" when the start position is a number greater than end or the byte length of the string.
With Amazon DocumentDB 5.0, projection operations in _id fields, for example {"_id.nestedField" : 1}, return documents that only include the projected field. Whereas in Amazon DocumentDB 4.0, nested field projection commands do not filter out any document.

MongoDB 4.0 Compatibility

Topics

Amazon DocumentDB 4.0 features
Get Started with Amazon DocumentDB 4.0
Upgrade or Migrate to Amazon DocumentDB 4.0
Functional Differences

Amazon DocumentDB 4.0 features

Amazon DocumentDB 4.0 introduced many new features and capabilities that included ACID transactions and improvements to change streams. The summary below shows some of the major features that were introduced in Amazon DocumentDB 4.0. To see a full list of the 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 (client.watch() or mongo.watch()) and the database (db.watch()), 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.

Note

Amazon DocumentDB 4.0 supports r5, r6g, t3.medium, and t4g.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 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.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Quick Start using AWS CloudFormation

Transactions