Methods

The following document lists the available methods in the MongoDB Shell. Click a method to see its documentation in the MongoDB Manual, including syntax and examples.

Important

Methods which reset the shell's connection to the server trigger a termination of all open server sessions. When a session ends, all in-progress operations are terminated as well, and the client must re-authenticate if authentication is enabled.

The following methods reset the shell's connection:

db.auth
Mongo.setReadPref
Mongo.setReadConcern

Administration Methods

Method	Description
`db.shutdownServer()`	Shuts down the current `mongos` process cleanly and safely.
`db.fsyncLock()`	Flushes writes to disk and locks the database to prevent write operations and assist backup operations.
`db.fsyncUnlock()`	Allows writes to continue on a database locked with Atlas Search indexes let you query data in Atlas Search. Atlas Search indexes enable performant text search queries by mapping search terms to the documents that contain those terms. Use the following methods to manage Atlas Search indexes. Important The following methods can only be run on deployments hosted on db.collection.createSearchIndex()	Creates one or more Atlas Search indexes on a specified collection.
db.collection.getSearchIndexes()	Returns information about existing Atlas Search indexes on a specified collection.
`Bulk()` operations builder for a collection. The builder constructs an ordered list of write operations that MongoDB executes in bulk.
`Bulk()` operations builder for a collection. The builder constructs an unordered list of write operations that MongoDB executes in bulk.
`Bulk()`	Creates a bulk operations builder used to construct a list of write operations to perform in bulk for a single collection. To instantiate the builder, use either the `db.collection.initializeOrderedBulkOp()` or the `Bulk()` operations builder.
`Bulk.find.hint()`	Sets the hint option that specifies the index to support the bulk operation.
`Bulk.find.replaceOne()`	Adds a single document replacement operation to a bulk operations list.
`Bulk.find.update()`	Adds a multi update operation to a bulk operations list. The method updates specific fields in existing documents.
upsert option to `true` for an update or a replacement operation.
`Bulk.getOperations()`	Returns an array of write operations executed through `Bulk.toJSON()`	Returns a JSON document that contains the number of operations and batches in the `Bulk.toString()`	Returns as a string a JSON document that contains the number of operations and batches in the `db.collection.aggregate()`	Provides access to the `db.collection.count()`	Deprecated in `mongosh` 1.0.6. Use `db.collection.countDocuments()` or `db.collection.countDocuments()`	Returns a count of the number of documents in a collection or a view. Wraps the `$group` aggregation stage with a `db.collection.estimatedDocumentCount()`	Returns an approximate count of the documents in a collection or a view.
`db.collection.dataSize()`	Returns the size of the collection. Wraps the `size` field in the output of the `db.collection.distinct()`	Returns an array of documents that have distinct values for the specified field.
`db.collection.ensureIndex()`	Deprecated. Use `db.collection.find()`	Performs a query on a collection or a view and returns a cursor object.
`db.collection.findOneAndReplace()`	Finds a single document and replaces it.
`db.collection.getIndexes()`	Returns an array of documents that describe the existing indexes on a collection.
`db.collection.getShardVersion()`	Returns information regarding the state of data in a sharded cluster.
capped collection.
`db.collection.renameCollection()`	Changes the name of a collection.
`db.collection.stats()`	Reports on the state of a collection. Provides a wrapper around the `db.collection.storageSize()`	Reports the total size used by the collection in bytes. Provides a wrapper around the `storageSize` field of the `db.collection.totalIndexSize()`	Reports the total size used by the indexes on a collection. Provides a wrapper around the `totalIndexSize` field of the `db.collection.totalSize()`	Reports the total size of a collection, including the size of all documents and all indexes on a collection.
`db.collection.watch()`	Opens a change stream cursor on the collection.

Connection Methods

Method

Description

Mongo()

JavaScript constructor to instantiate a database connection from the mongo shell or from a JavaScript file.

The Mongo() method has the following parameters:

Parameter	Type	Description
`host`	string	Optional The connection string for the target database connection. If omitted, `Mongo()` instantiates a connection to the localhost interface on the default port `27017`.
`autoEncryptionOpts`	Document	Optional New in version 4.2. Configuration parameters for enabling Client-Side Field Level Encryption. `autoEncryptionOpts` overrides the existing client-side field level encryption configuration of the database connection. If omitted, `Mongo()` inherits the client-side field level encryption configuration of the current database connection. For documentation of usage and syntax, see read preference for the MongoDB connection.
change stream cursor for a replica set or a sharded cluster to report on all its non-system collections across its databases, with the exception of the `admin`, `local`, and `config` databases.

Cursor Methods

Method

Description

cursor.addOption()

Adds special wire protocol flags that modify the behavior of the query.

db.collection.find() operations against a sharded collection to return partial results, rather than an error, if one or more queried shards are unavailable.

cursor.batchSize()

Specifies the maximum number of documents MongoDB can return to the client within each batch returned in a query result. By default, the initial batch size is the lesser of 101 documents or 16 mebibytes (MiB) worth of documents. Subsequent batches have a maximum size of 16 MiB. This option can enforce a smaller limit than 16 MiB, but not a larger one. When set, the batchSize is the lesser of batchSize documents or 16 MiB worth of documents.

A batchSize of 0 means that the cursor is established, but no documents are returned in the first batch.

The following example query returns results in batches of 100:

db.myCollection.find().batchSize(100)

cursor.collation()

Specifies the collation for the cursor returned by the cursor.comment()

Attaches a comment to the query to allow for traceability in the logs and the system.profile collection.

cursor.count()

Modifies the cursor to return the number of documents in the result set rather than the documents themselves.

cursor.hint()

Forces MongoDB to use a specific index for a query.

cursor.isExhausted()

Returns true if the cursor is closed and there are no objects remaining in the batch.

cursor.itcount()

Computes the total number of documents in the cursor client-side by fetching and iterating the result set.

cursor.map()

Applies a function to each document in a cursor and collects the return values in an array.

cursor.max()

Specifies an exclusive upper index bound for a cursor. For use with cursor.maxTimeMS()

Specifies a cumulative time limit in milliseconds for processing operations on a cursor.

cursor.min()

Specifies an inclusive lower index bound for a cursor. For use with cursor.noCursorTimeout()

Instructs the server to avoid closing a cursor automatically after a period of inactivity.

read concern for a read preference to a cursor to control how the client directs queries to a cursor.returnKey()

Modifies the cursor to return index keys rather than the documents.

cursor.showRecordId()

Adds an internal storage engine ID field to each document returned by the cursor.

cursor.size()

Returns a count of the documents in the cursor after applying cursor.skip()

Returns a cursor that begins returning results only after passing or skipping a number of documents.

cursor.tailable()

Marks the cursor as tailable. Only valid for cursors over capped collections.

cursor.toArray()

Returns an array that contains all documents returned by the cursor.

Database Methods

Method	Description
`db.aggregate()`	Runs admin/diagnostic pipeline which does not require an underlying collection.
`db.createView()`	Creates a view as the result of applying the specified aggregation pipeline to the source collection or view.
`db.getCollection()`	Returns a collection or view object. Used to access collections with names that are not valid in the `db.getCollectionInfos()`	Returns collection information for all collections and views in the current database.
`db.getName()`	Returns the name of the current database.
slowOpThresholdMs setting, and slowOpSampleRate setting.
`db.printShardingStatus()`	Prints a formatted report of the sharding configuration and the information regarding existing chunks in a sharded cluster.
log messages.
profiler level, slowms, and change stream cursor for a database to report on all its non-system collections.

In-Use Encryption Methods

Note

Limitations

Automatic encryption is only available when mongosh is connected to an Atlas cluster or a MongoDB Enterprise Server. For details, see Automatic Client-Side Field Level Encryption. The methods listed in this section are used for manual encryption, and are supported on non-enterprise servers.
Automatic encryption is not available with the Homebrew installation of mongosh.
Field level encryption is only available in the mongosh binary, and not available in the ClientEncryption.decrypt()

Decrypts the specified encryptedValue if the current database connection was configured with access to the Key Management Service (KMS) and key vault used to encrypt encryptedValue.

ClientEncryption.encrypt()

Encrypts the specified value using the specified encryptionKeyId and encryptionAlgorithm.

getClientEncryption()

Returns the ClientEncryption object for the current database collection.

KeyVault.addKeyAlternateName()

Adds the keyAltName to the keyAltNames array of the data encryption key with the specified UUID.

KeyVault.createKey()

Adds a data encryption key to the key vault associated to the database connection.

KeyVault.deleteKey()

Deletes a data encryption key with the specified UUID from the key vault associated to the database connection.

KeyVault.getKey()

Gets a data encryption key with the specified UUID. The data encryption key must exist in the key vault associated to the database connection.

KeyVault.getKeys()

Returns all data encryption keys stored in the key vault associated to the database connection.

KeyVault.removeKeyAlternateName()

Removes the specified keyAltName from the data encryption key with the specified UUID. The data encryption key must exist in the key vault associated to the database connection.

Native Methods

Method

Description

buildInfo()

Returns the following JSON-formatted document that describes your mongosh build and driver dependencies:

{
  version: '1.10.1',
  distributionKind: 'packaged',
  buildArch: 'x64',
  buildPlatform: 'linux',
  buildTarget: 'unknown',
  buildTime: '2023-06-21T09:49:37.225Z',
  gitVersion: '05ad91b4dd40382a13f27abe1ae8c3f9f52a38f7',
  nodeVersion: 'v16.20.1',
  opensslVersion: '3.1.1',
  sharedOpenssl: true,
  runtimeArch: 'x64',
  runtimePlatform: 'darwin',
  deps: {
     nodeDriverVersion: '5.6.0',
     libmongocryptVersion: undefined,
     libmongocryptNodeBindingsVersion: undefined
   }
}

isInteractive()

Returns a boolean indicating whether mongosh is running in interactive or script mode.

load()

Loads and runs a JavaScript file in the shell.

In mongosh, scripts loaded with the load() method support the __filename and __dirname Node.js variables. These variables return the file name and directory of the loaded script, respectively. The returned values are always absolute paths.

The legacy mongo shell cannot access a script's file name or directory in the load() method.

print()

Print the specified text or variable. print() and printjson() are aliases for console.log().

> print("hello world")
hello world
> x = "example text"
> print(x)
example text

quit()

Exits the current shell session.

sleep()

Suspends the db.collection.getPlanCache()

Returns an interface to access the query plan cache object and associated PlanCache methods for a collection.

PlanCache.clearPlansByQuery()

Clears the cached query plans for the specified PlanCache.help()

Lists the methods available to view and modify a collection’s query plan cache.

PlanCache.list()

Returns an array of plan cache entries for a collection.

Replication Methods

Method

Description

rs.add()

Adds a member to the replica set. You must connect to the primary of the replica set to run this method.

rs.freeze()

Makes the replica set member that mongosh is connected to ineligible to become primary for the specified duration. You must specify the duration in seconds.

db.printReplicationInfo()

Returns the oplog of the replica set member that mongosh is connected to.

rs.printReplicationInfo()

Returns the oplog of the replica set member that mongosh is connected to.

db.printSecondaryReplicationInfo

Returns the status of the secondary members of the replica set.

This is identical to the rs.printSecondaryReplicationInfo() method.

The following is an example output from the rs.printSecondaryReplicationInfo() method issued on a replica set with two secondary members:

source: rs2.example.net:27017
{
  syncedTo: 'Tue Oct 13 2020  09:37:28 GMT-0700 (Pacific Daylight Time)',
  replLag: '0 secs (0 hrs) behind the primary '
}
---
source: rs3.example.net:27017
{
  syncedTo: 'Tue Oct 13 2020  09:37:28 GMT-0700 (Pacific Daylight Time)',
  replLag: '0 secs (0 hrs) behind the primary '
}

rs.printSecondaryReplicationInfo

Returns the status of the secondary members of the replica set.

This is identical to the db.printSecondaryReplicationInfo() method.

The following is an example output from the rs.printSecondaryReplicationInfo() method issued on a replica set with two secondary members:

source: rs2.example.net:27017
{
  syncedTo: 'Tue Oct 13 2020 09:42:18 GMT-0700 (Pacific Daylight Time)',
  replLag: '0 secs (0 hrs) behind the primary '
}
---
source: rs3.example.net:27017
{
  syncedTo: 'Tue Oct 13 2020 09:42:18 GMT-0700 (Pacific Daylight Time)',
  replLag: '0 secs (0 hrs) behind the primary '
}

rs.status()

Returns the status of the replica set member that mongosh is connected to.

rs.stepDown()

Makes the primary of the replica set a secondary. You must be connected to the primary to run this method.

rs.syncFrom()

Resets the sync target to the replica set member specified by hostname for the replica set member that mongosh is connected to.

Role Management Methods

Method	Description
`db.getRole()`	Returns information for the specified role.
`db.getRoles()`	Returns information for all the user-defined roles in a database.
`db.grantRolesToRole()`	Specifies roles from which a user-defined role inherits privileges.
Session.advanceOperationTime()	Updates the operation time.
Session.getOperationTime()	Returns the timestamp of the last acknowledged operation for the session.
`SessionOptions()`	The options for a session in the shell. To access the `db.hello()`	Returns a document that describes the role of the `mongod` is a member of a replica set, then the `isWritablePrimary` and `secondary` fields report if the instance is the secondary member of the replica set.
`db.hostInfo()`	Returns a document with information about the system running the MongoDB instance.
`db.serverBuildInfo()`	Returns a document that displays the compilation parameters for the `db.serverCmdLineOpts()`	Returns a document with information about the runtime options used to start the MongoDB instance.
`db.serverStatus()`	Returns a document that provides an overview of the database process.
`db.stats()`	Returns a document that reports on the state of the current database.
`sh.addShardTag()`	Aliases to `sh.addShardToZone()`	Associates a shard with a zone. Supports configuring zones in sharded clusters.
sh.disableAutoMerger()	Disables automatic chunk merges for a namespace. New in version 7.0.
`sh.disableBalancing()`	Disables balancing on a single collection in a sharded database. Does not affect balancing of other collections in a sharded cluster.
`sh.enableBalancing()`	Activates the sharded collection balancer process if previously disabled using balancer is currently enabled.
`sh.getShardedDataDistribution()`	Returns data distribution information for sharded collections. `sh.getShardedDataDistribution()` is a shell helper method for the `$shardedDataDistribution` aggregation pipeline stage.
balancer process is currently migrating chunks.
config shard. If it does, `sh.isConfigShardEnabled()` also returns host and tag information.
sh.listShards()	Returns an array of documents describing the shards in a sharded cluster.
`sh.removeRangeFromZone()`	Removes the association between a range of shard key values and a `sh.removeShardTag()`	Removes the association between a tag and a shard.
`sh.removeTagRange()`	Removes a range of shard key values to a shard tag created using the `sh.addShardTag()` method. This method aliases to balancer which migrates `sh.splitAt()`	Divides an existing chunk into two chunks using a specific value of the chunk that contains a document matching a query into two approximately equal chunks.
`sh.status()`	Reports on the status of a sharded cluster.
balancer. This operation does not wait for the balancer to complete any in progress operations, and may terminate ongoing operations.
`sh.updateZoneKeyRange()`	Associates a range of shard keys with a zone. Supports configuring zones in sharded clusters.

Telemetry Methods

These methods configure whether mongosh tracks anonymous telemetry data. Telemetry is enabled by default.

For more information on what data mongosh tracks with telemetry, see enableTelemetry()

Enable telemetry for mongosh.

Transaction Methods

Method	Description
multi-document transaction and rolls back any data changes made by the operations within the transaction.
multi-document transaction and ends the transaction.
multi-document transaction associated with the session.

User Management Methods

Important

The passwordPrompt() method is currently not supported in mongosh. As a result, when using the following methods you must specify the password as a parameter:

db.updateUser()

Method	Description
`db.dropAllUsers()`	Deletes all users associated with a database.
`db.updateUser()`	Updates a specified user's data.
`db.revokeRolesFromUser()`	Removes a role from a user.

EJSON