Docs Menu

Docs HomeView & Analyze DataMongoDB Shell

Compatibility Changes with Legacy mongo Shell

On this page

  • Deprecated Methods
  • Read Preference Behavior
  • Write Preference Behavior
  • ObjectId Methods and Attributes
  • Numeric Values
  • Object Quoting Behavior
  • Limitations on Database Calls

This page describes differences between mongosh and the legacy mongo shell. In addition to the alternatives listed here, you can use the mongocompat snippet to access to legacy mongo shell APIs. Snippets are an experimental feature, for more information, see Snippets.

snippet install mongocompat

The following shell methods are deprecated in mongosh. Instead, use the methods listed in the Alternative Resources column.

Deprecated Method
Alternative Resources
Aggregation stage: $out
No longer required. See Read Operations on a Secondary Node.

When using the legacy mongo shell to connect directly to secondary replica set member, you must run mongo.setReadPref() to enable secondary reads.

When using mongosh to connect directly to a secondary replica set member, you can read from that member if you specify a read preference of either:

To specify a read preference, you can use either:

When using mongosh to connect directly to a secondary replica set member, if your read preference is set to primaryPreferred, secondary or secondaryPreferred it is not required to run rs.secondaryOk().

The following show helper methods always use a read preference of primaryPreferred, even when a different read preference has been specified for the operation:

  • show dbs

  • show databases

  • show collections

  • show tables

In the legacy mongo shell, these operations use the specified read preference.

Retryable writes are enabled by default in mongosh. Retryable writes were disabled by default in the legacy mongo shell. To disable retryable writes, use --retryWrites=false.

These ObjectId() methods work differently in mongosh than in the legacy mongo shell.

Method or Attribute
mongo Behavior
mongosh Behavior
Returns a hexadecimal string:
(Not available)
Returns the value of ObjectId.str:
Returns a formatted string:
Returns a formatted string:
Returns a hexadecimal formatted string:

The legacy mongo shell stored numerical values as doubles by default. In mongosh numbers are stored as 32 bit integers, Int32, or else as Double if the value cannot be stored as an Int32.

MongoDB Shell continues to support the numeric types that are supported in mongo shell. However, the preferred types have been updated to better align with the MongoDB drivers. See mongosh Data Types for more information.

The preferred types for numeric variables are different in MongoDB Shell than the types suggested in the legacy mongo shell. The types in mongosh better align with the types used by the MongoDB Drivers.

mongo type
mongosh type


Data types may be stored inconsistently if you connect to the same collection using both mongosh and the legacy mongo shell.


See also:

For more information on managing types, refer to the schema validation overview.

mongosh does not quote object keys in its output, and places single quotes on values. To reproduce the output of the legacy mongo shell, which wraps both the keys and string values in double quotes, use mongosh --eval with EJSON.stringify().

For example, the following command returns the items in the sales collection on the test database with double quotes and indentation:

mongosh --eval "EJSON.stringify(db.sales.findOne().toArray(), null, 2)"

The output looks like the following:

"_id": {
"$oid": "64da90c1175f5091debcab26"
"custId": 345,
"purchaseDate": {
"$date": "2023-07-04T00:00:00Z"
"quantity": 4,
"cost": {
"$numberDecimal": "100.60"

The results of database queries cannot be passed inside the following contexts:

  • Class constructor functions

  • Non-async generator functions

  • Callbacks to .sort() on an array

  • JavaScript setters in classes

To access to the results of database calls, use async functions, async generator functions, or .map().

The following constructors do not work:

// This code will fail
class FindResults {
constructor() {
this.value = db.students.find();
// This code will fail
function listEntries() { return db.students.find(); }
class FindResults {
constructor() {
this.value = listEntries();

Use an async function instead:

class FindResults {
constructor() {
this.value = ( async() => {
return db.students.find();
} )();


You can also create a method that performs a database operation inside a class as an alternative to working with asynchronous JavaScript.

class FindResults {
constructor() { }
init() { this.value = db.students.find(); }

To use this class, first construct a class instance then call the .init() method.

The following generator functions do not work:

// This code will fail
function* FindResults() {
yield db.students.findOne();
// This code will fail
function listEntries() { return db.students.findOne(); }
function* findResults() {
yield listEntries();

Use an async generator function instead:

function listEntries() { return db.students.findOne(); }
async function* findResults() {
yield listEntries();

The following array sort does not work:

// This code will fail
db.getCollectionNames().sort( ( collectionOne, collectionTwo ) => {
return db[ collectionOne ].estimatedDocumentCount() - db[ collectionOne ].estimatedDocumentCount() )
} );

Use .map() instead.

db.getCollectionNames().map( collectionName => {
return { collectionName, size: db[ collectionName ].estimatedDocumentCount() };
} ).sort( ( collectionOne, collectionTwo ) => {
return collectionOne.size - collectionTwo.size;
} ).map( collection => collection.collectionName);

This approach to array sort is often more performant than the equivalent unsupported code.

The following JavaScript setter does not work:

// This code will fail
class TestClass {
value = 1;
get property() {
return this.value;
// does not work:
set property(value) {
this.value = db.test.findOne({ value });
← Reference