methods.txt

.. _mdb-shell-methods:

=======
Methods
=======

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

The following document lists the available methods in the |mdb-shell|.
Click a method to see its documentation in the
:manual:`MongoDB Manual </>`, including syntax and examples.

.. include:: /includes/admonitions/connection-resets.rst

Administration Methods
----------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.adminCommand()`

     - Runs a command against the ``admin`` database.

   * - :method:`db.currentOp()`

     - Reports the current in-progress operations.

   * - :method:`db.killOp()`

     - Terminates a specified operation.

   * - :method:`db.shutdownServer()`

     - Shuts down the current :binary:`~mongod` or :binary:`~mongos`
       process cleanly and safely.

   * - :method:`db.fsyncLock()`

     - Flushes writes to disk and locks the database to prevent write
       operations and assist backup operations.

   * - :method:`db.fsyncUnlock()`

     - Allows writes to continue on a database locked with
       :method:`db.fsyncLock()`.

.. _mongosh-methods-atlas-search:

Atlas Search Index Methods
--------------------------

:atlas:`Atlas Search indexes
</atlas-search/atlas-search-overview/#fts-indexes>` let you query data
in :atlas:`Atlas Search </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
   :atlas:`MongoDB Atlas </>`.

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Name

     - Description

   * - :upcoming:`db.collection.createSearchIndex()
       </reference/method/db.collection.createSearchIndex>`

     - Creates one or more Atlas Search indexes on a specified
       collection.

   * - :upcoming:`db.collection.dropSearchIndex()
       </reference/method/db.collection.dropSearchIndex>`

     - Deletes an existing Atlas Search index.

   * - :upcoming:`db.collection.getSearchIndexes()
       </reference/method/db.collection.getSearchIndexes>`

     - Returns information about existing Atlas Search indexes on a specified
       collection.

   * - :upcoming:`db.collection.updateSearchIndex()
       </reference/method/db.collection.updateSearchIndex>`

     - Updates an existing Atlas Search index.

Bulk Operation Methods
----------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.collection.initializeOrderedBulkOp()`

     - Initializes and returns a new :method:`Bulk()` operations builder
       for a collection. The builder constructs an ordered list of write
       operations that MongoDB executes in bulk.

   * - :method:`db.collection.initializeUnorderedBulkOp()`

     - Initializes and returns a new :method:`Bulk()` operations builder
       for a collection. The builder constructs an unordered list of write
       operations that MongoDB executes in bulk.
   
   * - :method:`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 :method:`db.collection.initializeOrderedBulkOp()`
       or the :method:`db.collection.initializeUnorderedBulkOp()` method.

   * - :method:`Bulk.execute()`

     - Executes the list of operations built by the :method:`Bulk()`
       operations builder.

   * - :method:`Bulk.find()`

     - Specifies a query condition for an update or a remove operation.

   * - :method:`Bulk.find.hint()`

     - Sets the **hint** option that specifies the index to support the
       bulk operation.

   * - :method:`Bulk.find.remove()`

     - Adds a remove operation to a bulk operations list.

   * - :method:`Bulk.find.removeOne()`

     - Adds a single document remove operation to a bulk operations list.

   * - :method:`Bulk.find.replaceOne()`

     - Adds a single document replacement operation to a bulk operations
       list.

   * - :method:`Bulk.find.updateOne()`

     - Adds a single document update operation to a bulk operations list.

   * - :method:`Bulk.find.update()`

     - Adds a **multi** update operation to a bulk operations list. The
       method updates specific fields in existing documents.

   * - :method:`Bulk.find.upsert()`

     - Sets the :manual:`upsert </reference/glossary/#term-upsert>` option
       to ``true`` for an update or a replacement operation.

   * - :method:`Bulk.getOperations()`

     - Returns an array of write operations executed through
       :method:`Bulk.execute()`.

   * - :method:`Bulk.insert()`
  
     - Adds an insert operation to a bulk operations list.

   * - :method:`Bulk.toJSON()`

     - Returns a JSON document that contains the number of operations and
       batches in the :method:`Bulk()` object.

   * - :method:`Bulk.toString()`

     - Returns as a string a JSON document that contains the number of
       operations and batches in the :method:`Bulk()` object.

.. _mongosh-collection-methods:

Collection Methods
------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.collection.aggregate()`

     - Provides access to the
       :manual:`aggregation pipeline </core/aggregation-pipeline>`.

   * - :method:`db.collection.bulkWrite()`

     - Provides bulk write operation functionality.

       .. convertToCapped

   * - :method:`db.collection.count()`

     - Deprecated in :binary:`~bin.mongosh` 1.0.6. Use
       :method:`db.collection.countDocuments()` or
       :method:`db.collection.estimatedDocumentCount()` instead.

   * - :method:`db.collection.countDocuments()`

     - Returns a count of the number of documents in a collection or a
       view. Wraps the :pipeline:`$group` aggregation stage with a
       :group:`$sum` expression.
   
   * - :method:`db.collection.estimatedDocumentCount()`

     - Returns an approximate count of the documents in a collection or
       a view.

   * - :method:`db.collection.createIndex()`

     - Builds an index on a collection.

   * - :method:`db.collection.createIndexes()`

     - Builds one or more indexes on a collection.

   * - :method:`db.collection.dataSize()`

     - Returns the size of the collection. Wraps the
       :data:`~collStats.size` field in the output of the
       :dbcommand:`collStats`.

   * - :method:`db.collection.deleteOne()`

     - Deletes a single document in a collection.

   * - :method:`db.collection.deleteMany()`

     - Deletes multiple documents in a collection.

   * - :method:`db.collection.distinct()`

     - Returns an array of documents that have distinct values for the
       specified field.

   * - :method:`db.collection.drop()`

     - Removes the specified collection from the database.

   * - :method:`db.collection.dropIndex()`

     - Removes a specified index on a collection.

   * - :method:`db.collection.dropIndexes()`

     - Removes all indexes on a collection.

   * - :method:`db.collection.ensureIndex()`

     - Deprecated. Use :method:`db.collection.createIndex()`.

       .. exists

   * - :method:`db.collection.explain()`

     - Returns information on the query execution of various methods.

   * - :method:`db.collection.find()`

     - Performs a query on a collection or a view and returns a cursor
       object.

   * - :method:`db.collection.findAndModify()`

     - Atomically modifies and returns a single document.

   * - :method:`db.collection.findOne()`

     - Performs a query and returns a single document.

   * - :method:`db.collection.findOneAndDelete()`

     - Finds a single document and deletes it.

   * - :method:`db.collection.findOneAndReplace()`

     - Finds a single document and replaces it.

   * - :method:`db.collection.findOneAndUpdate()`

     - Finds a single document and updates it.

   * - :method:`db.collection.getIndexes()`

     - Returns an array of documents that describe the existing indexes
       on a collection.

       .. getIndexKeys

       .. getIndexSpecs

   * - :method:`db.collection.getShardDistribution()`

     - Prints the data distribution statistics for a sharded collection.

   * - :method:`db.collection.getShardVersion()`

     - Returns information regarding the state of data in a sharded 
       cluster.

   * - :method:`db.collection.insertOne()`

     - Inserts a new document in a collection.

   * - :method:`db.collection.insertMany()`

     - Inserts several new document in a collection.

   * - :method:`db.collection.isCapped()`

     - Reports if a collection is a :term:`capped collection`.

   * - :method:`db.collection.mapReduce()`
     
     - Runs :term:`map-reduce` aggregation operations on a collection.

   * - :method:`db.collection.reIndex()`

     - Rebuilds all existing indexes on a collection.

   * - :method:`db.collection.renameCollection()`

     - Changes the name of a collection.

   * - :method:`db.collection.replaceOne()`

     - Replaces a single document in a collection.

   * - :method:`db.collection.stats()`

     - Reports on the state of a collection. Provides a wrapper around
       the :dbcommand:`collStats`.

   * - :method:`db.collection.storageSize()`

     - Reports the total size used by the collection in bytes. Provides
       a wrapper around the :data:`~collStats.storageSize` field of the
       :dbcommand:`collStats` output.

   * - :method:`db.collection.totalIndexSize()`

     - Reports the total size used by the indexes on a collection.
       Provides a wrapper around the :data:`~collStats.totalIndexSize`
       field of the :dbcommand:`collStats` output.

   * - :method:`db.collection.totalSize()`

     - Reports the total size of a collection, including the size of
       all documents and all indexes on a collection.

   * - :method:`db.collection.updateOne()`

     - Modifies a single document in a collection.

   * - :method:`db.collection.updateMany()`

     - Modifies multiple documents in a collection.

   * - :method:`db.collection.validate()`
     
     - Validates a collection.

   * - :method:`db.collection.watch()`

     - Opens a :manual:`change stream cursor </changeStreams>` on the
       collection.

Connection Methods
------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`Mongo()`

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

       The :method:`Mongo()` method has the following parameters:

       .. list-table::
           :header-rows: 1
           :widths: 20 20 80

           * - Parameter
       
             - Type
       
             - Description
       
           * - ``host``
       
             - string
       
             - *Optional*
             
               The connection string for the target database
               connection.

               If omitted, :method:`Mongo` instantiates a connection to the 
               localhost interface on the default port ``27017``.

           * - ``autoEncryptionOpts``
             
             - Document

             - *Optional* 
               
               .. versionadded:: 4.2

               Configuration parameters for enabling
               :manual:`Client-Side Field Level Encryption
               </core/security-client-side-encryption>`.

               ``autoEncryptionOpts`` overrides the
               existing client-side field level encryption configuration of
               the database connection. If omitted, :method:`Mongo()`
               inherits the client-side field level encryption configuration
               of the current database connection.

               For documentation of usage and syntax, see
               :ref:`autoEncryptionOpts`.

   * - :method:`Mongo.getDB()`

     - Returns a database object.

   * - :method:`Mongo.setReadPref()`

     - Sets the :term:`read preference` for the MongoDB connection.

   * - :method:`Mongo.watch()`

     - Opens a :manual:`change stream cursor </changeStreams>` 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.

.. _mongosh-cursor-methods:

Cursor Methods
--------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`cursor.addOption()`

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

   * - :method:`cursor.allowPartialResults()`

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

       .. arrayAccess

   * - :method:`cursor.batchSize()`
     - Specifies the maximum number of documents MongoDB will return to the client 
       within each batch returned in a query result. By default, the initial batch 
       size is ``101`` documents and subsequent batches have a maximum 
       size of 16 mebibytes (MiB). This option can enforce a smaller
       limit than 16 MiB, but not a larger one. If you set ``batchSize`` 
       to a limit that results in batches larger than 16 MiB, this option has no effect.

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

       The following example query returns results in batches of
       100: 

       .. code-block:: sh

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

   * - :method:`cursor.close()`

     - Close a cursor and free associated server resources.

   * - :method:`cursor.collation()`

     - Specifies the collation for the cursor returned by the
       :method:`db.collection.find()`.

   * - :method:`cursor.comment()`

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

   * - :method:`cursor.count()`

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

   * - :method:`cursor.explain()`

     - Reports on the query execution plan for a cursor.

   * - :method:`cursor.forEach()`

     - Applies a JavaScript function for every document in a cursor.

   * - :method:`cursor.hasNext()`

     - Returns ``true`` if the cursor has documents and can be iterated.

   * - :method:`cursor.hint()`

     - Forces MongoDB to use a specific index for a query.

   * - :method:`cursor.isClosed()`

     - Returns ``true`` if the cursor is closed.

   * - :method:`cursor.isExhausted()`

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

   * - :method:`cursor.itcount()`

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

   * - :method:`cursor.limit()`

     - Constrains the size of a cursor's result set.

   * - :method:`cursor.map()`

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

   * - :method:`cursor.max()`

     - Specifies an exclusive upper index bound for a cursor. For use
       with :method:`cursor.hint()`

   * - :method:`cursor.maxTimeMS()`

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

   * - :method:`cursor.min()`

     - Specifies an inclusive lower index bound for a cursor. For use
       with :method:`cursor.hint()`

   * - :method:`cursor.next()`

     - Returns the next document in a cursor.

   * - :method:`cursor.noCursorTimeout()`

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

       .. oplogReplay

       .. projection

   * - :method:`cursor.objsLeftInBatch()`

     - Returns the number of documents left in the current cursor batch.

   * - :method:`cursor.readConcern()`

     - Specifies a :term:`read concern` for a
       :method:`db.collection.find()` operation.

   * - :method:`cursor.readPref()`

     - Specifies a :term:`read preference` to a cursor to control how
       the client directs queries to a :term:`replica set`.

   * - :method:`cursor.returnKey()`

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

   * - :method:`cursor.showRecordId()`

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

   * - :method:`cursor.size()`

     - Returns a count of the documents in the cursor after applying
       :method:`~cursor.skip()` and :method:`~cursor.limit()` methods.

   * - :method:`cursor.skip()`

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

   * - :method:`cursor.sort()`

     - Returns results ordered according to a sort specification.

   * - :method:`cursor.tailable()`

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

   * - :method:`cursor.toArray()`

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

.. _mongosh-database-methods:

Database Methods
----------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.aggregate()`

     - Runs admin/diagnostic pipeline which does not require an
       underlying collection.
     
   * - :method:`db.createCollection()`
     
     - Creates a new collection or view.

   * - :method:`db.createView()`

     - Creates a view as the result of applying the specified
       aggregation pipeline to the source collection or view.

   * - :method:`db.commandHelp()`

     - Displays help text for the specified database command.

   * - :method:`db.dropDatabase()`

     - Removes the current database.

   * - :method:`db.getCollection()`

     - Returns a collection or view object. Used to access collections
       with names that are not valid in the :binary:`~bin.mongo` shell.

   * - :method:`db.getCollectionInfos()`

     - Returns collection information for all collections and views in
       the current database.

   * - :method:`db.getCollectionNames()`

     - Lists all collections and views in the current database.

   * - :method:`db.getMongo()`

     - Returns the current database connection.

   * - :method:`db.getLogComponents()`

     - Returns the current log verbosity settings.

   * - :method:`db.getName()`

     - Returns the name of the current database.

   * - :method:`db.getProfilingStatus()`

     - Returns the current :manual:`profile level
       </reference/command/profile/#dbcmd.profile>`, :manual:`slowOpThresholdMs
       </reference/configuration-options/#operationProfiling.slowOpThresholdMs>`
       setting, and :manual:`slowOpSampleRate
       </reference/configuration-options/#operationProfiling.slowOpSampleRate>`
       setting.

   * - :method:`db.getSiblingDB()`

     - Provides access to the specified database.

   * - :method:`db.listCommands()`

     - Provides a list of all database commands.

   * - :method:`db.logout()`

     - Ends an authenticated session.

   * - :method:`db.printShardingStatus()`

     - Prints a formatted report of the sharding configuration and the
       information regarding existing chunks in a sharded cluster.

   * - :method:`db.runCommand()`

     - Runs a :manual:`database command </reference/command>`.

   * - :method:`db.setLogLevel()`

     - Sets a single verbosity level for :manual:`log messages
       </reference/log-messages/>`.

   * - :method:`db.setProfilingLevel()`
     
     - Configures the database :manual:`profiler level
       </reference/method/db.setProfilingLevel/#set-profiling-level-level>`,
       :manual:`slowms
       </reference/method/db.setProfilingLevel/#set-profiling-level-options-slowms>`,
       and :manual:`sampleRate
       </reference/method/db.setProfilingLevel/#set-profiling-level-options-samplerate>`.

   * - :method:`db.watch()`

     - Opens a :manual:`change stream cursor </change-streams>` for a
       database to report on all its non-system collections.

.. _fle-methods-mongosh:

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 :manual:`Automatic Client-Side Field Level Encryption
     </core/security-automatic-client-side-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 :compass:`embedded Compass shell
     </embedded-shell>`. 

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - Method

     - Description

   * - :upcoming:`ClientEncryption.createEncryptedCollection() 
       </reference/method/ClientEncryption.createEncryptedCollection>`

     - Creates a collection with encrypted fields.

   * - :method:`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``.

   * - :method:`ClientEncryption.encrypt()`

     - Encrypts the specified value using the specified ``encryptionKeyId``
       and ``encryptionAlgorithm``.

   * - :method:`getClientEncryption()`

     - Returns the ``ClientEncryption`` object for the current database
       collection.

   * - :method:`getKeyVault()`

     - Returns the ``KeyVault`` object for the current database connection. 

   * - :method:`KeyVault.addKeyAlternateName()`

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

   * - :method:`KeyVault.createKey()`

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

   * - :method:`KeyVault.deleteKey()`

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

   * - :method:`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.

   * - :method:`KeyVault.getKeyByAltName()`

     - Gets all data encryption keys with the specified ``keyAltName``.

   * - :method:`KeyVault.getKeys()`

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

   * - :method:`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
--------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - .. _mongosh-native-method-buildInfo():

       ``buildInfo()``

     - .. include:: /includes/examples/ex-build-info-command.rst

   * - .. _mongosh-native-method-cd:

       ``cd()``

     - Changes the current working directory to the specified path.

   * - .. _mongosh-native-method-isInteractive:

       ``isInteractive()``

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

   * - .. _mongosh-native-method-load:

       ``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.

       .. include:: /includes/legacy/legacy-load-method.rst

   * - .. _mongosh-native-method-print:  

       ``print()``

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

       .. code-block:: code

          > print("hello world")
          hello world

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

   * - .. _mongosh-native-method-pwd:

       ``pwd()``

     - Returns the current working directory of the active shell session.

   * - .. _mongosh-native-method-quit:

       ``quit()``
     
     - Exits the current shell session.

   * - .. _mongosh-native-method-sleep: 

       ``sleep()``
 
     - Suspends the |mongo| shell for a given period of time.


   * - .. _mongosh-native-method-version:

       ``version()``
    
     - Returns the current version of the ``mongosh`` instance.

Query Plan Cache Methods
------------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.collection.getPlanCache()`

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

   * - :method:`PlanCache.clear()`

     - Removes all cached query plans for a collection.

   * - :method:`PlanCache.clearPlansByQuery()`

     - Clears the cached query plans for the specified 
       :term:`query shape`.

   * - :method:`PlanCache.help()`

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

   * - :method:`PlanCache.list()`

     - Returns an array of 
       :manual:`plan cache entries </core/query-plans/>` 
       for a collection.

.. _mongosh-replication-methods:

Replication Methods 
-------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`rs.add()`

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

   * - :method:`rs.addArb()`

     - Adds an arbiter to an existing replica set.

   * - :method:`rs.config()`

     - Returns a document that contains the current replica set configuration.

   * - :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.

   * - :method:`db.getReplicationInfo()`

     - Returns the status of the replica set from the oplog data.

   * - :method:`rs.initiate()`

     - Initializes a new replica set.

   * - :method:`db.printReplicationInfo()`

     - Returns the oplog of the replica set member that ``mongosh`` is 
       connected to. 
       
   * - :method:`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:

       .. code-block:: sh 
          :copyable: false 

          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:

       .. code-block:: sh 
          :copyable: false 

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

   * - :manual:`rs.reconfig() </reference/command/replSetReconfig/>`

     - Modifies the configuration of an existing replica set.

   * - :method:`rs.remove()`

     - Removes the member specified by hostname from the replica set.

   * - :method:`rs.status()`

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

   * - :method:`rs.stepDown()`

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

   * - :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.

.. _mongosh-role-management-methods:

Role Management Methods 
-----------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description
 
   * - :method:`db.createRole()`

     - Creates a role and specifies its privileges.

   * - :method:`db.dropRole()`

     - Deletes a user-defined role.

   * - :method:`db.dropAllRoles()`

     - Deletes all user-defined roles associated with a database.

   * - :method:`db.getRole()`

     - Returns information for the specified role.

   * - :method:`db.getRoles()`

     - Returns information for all the user-defined roles in a
       database. 

   * - :method:`db.grantPrivilegesToRole()`

     - Assigns privileges to a user-defined role.
   
   * - :method:`db.revokePrivilegesFromRole()`

     - Removes the specified privileges from a user-defined role.
   
   * - :method:`db.grantRolesToRole()`

     - Specifies roles from which a user-defined role inherits
       privileges.
   
   * - :method:`db.revokeRolesFromRole()`

     - Removes inherited roles from a role.

   * - :method:`db.updateRole()`

     - Updates a user-defined role.

Session Object Methods
----------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`Mongo.startSession()`

     - Starts a session for the connection.

   * - :manual:`Session.advanceOperationTime() </reference/method/Session>`

     - Updates the operation time.

   * - :manual:`Session.endSession() </reference/method/Session>`

     - Ends the session.

   * - :manual:`Session.getClusterTime() </reference/method/Session>`

     - Returns the most recent cluster time as seen by the session. 

   * - :manual:`Session.getDatabase() </reference/method/Session>`

     - Access the specified database from the session in the shell.

   * - :manual:`Session.getOperationTime() </reference/method/Session>`

     - Returns the timestamp of the last acknowledged operation for the
       session.

   * - :manual:`Session.getOptions() </reference/method/Session>`

     - Returns the options for the session. 

   * - :manual:`Session.hasEnded() </reference/method/Session>`

     - Returns a boolean that specifies whether the session has ended.

   * - :method:`SessionOptions()`

     - The options for a session in the shell. To access the
       :method:`SessionOptions()` object, use :method:`Session.getOptions()`. 

.. _mongosh-server-status-methods:

Server Status Methods
---------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.hello()`

     - Returns a document that describes the role of the
       :binary:`~bin.mongod` instance.

       If the :binary:`~bin.mongod` is a member of a
       replica set, then the :data:`~hello.isWritablePrimary` and
       :data:`~hello.secondary` fields report if the instance is the
       :term:`primary` or if it is a :term:`secondary` member of the
       replica set.

   * - :method:`db.hostInfo()`

     - Returns a document with information about the system running
       the MongoDB instance.

   * - :method:`db.collection.latencyStats()`

     - Returns latency statistics for a specified collection.

   * - :method:`db.printCollectionStats()`

     - Returns statistics from every collection.

   * - :method:`db.serverBuildInfo()`

     - Returns a document that displays the compilation parameters for
       the :binary:`~bin.mongod` instance.

   * - :method:`db.serverCmdLineOpts()`

     - Returns a document with information about the runtime options
       used to start the MongoDB instance.

   * - :method:`db.serverStatus()`

     - Returns a document that provides an overview of the database
       process.

   * - :method:`db.stats()`

     - Returns a document that reports on the state of the current
       database.

   * - :method:`db.version()`

     - Returns the version of the :binary:`~mongod` instance.

.. _mongosh-sharding-methods:

Sharding Methods
----------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`sh.addShard()`

     - Adds a shard to a sharded cluster.

   * - :method:`sh.addShardTag()`

     - Aliases to :method:`sh.addShardToZone()`.

   * - :method:`sh.addShardToZone()`

     - Associates a shard with a zone. Supports configuring zones in sharded
       clusters.

   * - :method:`sh.addTagRange()`

     - Aliases to :method:`sh.updateZoneKeyRange()`.

   * - :method:`sh.balancerCollectionStatus()`

     - Returns information on whether the chunks of a sharded collection are balanced.

       .. versionadded:: 4.4

   * - :upcoming:`sh.disableAutoMerger()
       </reference/method/sh.disableAutoMerger>`

     - Disables automatic chunk merges for a namespace.
   
       .. versionadded:: 7.0

   * - :method:`sh.disableAutoSplit()`

     - Disables auto-splitting for the sharded cluster.

   * - :method:`sh.disableBalancing()`

     - Disables balancing on a single collection in a sharded
       database. Does not affect balancing of other collections in a sharded cluster.

   * - :upcoming:`sh.enableAutoMerger()
       </reference/method/sh.enableAutoMerger>`

     - Enables automatic chunk merges for a namespace.
   
       .. versionadded:: 7.0

   * - :method:`sh.enableAutoSplit()`

     - Enables auto-splitting for the sharded cluster.

   * - :method:`sh.enableBalancing()`

     - Activates the sharded collection balancer process if
       previously disabled using :method:`sh.disableBalancing()`.

   * - :method:`sh.enableSharding()`

     - Enables sharding on a specific database.

   * - :method:`sh.getBalancerState()`

     - Returns a boolean to report if the :term:`balancer` is currently
       enabled.

   * - :method:`sh.getShardedDataDistribution()`

     - Returns data distribution information for sharded collections.
       ``sh.getShardedDataDistribution()`` is a shell helper method for
       the :pipeline:`$shardedDataDistribution` aggregation pipeline
       stage.

   * - :method:`sh.isBalancerRunning()`

     - Returns a boolean to report if the :term:`balancer` process is
       currently migrating chunks.

   * - :method:`sh.moveChunk()`

     - Migrates a :term:`chunk` in a :term:`sharded cluster`.

   * - :method:`sh.removeRangeFromZone()`

     - Removes the association between a range of shard key values and a
       :term:`zone`.

   * - :method:`sh.removeShardFromZone`

     - Removes the association between a shard and a :term:`zone`.

   * - :method:`sh.removeShardTag()`

     - Removes the association between a tag and a shard.

   * - :method:`sh.removeTagRange()`

     - Removes a range of shard key values to a shard tag created using
       the :method:`sh.addShardTag()` method. This method aliases to
       :method:`sh.removeRangeFromZone()` in MongoDB 3.4.

   * - :method:`sh.setBalancerState()`

     - Enables or disables the :term:`balancer` which migrates
       :term:`chunks <chunk>` between :term:`shards <shard>`.

   * - :method:`sh.shardCollection()`

     - Enables sharding for a collection.

   * - :method:`sh.splitAt()`

     - Divides an existing :term:`chunk` into two chunks using a
       specific value of the :term:`shard key` as the dividing point.

   * - :method:`sh.splitFind()`

     - Divides an existing :term:`chunk` that contains a document
       matching a query into two approximately equal chunks.

   * - :upcoming:`sh.startAutoMerger()
       </reference/method/sh.startAutoMerger>`

     - Enables the AutoMerger.

       .. versionadded:: 7.0

   * - :method:`sh.startBalancer()`

     - Enables the :term:`balancer`.
   
   * - :method:`sh.status()`

     - Reports on the status of a sharded cluster.

   * - :upcoming:`sh.stopAutoMerger()
       </reference/method/sh.stopAutoMerger>`

     - Disables the AutoMerger.

       .. versionadded:: 7.0

   * - :method:`sh.stopBalancer()`

     - Disables the :term:`balancer`. This operation does not wait for
       the balancer to complete any in progress operations, and may
       terminate ongoing operations.

   * - :method:`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 :ref:`telemetry`.

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`disableTelemetry()`

     - Disable telemetry for ``mongosh``. 

   * - :method:`enableTelemetry()`

     - Enable telemetry for ``mongosh``.


Transaction Methods
-------------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`Session.abortTransaction()`

     - Terminates a :manual:`multi-document transaction </core/transactions/>`
       and rolls back any data changes made by the operations within the
       transaction.

   * - :method:`Session.commitTransaction()`

     - Saves the changes made by the operations in a :manual:`multi-document
       transaction </core/transactions/>` and ends the transaction.

   * - :method:`Session.startTransaction()`

     - Starts a :manual:`multi-document transaction </core/transactions/>`
       associated with the session.

.. _mongosh-user-management-methods:

User Management Methods
-----------------------

.. important::

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

   - :method:`db.auth()`
   - :method:`db.changeUserPassword()`
   - :method:`db.createUser()`
   - :method:`db.updateUser()`

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method

     - Description

   * - :method:`db.auth()`

     - Authenticates a user to a database.

   * - :method:`db.changeUserPassword()`

     - Changes an existing user’s password.

   * - :method:`db.createUser()`

     - Creates a new user.

   * - :method:`db.dropAllUsers()`

     - Deletes all users associated with a database.

   * - :method:`db.dropUser()`

     - Deletes a single user.

   * - :method:`db.getUser()`

     - Returns information about the specified user.

   * - :method:`db.getUsers()`

     - Returns information about all users associated with a database.

   * - :method:`db.updateUser()`

     - Updates a specified user's data.

   * - :method:`db.grantRolesToUser()`

     - Grants a role and its privileges to a user.

   * - :method:`db.revokeRolesFromUser()`

     - Removes a role from a user.