Install MongoDB

MongoDB runs on most platforms and supports both 32-bit and 64-bit architectures.

Installation Guides

See the Release Notes for information about specific releases of MongoDB.

Install on Linux

Documentations for installing the official MongoDB distribution on Linux-based systems.

Install on Red Hat

Install MongoDB on Red Hat Enterprise and related Linux systems using .rpm packages.

Install on Ubuntu

Install MongoDB on Ubuntu Linux systems using .deb packages.

Install on Debian

Install MongoDB on Debian systems using .deb packages.

Install on Other Linux Systems

Install the official build of MongoDB on other Linux systems from MongoDB archives.

Install on OS X

Install the official build of MongoDB on OS X systems from Homebrew packages or from MongoDB archives.

Install on Windows

Install MongoDB on Windows systems and optionally start MongoDB as a Windows service.

Install MongoDB Enterprise

MongoDB Enterprise is available for MongoDB Enterprise subscribers and includes several additional features including support for SNMP monitoring, LDAP authentication, Kerberos authentication, and System Event Auditing.

Install MongoDB Enterprise on Red Hat

Install the MongoDB Enterprise build and required dependencies on Red Hat Enterprise or CentOS Systems using packages.

Install MongoDB Enterprise on Ubuntu

Install the MongoDB Enterprise build and required dependencies on Ubuntu Linux Systems using packages.

Install MongoDB Enterprise on Amazon AMI

Install the MongoDB Enterprise build and required dependencies on Amazon Linux AMI.

Install MongoDB Enterprise on Windows

Install the MongoDB Enterprise build and required dependencies using the .msi installer.

Install on Linux

Install on Red Hat

Install on Ubuntu

Install on Debian

Install on Other Linux Systems

Install on OS X

Install on Windows

Install MongoDB Enterprise

Install MongoDB Enterprise on Red Hat

Install MongoDB Enterprise on Ubuntu

Install MongoDB Enterprise on Debian

Install MongoDB Enterprise on SUSE

Install MongoDB Enterprise on Amazon AMI

Install MongoDB Enterprise on Windows

Verify Integrity of MongoDB Packages

First Steps with MongoDB

After you have installed MongoDB, consider the following documents as you begin to learn about MongoDB:

Getting Started with MongoDB

An introduction to the basic operation and use of MongoDB.

Generate Test Data

To support initial exploration, generate test data to facilitate testing.

Getting Started with MongoDB

Generate Test Data

See also

MongoDB CRUD Concepts and Data Models.

Additional Resources

Install MongoDB using MMS [https://docs.mms.mongodb.com/tutorial/getting-started]: MongoDB Management Service is cloud managed MongoDB on the infrastructure of your choice.

MongoDB CRUD Concepts

Data Models

Install on Linux

These documents provide instructions to install MongoDB for various Linux systems.

Recommended

For easy installation, MongoDB provides packages for popular Linux distributions. The following guides detail the installation process for these systems:

Install on Red Hat

Install MongoDB on Red Hat Enterprise and related Linux systems using .rpm packages.

Install on Ubuntu

Install MongoDB on Ubuntu Linux systems using .deb packages.

Install on Debian

Install MongoDB on Debian systems using .deb packages.

For systems without supported packages, refer to the Manual Installation tutorial.

Manual Installation

For Linux systems without supported packages, see the following guide:

Install on Other Linux Systems

Install the official build of MongoDB on other Linux systems from MongoDB archives.

Install on Red Hat

Install on Ubuntu

Install on Debian

Install on Other Linux Systems

Install MongoDB on Red Hat Enterprise or CentOS Linux

Overview

Use this tutorial to install MongoDB on Red Hat Enterprise Linux CentOS Linux using .rpm packages. While some of these distributions include their own MongoDB packages, the official MongoDB packages are generally more up to date.

Packages

MongoDB provides packages of the officially supported MongoDB builds in its own repository. This repository provides the MongoDB distribution in the following packages:

mongodb-org

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-org-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-org-mongos

This package contains the mongos daemon.

mongodb-org-shell

This package contains the mongo shell.

mongodb-org-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-org package includes various control scripts, including the init script /etc/rc.d/init.d/mongod. These scripts are used to stop, start, and restart daemon processes.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script for use in such environments. See the mongos reference for configuration details.

Considerations

For production deployments, always run MongoDB on 64-bit systems.

The default /etc/mongod.conf configuration file supplied by the 2.6 series packages has bind_ip` set to 127.0.0.1 by default. Modify this setting as needed for your environment before initializing a replica set.

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

Install MongoDB

Run MongoDB

Important

You must configure SELinux to allow MongoDB to start on Red Hat Linux-based systems (Red Hat Enterprise Linux or CentOS Linux). Administrators have three options:

enable access to the relevant ports (e.g. 27017) for SELinux. See Default MongoDB Port for more information on MongoDB’s default ports. For default settings, this can be accomplished by running

semanage port -a -t mongod_port_t -p tcp 27017

set SELinux to permissive mode in /etc/selinux.conf. The line

SELINUX=enforcing

should be changed to

SELINUX=permissive

disable SELinux entirely; as above but set

SELINUX=disabled

All three options require root privileges. The latter two options each requires a system reboot and may have larger implications for your deployment.

You may alternatively choose not to install the SELinux packages when you are installing your Linux operating system, or choose to remove the relevant packages. This option is the most invasive and is not recommended.

The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongo and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

You can start the mongod process by issuing the following command:

sudo service mongod start

Step 1: Start MongoDB.

You can start the mongod process by issuing the following command:

sudo service mongod start

2

Verify that MongoDB has started successfully

You can verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:

sudo chkconfig mongod on

Step 2: Verify that MongoDB has started successfully

You can verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:

sudo chkconfig mongod on

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

You can restart the mongod process by issuing the following command:

sudo service mongod restart

You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.log file.

Step 4: Restart MongoDB.

You can restart the mongod process by issuing the following command:

sudo service mongod restart

You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.log file.

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB on Ubuntu

Overview

Use this tutorial to install MongoDB on Ubuntu Linux systems from .deb packages. While Ubuntu includes its own MongoDB packages, the official MongoDB packages are generally more up-to-date.

Note

If you use an older Ubuntu that does not use Upstart (i.e. any version before 9.10 “Karmic”), please follow the instructions on the Install MongoDB on Debian tutorial.

Packages

MongoDB provides packages of the officially supported MongoDB builds in its own repository. This repository provides the MongoDB distribution in the following packages:

mongodb-org

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-org-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-org-mongos

This package contains the mongos daemon.

mongodb-org-shell

This package contains the mongo shell.

mongodb-org-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-org package includes various control scripts, including the init script /etc/init.d/mongod. These scripts are used to stop, start, and restart daemon processes.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script for use in such environments. See the mongos reference for configuration details.

Considerations

For production deployments, always run MongoDB on 64-bit systems.

You cannot install this package concurrently with the mongodb, mongodb-server, or mongodb-clients packages provided by Ubuntu.

The default /etc/mongod.conf configuration file supplied by the 2.6 series packages has bind_ip` set to 127.0.0.1 by default. Modify this setting as needed for your environment before initializing a replica set.

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

Install MongoDB

1

Import the public key used by the package management system.

The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc]:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10

Step 1: Import the public key used by the package management system.

The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc]:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10

2

Create a list file for MongoDB.

Create the /etc/apt/sources.list.d/mongodb.list list file using the following command:

echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list

Step 2: Create a list file for MongoDB.

Create the /etc/apt/sources.list.d/mongodb.list list file using the following command:

echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list

3

Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

Step 3: Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

4

Install the MongoDB packages.

You can install either the latest stable version of MongoDB or a specific version of MongoDB.

Install the latest stable version of MongoDB.

Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo apt-get install -y mongodb-org=2.6.1 mongodb-org-server=2.6.1 mongodb-org-shell=2.6.1 mongodb-org-mongos=2.6.1 mongodb-org-tools=2.6.1

Pin a specific version of MongoDB.

Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections
echo "mongodb-org-server hold" | sudo dpkg --set-selections
echo "mongodb-org-shell hold" | sudo dpkg --set-selections
echo "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu].

Step 4: Install the MongoDB packages.

You can install either the latest stable version of MongoDB or a specific version of MongoDB.

Install the latest stable version of MongoDB.

Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo apt-get install -y mongodb-org=2.6.1 mongodb-org-server=2.6.1 mongodb-org-shell=2.6.1 mongodb-org-mongos=2.6.1 mongodb-org-tools=2.6.1

Pin a specific version of MongoDB.

Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections
echo "mongodb-org-server hold" | sudo dpkg --set-selections
echo "mongodb-org-shell hold" | sudo dpkg --set-selections
echo "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu].

Run MongoDB

The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodb and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

Step 1: Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

2

Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

Step 2: Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

Step 4: Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB on Debian

Overview

Use this tutorial to install MongoDB on Debian systems from .deb packages. While some Debian distributions include their own MongoDB packages, the official MongoDB packages are generally more up to date.

Note

This tutorial applies to both Debian systems and versions of Ubuntu Linux prior to 9.10 “Karmic” which do not use Upstart. Other Ubuntu users will want to follow the Install MongoDB on Ubuntu tutorial.

Packages

MongoDB provides packages of the officially supported MongoDB builds in its own repository. This repository provides the MongoDB distribution in the following packages:

mongodb-org

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-org-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-org-mongos

This package contains the mongos daemon.

mongodb-org-shell

This package contains the mongo shell.

mongodb-org-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-org package includes various control scripts, including the init script /etc/init.d/mongod. These scripts are used to stop, start, and restart daemon processes.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script for use in such environments. See the mongos reference for configuration details.

Considerations

For production deployments, always run MongoDB on 64-bit systems.

You cannot install this package concurrently with the mongodb, mongodb-server, or mongodb-clients packages that your release of Debian may include.

The default /etc/mongod.conf configuration file supplied by the 2.6 series packages has bind_ip` set to 127.0.0.1 by default. Modify this setting as needed for your environment before initializing a replica set.

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

Install MongoDB

The Debian package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys.

1

Import the public key used by the package management system.

Issue the following command to add the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc] to the system key ring.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

Step 1: Import the public key used by the package management system.

Issue the following command to add the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc] to the system key ring.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

2

Create a /etc/apt/sources.list.d/mongodb.list file for MongoDB.

Create the list file using the following command:

echo 'deb http://downloads-distro.mongodb.org/repo/debian-sysvinit dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list

Step 2: Create a /etc/apt/sources.list.d/mongodb.list file for MongoDB.

Create the list file using the following command:

echo 'deb http://downloads-distro.mongodb.org/repo/debian-sysvinit dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list

3

Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

Step 3: Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

4

Install the MongoDB packages.

You can install either the latest stable version of MongoDB or a specific version of MongoDB.

Install the latest stable version of MongoDB.

Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo apt-get install -y mongodb-org=2.6.1 mongodb-org-server=2.6.1 mongodb-org-shell=2.6.1 mongodb-org-mongos=2.6.1 mongodb-org-tools=2.6.1

Pin a specific version of MongoDB.

Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections
echo "mongodb-org-server hold" | sudo dpkg --set-selections
echo "mongodb-org-shell hold" | sudo dpkg --set-selections
echo "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu].

Step 4: Install the MongoDB packages.

You can install either the latest stable version of MongoDB or a specific version of MongoDB.

Install the latest stable version of MongoDB.

Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo apt-get install -y mongodb-org=2.6.1 mongodb-org-server=2.6.1 mongodb-org-shell=2.6.1 mongodb-org-mongos=2.6.1 mongodb-org-tools=2.6.1

Pin a specific version of MongoDB.

Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections
echo "mongodb-org-server hold" | sudo dpkg --set-selections
echo "mongodb-org-shell hold" | sudo dpkg --set-selections
echo "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu].

Run MongoDB

The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodb and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

Step 1: Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

2

Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

Step 2: Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

Step 4: Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB on Linux Systems

Overview

Compiled versions of MongoDB for Linux provide a simple option for installing MongoDB for other Linux systems without supported packages.

Considerations

For production deployments, always run MongoDB on 64-bit systems.

Install MongoDB

MongoDB provides archives for both 64-bit and 32-bit Linux. Follow the installation procedure appropriate for your system.

Install for 64-bit Linux

1

Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following:

curl -O http://downloads.mongodb.org/linux/mongodb-linux-x86_64-2.6.8.tgz

Step 1: Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following:

curl -O http://downloads.mongodb.org/linux/mongodb-linux-x86_64-2.6.8.tgz

2

Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-linux-x86_64-2.6.8.tgz

Step 2: Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-linux-x86_64-2.6.8.tgz

3

Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-linux-x86_64-2.6.8/ mongodb

Step 3: Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-linux-x86_64-2.6.8/ mongodb

4

Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Step 4: Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Install for 32-bit Linux

1

Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following: .. include:: /includes/release/curl-release-linux-i686.rst

Step 1: Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following: .. include:: /includes/release/curl-release-linux-i686.rst

2

Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-linux-i686-2.6.8.tgz

Step 2: Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-linux-i686-2.6.8.tgz

3

Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-linux-i686-2.6.8/ mongodb

Step 3: Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-linux-i686-2.6.8/ mongodb

4

Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Step 4: Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Run MongoDB

1

Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 1: Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

2

Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 2: Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

3

Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

Step 3: Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB on OS X

Overview

Use this tutorial to install MongoDB on OS X systems.

Platform Support

Starting in version 2.4, MongoDB only supports OS X versions 10.6 (Snow Leopard) on Intel x86-64 and later.

MongoDB is available through the popular OS X package manager Homebrew [http://brew.sh/] or through the MongoDB Download site [http://www.mongodb.org/downloads].

Install MongoDB

You can install MongoDB with Homebrew [http://brew.sh/] or manually. This section describes both.

Install MongoDB with Homebrew

Homebrew [http://brew.sh/] installs binary packages based on published “formulae.” This section describes how to update brew to the latest packages and install MongoDB. Homebrew requires some initial setup and configuration, which is beyond the scope of this document.

1

Update Homebrew’s package database.

In a system shell, issue the following command:

brew update

Step 1: Update Homebrew’s package database.

In a system shell, issue the following command:

brew update

2

Install MongoDB.

You can install MongoDB via brew with several different options. Use one of the following operations:

Install the MongoDB Binaries

To install the MongoDB binaries, issue the following command in a system shell:

brew install mongodb

Build MongoDB from Source with SSL Support

To build MongoDB from the source files and include SSL support, issue the following from a system shell:

brew install mongodb --with-openssl

Install the Latest Development Release of MongoDB

To install the latest development release for use in testing and development, issue the following command in a system shell:

brew install mongodb --devel

Step 2: Install MongoDB.

You can install MongoDB via brew with several different options. Use one of the following operations:

Install the MongoDB Binaries

To install the MongoDB binaries, issue the following command in a system shell:

brew install mongodb

Build MongoDB from Source with SSL Support

To build MongoDB from the source files and include SSL support, issue the following from a system shell:

brew install mongodb --with-openssl

Install the Latest Development Release of MongoDB

To install the latest development release for use in testing and development, issue the following command in a system shell:

brew install mongodb --devel

Install MongoDB Manually

Only install MongoDB using this procedure if you cannot use homebrew.

1

Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following:

curl -O http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.8.tgz

Step 1: Download the binary files for the desired release of MongoDB.

Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following:

curl -O http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.8.tgz

2

Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-osx-x86_64-2.6.8.tgz

Step 2: Extract the files from the downloaded archive.

For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-osx-x86_64-2.6.8.tgz

3

Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-osx-x86_64-2.6.8/ mongodb

Step 3: Copy the extracted archive to the target directory.

Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb
cp -R -n mongodb-osx-x86_64-2.6.8/ mongodb

4

Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Step 4: Ensure the location of the binaries is in the PATH variable.

The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Run MongoDB

1

Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 1: Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

2

Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 2: Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

3

Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

Step 3: Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB on Windows

Overview

Use this tutorial to install MongoDB on a Windows systems.

Platform Support

Starting in version 2.2, MongoDB does not support Windows XP. Please use a more recent version of Windows to use more recent releases of MongoDB.

Important

If you are running any edition of Windows Server 2008 R2 or Windows 7, please install a hotfix to resolve an issue with memory mapped files on Windows [http://support.microsoft.com/kb/2731284].

Requirements

On Windows MongoDB requires Windows Server 2008 R2, Windows Vista, or later. The MSI installer includes all other software dependencies.

Install MongoDB

1

Determine which MongoDB build you need.

There are three builds of MongoDB for Windows:

MongoDB for Windows 64-bit runs only on Windows Server 2008 R2, Windows 7 64-bit, and newer versions of Windows. This build takes advantage of recent enhancements to the Windows Platform and cannot operate on older versions of Windows.

MongoDB for Windows 32-bit runs on any 32-bit version of Windows newer than Windows Vista. 32-bit versions of MongoDB are only intended for older systems and for use in testing and development systems. 32-bit versions of MongoDB only support databases smaller than 2GB.

MongoDB for Windows 64-bit Legacy runs on Windows Vista, Windows Server 2003, and Windows Server 2008 and does not include recent performance enhancements.

To find which version of Windows you are running, enter the following command in the Command Prompt:

wmic os get osarchitecture

Step 1: Determine which MongoDB build you need.

There are three builds of MongoDB for Windows:

MongoDB for Windows 64-bit runs only on Windows Server 2008 R2, Windows 7 64-bit, and newer versions of Windows. This build takes advantage of recent enhancements to the Windows Platform and cannot operate on older versions of Windows.

MongoDB for Windows 32-bit runs on any 32-bit version of Windows newer than Windows Vista. 32-bit versions of MongoDB are only intended for older systems and for use in testing and development systems. 32-bit versions of MongoDB only support databases smaller than 2GB.

MongoDB for Windows 64-bit Legacy runs on Windows Vista, Windows Server 2003, and Windows Server 2008 and does not include recent performance enhancements.

To find which version of Windows you are running, enter the following command in the Command Prompt:

wmic os get osarchitecture

2

Download MongoDB for Windows.

Download the latest production release of MongoDB from the MongoDB downloads page [http://www.mongodb.org/downloads]. Ensure you download the correct version of MongoDB for your Windows system. The 64-bit versions of MongoDB does not work with 32-bit Windows.

Step 2: Download MongoDB for Windows.

Download the latest production release of MongoDB from the MongoDB downloads page [http://www.mongodb.org/downloads]. Ensure you download the correct version of MongoDB for your Windows system. The 64-bit versions of MongoDB does not work with 32-bit Windows.

3

Install the downloaded file.

In Windows Explorer, locate the downloaded MongoDB msi file, which typically is located in the default Downloads folder. Double-click the msi file. A set of screens will appear to guide you through the installation process.

You may specify an installation directory if you choose the “Custom” installation option. These instructions assume that you have installed MongoDB to C:\mongodb.

MongoDB is self-contained and does not have any other system dependencies. You can run MongoDB from any folder you choose. You may install MongoDB in any folder (e.g. D:\test\mongodb)

Step 3: Install the downloaded file.

In Windows Explorer, locate the downloaded MongoDB msi file, which typically is located in the default Downloads folder. Double-click the msi file. A set of screens will appear to guide you through the installation process.

You may specify an installation directory if you choose the “Custom” installation option. These instructions assume that you have installed MongoDB to C:\mongodb.

MongoDB is self-contained and does not have any other system dependencies. You can run MongoDB from any folder you choose. You may install MongoDB in any folder (e.g. D:\test\mongodb)

Run MongoDB

Warning

Do not make mongod.exe visible on public networks without running in “Secure Mode” with the auth setting. MongoDB is designed to be run in trusted environments, and the database does not enable “Secure Mode” by default.

1

Set up the MongoDB environment.

MongoDB requires a data directory to store all data. MongoDB’s default data directory path is \data\db. Create this folder using the following commands from a Command Prompt:

md \data\db

You can specify an alternate path for data files using the --dbpath option to mongod.exe, for example:

C:\mongodb\bin\mongod.exe --dbpath d:\test\mongodb\data

If your path includes spaces, enclose the entire path in double quotes, for example:

C:\mongodb\bin\mongod.exe --dbpath "d:\test\mongo db data"

You may also specify the dbpath in a configuration file.

Step 1: Set up the MongoDB environment.

MongoDB requires a data directory to store all data. MongoDB’s default data directory path is \data\db. Create this folder using the following commands from a Command Prompt:

md \data\db

You can specify an alternate path for data files using the --dbpath option to mongod.exe, for example:

C:\mongodb\bin\mongod.exe --dbpath d:\test\mongodb\data

If your path includes spaces, enclose the entire path in double quotes, for example:

C:\mongodb\bin\mongod.exe --dbpath "d:\test\mongo db data"

You may also specify the dbpath in a configuration file.

2

Start MongoDB.

To start MongoDB, run mongod.exe. For example, from the Command Prompt:

C:\mongodb\bin\mongod.exe

This starts the main MongoDB database process. The waiting for connections message in the console output indicates that the mongod.exe process is running successfully.

Depending on the security level of your system, Windows may pop up a Security Alert dialog box about blocking “some features” of C:\mongodb\bin\mongod.exe from communicating on networks. All users should select Private Networks, such as my home or work network and click Allow access. For additional information on security and MongoDB, please see the Security Documentation.

Step 2: Start MongoDB.

To start MongoDB, run mongod.exe. For example, from the Command Prompt:

C:\mongodb\bin\mongod.exe

This starts the main MongoDB database process. The waiting for connections message in the console output indicates that the mongod.exe process is running successfully.

Depending on the security level of your system, Windows may pop up a Security Alert dialog box about blocking “some features” of C:\mongodb\bin\mongod.exe from communicating on networks. All users should select Private Networks, such as my home or work network and click Allow access. For additional information on security and MongoDB, please see the Security Documentation.

3

Connect to MongoDB.

To connect to MongoDB through the mongo.exe shell, open another Command Prompt.

C:\mongodb\bin\mongo.exe

If you want to develop applications using .NET, see the documentation of C# and MongoDB [http://docs.mongodb.org/ecosystem/drivers/csharp] for more information.

Step 3: Connect to MongoDB.

To connect to MongoDB through the mongo.exe shell, open another Command Prompt.

C:\mongodb\bin\mongo.exe

If you want to develop applications using .NET, see the documentation of C# and MongoDB [http://docs.mongodb.org/ecosystem/drivers/csharp] for more information.

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Configure a Windows Service for MongoDB

1

Configure directories and files.

Create a configuration file and a directory path for MongoDB log output (logpath):

Create a specific directory for MongoDB log files:

md "C:\mongodb\log"

In the Command Prompt, create a configuration file for the logpath option for MongoDB:

echo logpath=C:\mongodb\log\mongo.log > "C:\mongodb\mongod.cfg"

Step 1: Configure directories and files.

Create a configuration file and a directory path for MongoDB log output (logpath):

Create a specific directory for MongoDB log files:

md "C:\mongodb\log"

In the Command Prompt, create a configuration file for the logpath option for MongoDB:

echo logpath=C:\mongodb\log\mongo.log > "C:\mongodb\mongod.cfg"

2

Run the MongoDB service.

Run all of the following commands in Command Prompt with “Administrative Privileges:”

Install the MongoDB service. For --install to succeed, you must specify the logpath run-time option.

"C:\mongodb\bin\mongod.exe" --config "C:\mongodb\mongod.cfg" --install

Modify the path to the mongod.cfg file as needed.

To use an alternate dbpath, specify the path in the configuration file (e.g. C:\mongodb\mongod.cfg) or on the command line with the --dbpath option.

If the dbpath directory does not exist, mongod.exe will not start. The default value for dbpath is \data\db.

If needed, you can install services for multiple instances of mongod.exe or mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

Step 2: Run the MongoDB service.

Run all of the following commands in Command Prompt with “Administrative Privileges:”

Install the MongoDB service. For --install to succeed, you must specify the logpath run-time option.

"C:\mongodb\bin\mongod.exe" --config "C:\mongodb\mongod.cfg" --install

Modify the path to the mongod.cfg file as needed.

To use an alternate dbpath, specify the path in the configuration file (e.g. C:\mongodb\mongod.cfg) or on the command line with the --dbpath option.

If the dbpath directory does not exist, mongod.exe will not start. The default value for dbpath is \data\db.

If needed, you can install services for multiple instances of mongod.exe or mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

3

Stop or remove the MongoDB service as needed.

To stop the MongoDB service use the following command:

net stop MongoDB

To remove the MongoDB service use the following command:

"C:\mongodb\bin\mongod.exe" --remove

Step 3: Stop or remove the MongoDB service as needed.

To stop the MongoDB service use the following command:

net stop MongoDB

To remove the MongoDB service use the following command:

"C:\mongodb\bin\mongod.exe" --remove

Additional Resources

MongoDB for Developers Free Course [https://university.mongodb.com/courses/M101P/about]

MongoDB for .NET Developers Free Online Course [https://university.mongodb.com/courses/M101N/about]

MongoDB Architecture Guide [https://www.mongodb.com/lp/white-paper/architecture-guide]

Install MongoDB Enterprise

These documents provide instructions to install MongoDB Enterprise for Linux and Windows Systems.

Install MongoDB Enterprise on Red Hat

Install the MongoDB Enterprise build and required dependencies on Red Hat Enterprise or CentOS Systems using packages.

Install MongoDB Enterprise on Ubuntu

Install the MongoDB Enterprise build and required dependencies on Ubuntu Linux Systems using packages.

Install MongoDB Enterprise on Debian

Install the MongoDB Enterprise build and required dependencies on Debian Linux Systems using packages.

Install MongoDB Enterprise on SUSE

Install the MongoDB Enterprise build and required dependencies on SUSE Enterprise Linux.

Install MongoDB Enterprise on Amazon AMI

Install the MongoDB Enterprise build and required dependencies on Amazon Linux AMI.

Install MongoDB Enterprise on Windows

Install the MongoDB Enterprise build and required dependencies using the .msi installer.

Install MongoDB Enterprise on Red Hat

Install MongoDB Enterprise on Ubuntu

Install MongoDB Enterprise on Debian

Install MongoDB Enterprise on SUSE

Install MongoDB Enterprise on Amazon AMI

Install MongoDB Enterprise on Windows

Install MongoDB Enterprise on Red Hat Enterprise or CentOS

Overview

Use this tutorial to install MongoDB Enterprise on Red Hat Enterprise Linux or CentOS Linux from .rpm packages.

Packages

MongoDB provides packages of the officially supported MongoDB Enterprise builds in it’s own repository. This repository provides the MongoDB Enterprise distribution in the following packages:

mongodb-enterprise

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-enterprise-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-enterprise-mongos

This package contains the mongos daemon.

mongodb-enterprise-shell

This package contains the mongo shell.

mongodb-enterprise-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongoimport, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-enterprise package includes various control scripts, including the init script /etc/rc.d/init.d/mongod.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script.

Considerations

MongoDB only provides Enterprise packages for Red Hat Enterprise Linux and CentOS Linux versions 5 and 6, 64-bit.

The default /etc/mongod.conf configuration file supplied by the 2.6 series packages has bind_ip` set to 127.0.0.1 by default. Modify this setting as needed for your environment before initializing a replica set.

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

Install MongoDB Enterprise

When you install the packages for MongoDB Enterprise, you choose whether to install the current release or a previous one. This procedure describes how to do both.

1

Configure repository.

Create an /etc/yum.repos.d/mongodb-enterprise.repo file so that you can install MongoDB enterprise directly, using yum.

Use the following repository file to specify the latest stable release of MongoDB enterprise.

[mongodb-enterprise]
name=MongoDB Enterprise Repository
baseurl=https://repo.mongodb.com/yum/redhat/$releasever/mongodb-enterprise/stable/$basearch/
gpgcheck=0
enabled=1

Use the following repository to install only versions of MongoDB for the 2.6 release. If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, create a /etc/yum.repos.d/mongodb-enterprise-2.6.repo file to hold the following configuration information for the MongoDB Enterprise 2.6 repository:

[mongodb-enterprise-2.6]
name=MongoDB Enterprise 2.6 Repository
baseurl=https://repo.mongodb.com/yum/redhat/$releasever/mongodb-enterprise/2.6/$basearch/
gpgcheck=0
enabled=1

.repo files for each release can also be found in the repository itself [https://repo.mongodb.com/yum/redhat/]. Remember that odd-numbered minor release versions (e.g. 2.5) are development versions and are unsuitable for production deployment.

Step 1: Configure repository.

Create an /etc/yum.repos.d/mongodb-enterprise.repo file so that you can install MongoDB enterprise directly, using yum.

Use the following repository file to specify the latest stable release of MongoDB enterprise.

[mongodb-enterprise]
name=MongoDB Enterprise Repository
baseurl=https://repo.mongodb.com/yum/redhat/$releasever/mongodb-enterprise/stable/$basearch/
gpgcheck=0
enabled=1

Use the following repository to install only versions of MongoDB for the 2.6 release. If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, create a /etc/yum.repos.d/mongodb-enterprise-2.6.repo file to hold the following configuration information for the MongoDB Enterprise 2.6 repository:

[mongodb-enterprise-2.6]
name=MongoDB Enterprise 2.6 Repository
baseurl=https://repo.mongodb.com/yum/redhat/$releasever/mongodb-enterprise/2.6/$basearch/
gpgcheck=0
enabled=1

.repo files for each release can also be found in the repository itself [https://repo.mongodb.com/yum/redhat/]. Remember that odd-numbered minor release versions (e.g. 2.5) are development versions and are unsuitable for production deployment.

2

Install the MongoDB Enterprise packages and associated tools.

You can install either the latest stable version of MongoDB Enterprise or a specific version of MongoDB Enterprise.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo yum install -y mongodb-enterprise

Step 2: Install the MongoDB Enterprise packages and associated tools.

You can install either the latest stable version of MongoDB Enterprise or a specific version of MongoDB Enterprise.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo yum install -y mongodb-enterprise

3

Optional: Manage Installed Version

Install a specific release of MongoDB Enterprise.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo yum install -y mongodb-enterprise-2.6.1 mongodb-enterprise-server-2.6.1 mongodb-enterprise-shell-2.6.1 mongodb-enterprise-mongos-2.6.1 mongodb-enterprise-tools-2.6.1

Pin a specific version of MongoDB Enterprise.

Although you can specify any available version of MongoDB Enterprise, yum will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin a package, add the following exclude directive to your /etc/yum.conf file:

exclude=mongodb-enterprise,mongodb-enterprise-server,mongodb-enterprise-shell,mongodb-enterprise-mongos,mongodb-enterprise-tools

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-linux].

Step 3: Optional: Manage Installed Version

Install a specific release of MongoDB Enterprise.

Specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1 release of MongoDB:

sudo yum install -y mongodb-enterprise-2.6.1 mongodb-enterprise-server-2.6.1 mongodb-enterprise-shell-2.6.1 mongodb-enterprise-mongos-2.6.1 mongodb-enterprise-tools-2.6.1

Pin a specific version of MongoDB Enterprise.

Although you can specify any available version of MongoDB Enterprise, yum will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin a package, add the following exclude directive to your /etc/yum.conf file:

exclude=mongodb-enterprise,mongodb-enterprise-server,mongodb-enterprise-shell,mongodb-enterprise-mongos,mongodb-enterprise-tools

Previous versions of MongoDB packages use different naming conventions. See the 2.4 version of documentation for more information [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-linux].

4

When the install completes, you can run MongoDB.

Step 4: When the install completes, you can run MongoDB.

Run MongoDB Enterprise

Important

You must configure SELinux to allow MongoDB to start on Red Hat Linux-based systems (Red Hat Enterprise Linux or CentOS Linux). Administrators have three options:

enable access to the relevant ports (e.g. 27017) for SELinux. See Default MongoDB Port for more information on MongoDB’s default ports. For default settings, this can be accomplished by running

semanage port -a -t mongod_port_t -p tcp 27017

set SELinux to permissive mode in /etc/selinux.conf. The line

SELINUX=enforcing

should be changed to

SELINUX=permissive

disable SELinux entirely; as above but set

SELINUX=disabled

All three options require root privileges. The latter two options each requires a system reboot and may have larger implications for your deployment.

You may alternatively choose not to install the SELinux packages when you are installing your Linux operating system, or choose to remove the relevant packages. This option is the most invasive and is not recommended.

The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongo and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

You can start the mongod process by issuing the following command:

sudo service mongod start

Step 1: Start MongoDB.

You can start the mongod process by issuing the following command:

sudo service mongod start

2

Verify that MongoDB has started successfully

You can verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:

sudo chkconfig mongod on

Step 2: Verify that MongoDB has started successfully

You can verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:

sudo chkconfig mongod on

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

You can restart the mongod process by issuing the following command:

sudo service mongod restart

You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.log file.

Step 4: Restart MongoDB.

You can restart the mongod process by issuing the following command:

sudo service mongod restart

You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.log file.

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB Enterprise on Ubuntu

Overview

Use this tutorial to install MongoDB Enterprise on Ubuntu Linux systems from .deb packages.

Packages

MongoDB provides packages of the officially supported MongoDB Enterprise builds in it’s own repository. This repository provides the MongoDB Enterprise distribution in the following packages:

mongodb-enterprise

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-enterprise-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-enterprise-mongos

This package contains the mongos daemon.

mongodb-enterprise-shell

This package contains the mongo shell.

mongodb-enterprise-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongoimport, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-enterprise package includes various control scripts, including the init script /etc/rc.d/init.d/mongod.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script.

Considerations

MongoDB only provides Enterprise packages for Ubuntu 12.04 LTS (Precise Pangolin) and 14.04 LTS (Trusty Tahr).

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

Install MongoDB Enterprise

1

Import the public key used by the package management system.

The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc]:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10

Step 1: Import the public key used by the package management system.

The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc]:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10

2

Create a /etc/apt/sources.list.d/mongodb-enterprise.list file for MongoDB.

Create the list file using the following command:

echo "deb http://repo.mongodb.com/apt/ubuntu "$(lsb_release -sc)"/mongodb-enterprise/stable multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise.list

If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, add the following repository:

echo "deb http://repo.mongodb.com/apt/ubuntu "$(lsb_release -sc)"/mongodb-enterprise/2.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise-2.6.list

Step 2: Create a /etc/apt/sources.list.d/mongodb-enterprise.list file for MongoDB.

Create the list file using the following command:

echo "deb http://repo.mongodb.com/apt/ubuntu "$(lsb_release -sc)"/mongodb-enterprise/stable multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise.list

If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, add the following repository:

echo "deb http://repo.mongodb.com/apt/ubuntu "$(lsb_release -sc)"/mongodb-enterprise/2.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise-2.6.list

3

Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

Step 3: Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

4

Install the MongoDB Enterprise packages.

When you install the packages, you choose whether to install the current release or a previous one. This step provides instructions for both.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo apt-get install mongodb-enterprise

To install a specific release of MongoDB Enterprise, specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1` release of MongoDB Enterprise:

sudo apt-get install mongodb-enterprise=2.6.1 mongodb-enterprise-server=2.6.1 mongodb-enterprise-shell=2.6.1 mongodb-enterprise-mongos=2.6.1 mongodb-enterprise-tools=2.6.1

You can specify any available version of MongoDB Enterprise. However apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB Enterprise at the currently installed version, issue the following command sequence:

echo "mongodb-enterprise hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-server hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-shell hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-mongos hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB Enterprise packages use different naming conventions. See the 2.4 version of documentation [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-enterprise] for more information.

Step 4: Install the MongoDB Enterprise packages.

When you install the packages, you choose whether to install the current release or a previous one. This step provides instructions for both.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo apt-get install mongodb-enterprise

To install a specific release of MongoDB Enterprise, specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1` release of MongoDB Enterprise:

sudo apt-get install mongodb-enterprise=2.6.1 mongodb-enterprise-server=2.6.1 mongodb-enterprise-shell=2.6.1 mongodb-enterprise-mongos=2.6.1 mongodb-enterprise-tools=2.6.1

You can specify any available version of MongoDB Enterprise. However apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB Enterprise at the currently installed version, issue the following command sequence:

echo "mongodb-enterprise hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-server hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-shell hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-mongos hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-tools hold" | sudo dpkg --set-selections

Previous versions of MongoDB Enterprise packages use different naming conventions. See the 2.4 version of documentation [http://docs.mongodb.org/v2.4/tutorial/install-mongodb-enterprise] for more information.

Run MongoDB Enterprise

The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodb and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

Step 1: Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

2

Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

Step 2: Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

Step 4: Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB Enterprise on Debian

Overview

Use this tutorial to install MongoDB Enterprise on Debian Linux systems from .deb packages.

Packages

MongoDB provides packages of the officially supported MongoDB Enterprise builds in it’s own repository. This repository provides the MongoDB Enterprise distribution in the following packages:

mongodb-enterprise

This package is a metapackage that will automatically install the four component packages listed below.

mongodb-enterprise-server

This package contains the mongod daemon and associated configuration and init scripts.

mongodb-enterprise-mongos

This package contains the mongos daemon.

mongodb-enterprise-shell

This package contains the mongo shell.

mongodb-enterprise-tools

This package contains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongoimport, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

Control Scripts

The mongodb-enterprise package includes various control scripts, including the init script /etc/rc.d/init.d/mongod.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the control scripts. See the Configuration File reference for documentation of settings available in the configuration file.

As of version 2.6.8, there are no control scripts for mongos. The mongos process is used only in sharding. You can use the mongod init script to derive your own mongos control script.

Considerations

Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on installation of an older release, please refer to the documentation for the appropriate version.

MongoDB only provides Enterprise packages for 64-bit versions of Debian Wheezy.

Install MongoDB Enterprise

1

Import the public key used by the package management system.

Issue the following command to add the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc] to the system key ring.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

Step 1: Import the public key used by the package management system.

Issue the following command to add the MongoDB public GPG Key [http://docs.mongodb.org/10gen-gpg-key.asc] to the system key ring.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

2

Create a /etc/apt/sources.list.d/mongodb-enterprise.list file for MongoDB.

Create the list file using the following command:

echo "deb http://repo.mongodb.com/apt/debian "$(lsb_release -sc)"/mongodb-enterprise/stable main" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise.list

If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, add the following repository:

echo "deb http://repo.mongodb.com/apt/debian "$(lsb_release -sc)"/mongodb-enterprise/2.6 main" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise-2.6.list

Step 2: Create a /etc/apt/sources.list.d/mongodb-enterprise.list file for MongoDB.

Create the list file using the following command:

echo "deb http://repo.mongodb.com/apt/debian "$(lsb_release -sc)"/mongodb-enterprise/stable main" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise.list

If you’d like to install MongoDB Enterprise packages from a particular release series, such as 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, add the following repository:

echo "deb http://repo.mongodb.com/apt/debian "$(lsb_release -sc)"/mongodb-enterprise/2.6 main" | sudo tee /etc/apt/sources.list.d/mongodb-enterprise-2.6.list

3

Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

Step 3: Reload local package database.

Issue the following command to reload the local package database:

sudo apt-get update

4

Install the MongoDB Enterprise packages.

When you install the packages, you choose whether to install the current release or a previous one. This step provides instructions for both.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo apt-get install mongodb-enterprise

To install a specific release of MongoDB Enterprise, specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1` release of MongoDB Enterprise:

sudo apt-get install mongodb-enterprise=2.6.1 mongodb-enterprise-server=2.6.1 mongodb-enterprise-shell=2.6.1 mongodb-enterprise-mongos=2.6.1 mongodb-enterprise-tools=2.6.1

You can specify any available version of MongoDB Enterprise. However apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB Enterprise at the currently installed version, issue the following command sequence:

echo "mongodb-enterprise hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-server hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-shell hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-mongos hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-tools hold" | sudo dpkg --set-selections

Step 4: Install the MongoDB Enterprise packages.

When you install the packages, you choose whether to install the current release or a previous one. This step provides instructions for both.

To install the latest stable version of MongoDB Enterprise, issue the following command:

sudo apt-get install mongodb-enterprise

To install a specific release of MongoDB Enterprise, specify each component package individually and append the version number to the package name, as in the following example that installs the 2.6.1` release of MongoDB Enterprise:

sudo apt-get install mongodb-enterprise=2.6.1 mongodb-enterprise-server=2.6.1 mongodb-enterprise-shell=2.6.1 mongodb-enterprise-mongos=2.6.1 mongodb-enterprise-tools=2.6.1

You can specify any available version of MongoDB Enterprise. However apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB Enterprise at the currently installed version, issue the following command sequence:

echo "mongodb-enterprise hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-server hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-shell hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-mongos hold" | sudo dpkg --set-selections
echo "mongodb-enterprise-tools hold" | sudo dpkg --set-selections

Run MongoDB Enterprise

The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodb and /var/log/mongodb directories to give this user access to these directories.

1

Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

Step 1: Start MongoDB.

Issue the following command to start mongod:

sudo service mongod start

2

Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

Step 2: Verify that MongoDB has started successfully

Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

3

Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 3: Stop MongoDB.

As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

4

Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

Step 4: Restart MongoDB.

Issue the following command to restart mongod:

sudo service mongod restart

5

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 5: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB Enterprise on SUSE

Overview

Use this tutorial to install MongoDB Enterprise on SUSE Linux. MongoDB Enterprise is available on select platforms and contains support for several features related to security and monitoring.

Prerequisites

To use MongoDB Enterprise on SUSE Enterprise Linux, you must install several prerequisite packages:

libopenssl0_9_8

libsnmp15

net-snmp

snmp-mibs

cyrus-sasl

cyrus-sasl-gssapi

To install these packages, you can issue the following command:

sudo zypper install libopenssl0_9_8 net-snmp libsnmp15 snmp-mibs cyrus-sasl cyrus-sasl-gssapi

Install MongoDB Enterprise

Note

The Enterprise packages include an example SNMP configuration file named mongod.conf. This file is not a MongoDB configuration file.

1

Download and install the MongoDB Enterprise packages.

After you have installed the required prerequisite packages, download and install the MongoDB Enterprise packages from http://www.mongodb.com/thank-you/download/mongodb-enterprise. The MongoDB binaries are located in the bin/ directory of the archive. To download and install, use the following sequence of commands.

curl -O http://downloads.10gen.com/linux/mongodb-linux-x86_64-enterprise-suse11-2.6.8.tgz
tar -zxvf mongodb-linux-x86_64-enterprise-suse11-2.6.8.tgz
cp -R -n mongodb-linux-x86_64-enterprise-suse11-2.6.8/ mongodb

Step 1: Download and install the MongoDB Enterprise packages.

After you have installed the required prerequisite packages, download and install the MongoDB Enterprise packages from http://www.mongodb.com/thank-you/download/mongodb-enterprise. The MongoDB binaries are located in the bin/ directory of the archive. To download and install, use the following sequence of commands.

curl -O http://downloads.10gen.com/linux/mongodb-linux-x86_64-enterprise-suse11-2.6.8.tgz
tar -zxvf mongodb-linux-x86_64-enterprise-suse11-2.6.8.tgz
cp -R -n mongodb-linux-x86_64-enterprise-suse11-2.6.8/ mongodb

2

Ensure the location of the MongoDB binaries is included in the PATH variable.

Once you have copied the MongoDB binaries to their target location, ensure that the location is included in your PATH variable. If it is not, either include it or create symbolic links from the binaries to a directory that is included.

Step 2: Ensure the location of the MongoDB binaries is included in the PATH variable.

Once you have copied the MongoDB binaries to their target location, ensure that the location is included in your PATH variable. If it is not, either include it or create symbolic links from the binaries to a directory that is included.

Run MongoDB Enterprise

1

Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 1: Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

2

Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 2: Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

3

Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

Step 3: Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB Enterprise on Amazon Linux AMI

Overview

Use this tutorial to install MongoDB Enterprise on Amazon Linux AMI. MongoDB Enterprise is available on select platforms and contains support for several features related to security and monitoring.

Prerequisites

To use MongoDB Enterprise on Amazon Linux AMI, you must install several prerequisite packages:

net-snmp

net-snmp-libs

openssl

net-snmp-utils

cyrus-sasl

cyrus-sasl-lib

cyrus-sasl-devel

cyrus-sasl-gssapi

To install these packages, you can issue the following command:

sudo yum install openssl net-snmp net-snmp-libs net-snmp-utils cyrus-sasl cyrus-sasl-lib cyrus-sasl-devel cyrus-sasl-gssapi

Install MongoDB Enterprise

Note

The Enterprise packages include an example SNMP configuration file named mongod.conf. This file is not a MongoDB configuration file.

1

Download and install the MongoDB Enterprise packages.

After you have installed the required prerequisite packages, download and install the MongoDB Enterprise packages from http://www.mongodb.com/thank-you/download/mongodb-enterprise. The MongoDB binaries are located in the bin/ directory of the archive. To download and install, use the following sequence of commands.

curl -O http://downloads.10gen.com/linux/mongodb-linux-x86_64-enterprise-amzn64-2.6.8.tgz
tar -zxvf mongodb-linux-x86_64-enterprise-amzn64-2.6.8.tgz
cp -R -n mongodb-linux-x86_64-enterprise-amzn64-2.6.8/ mongodb

Step 1: Download and install the MongoDB Enterprise packages.

After you have installed the required prerequisite packages, download and install the MongoDB Enterprise packages from http://www.mongodb.com/thank-you/download/mongodb-enterprise. The MongoDB binaries are located in the bin/ directory of the archive. To download and install, use the following sequence of commands.

curl -O http://downloads.10gen.com/linux/mongodb-linux-x86_64-enterprise-amzn64-2.6.8.tgz
tar -zxvf mongodb-linux-x86_64-enterprise-amzn64-2.6.8.tgz
cp -R -n mongodb-linux-x86_64-enterprise-amzn64-2.6.8/ mongodb

2

Ensure the location of the MongoDB binaries is included in the PATH variable.

Once you have copied the MongoDB binaries to their target location, ensure that the location is included in your PATH variable. If it is not, either include it or create symbolic links from the binaries to a directory that is included.

Step 2: Ensure the location of the MongoDB binaries is included in the PATH variable.

Once you have copied the MongoDB binaries to their target location, ensure that the location is included in your PATH variable. If it is not, either include it or create symbolic links from the binaries to a directory that is included.

Run MongoDB Enterprise

The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongo and /var/log/mongodb directories to give this user access to these directories.

1

Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 1: Create the data directory.

Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

2

Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 2: Set permissions for the data directory.

Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

3

Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

Step 3: Run MongoDB.

To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths

If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod

If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory

If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Install MongoDB Enterprise on Windows

New in version 2.6.

Overview

Use this tutorial to install MongoDB Enterprise on Windows systems. MongoDB Enterprise is available on select platforms and contains support for several features related to security and monitoring.

Prerequisites

MongoDB Enterprise Server for Windows requires Windows Server 2008 R2 or later. The MSI installer includes all other software dependencies.

Install MongoDB Enterprise

1

Download MongoDB Enterprise for Windows.

Download the latest production release of MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise]

Step 1: Download MongoDB Enterprise for Windows.

Download the latest production release of MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise]

2

Install MongoDB Enterprise for Windows.

Run the downloaded MSI installer. Make configuration choices as prompted.

MongoDB is self-contained and does not have any other system dependencies. You can install MongoDB into any folder (e.g. D:\test\mongodb) and run it from there. The installation wizard includes an option to select an installation directory.

Step 2: Install MongoDB Enterprise for Windows.

Run the downloaded MSI installer. Make configuration choices as prompted.

MongoDB is self-contained and does not have any other system dependencies. You can install MongoDB into any folder (e.g. D:\test\mongodb) and run it from there. The installation wizard includes an option to select an installation directory.

Run MongoDB Enterprise

Warning

Do not make mongod.exe visible on public networks without running in “Secure Mode” with the auth setting. MongoDB is designed to be run in trusted environments, and the database does not enable “Secure Mode” by default.

1

Set up the MongoDB environment.

MongoDB requires a data directory to store all data. MongoDB’s default data directory path is \data\db. Create this folder using the following commands from a Command Prompt:

md \data\db

You can specify an alternate path for data files using the --dbpath option to mongod.exe, for example:

C:\mongodb\bin\mongod.exe --dbpath d:\test\mongodb\data

If your path includes spaces, enclose the entire path in double quotes, for example:

C:\mongodb\bin\mongod.exe --dbpath "d:\test\mongo db data"

You may also specify the dbpath in a configuration file.

Step 1: Set up the MongoDB environment.

MongoDB requires a data directory to store all data. MongoDB’s default data directory path is \data\db. Create this folder using the following commands from a Command Prompt:

md \data\db

You can specify an alternate path for data files using the --dbpath option to mongod.exe, for example:

C:\mongodb\bin\mongod.exe --dbpath d:\test\mongodb\data

If your path includes spaces, enclose the entire path in double quotes, for example:

C:\mongodb\bin\mongod.exe --dbpath "d:\test\mongo db data"

You may also specify the dbpath in a configuration file.

2

Start MongoDB.

To start MongoDB, run mongod.exe. For example, from the Command Prompt:

C:\mongodb\bin\mongod.exe

This starts the main MongoDB database process. The waiting for connections message in the console output indicates that the mongod.exe process is running successfully.

Depending on the security level of your system, Windows may pop up a Security Alert dialog box about blocking “some features” of C:\mongodb\bin\mongod.exe from communicating on networks. All users should select Private Networks, such as my home or work network and click Allow access. For additional information on security and MongoDB, please see the Security Documentation.

Step 2: Start MongoDB.

To start MongoDB, run mongod.exe. For example, from the Command Prompt:

C:\mongodb\bin\mongod.exe

This starts the main MongoDB database process. The waiting for connections message in the console output indicates that the mongod.exe process is running successfully.

Depending on the security level of your system, Windows may pop up a Security Alert dialog box about blocking “some features” of C:\mongodb\bin\mongod.exe from communicating on networks. All users should select Private Networks, such as my home or work network and click Allow access. For additional information on security and MongoDB, please see the Security Documentation.

3

Connect to MongoDB.

To connect to MongoDB through the mongo.exe shell, open another Command Prompt.

C:\mongodb\bin\mongo.exe

If you want to develop applications using .NET, see the documentation of C# and MongoDB [http://docs.mongodb.org/ecosystem/drivers/csharp] for more information.

Step 3: Connect to MongoDB.

To connect to MongoDB through the mongo.exe shell, open another Command Prompt.

C:\mongodb\bin\mongo.exe

If you want to develop applications using .NET, see the documentation of C# and MongoDB [http://docs.mongodb.org/ecosystem/drivers/csharp] for more information.

4

Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Step 4: Begin using MongoDB.

To begin using MongoDB, see Getting Started with MongoDB. Also consider the Production Notes document before deploying MongoDB in a production environment.

Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

Configure a Windows Service for MongoDB Enterprise

You can set up the MongoDB server as a Windows Service that starts automatically at boot time.

1

Configure directories and files.

Create a configuration file and a directory path for MongoDB log output (logpath):

Create a specific directory for MongoDB log files:

md "C:\mongodb\log"

In the Command Prompt, create a configuration file for the logpath option for MongoDB:

echo logpath=C:\mongodb\log\mongo.log > "C:\mongodb\mongod.cfg"

Step 1: Configure directories and files.

Create a configuration file and a directory path for MongoDB log output (logpath):

Create a specific directory for MongoDB log files:

md "C:\mongodb\log"

In the Command Prompt, create a configuration file for the logpath option for MongoDB:

echo logpath=C:\mongodb\log\mongo.log > "C:\mongodb\mongod.cfg"

2

Run the MongoDB service.

Run all of the following commands in Command Prompt with “Administrative Privileges:”

Install the MongoDB service. For --install to succeed, you must specify the logpath run-time option.

"C:\mongodb\bin\mongod.exe" --config "C:\mongodb\mongod.cfg" --install

Modify the path to the mongod.cfg file as needed.

To use an alternate dbpath, specify the path in the configuration file (e.g. C:\mongodb\mongod.cfg) or on the command line with the --dbpath option.

If the dbpath directory does not exist, mongod.exe will not start. The default value for dbpath is \data\db.

If needed, you can install services for multiple instances of mongod.exe or mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

Step 2: Run the MongoDB service.

Run all of the following commands in Command Prompt with “Administrative Privileges:”

Install the MongoDB service. For --install to succeed, you must specify the logpath run-time option.

"C:\mongodb\bin\mongod.exe" --config "C:\mongodb\mongod.cfg" --install

Modify the path to the mongod.cfg file as needed.

To use an alternate dbpath, specify the path in the configuration file (e.g. C:\mongodb\mongod.cfg) or on the command line with the --dbpath option.

If the dbpath directory does not exist, mongod.exe will not start. The default value for dbpath is \data\db.

If needed, you can install services for multiple instances of mongod.exe or mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

3

Stop or remove the MongoDB service as needed.

To stop the MongoDB service use the following command:

net stop MongoDB

To remove the MongoDB service use the following command:

"C:\mongodb\bin\mongod.exe" --remove

Step 3: Stop or remove the MongoDB service as needed.

To stop the MongoDB service use the following command:

net stop MongoDB

To remove the MongoDB service use the following command:

"C:\mongodb\bin\mongod.exe" --remove

Verify Integrity of MongoDB Packages

Overview

The MongoDB release team digitally signs all software packages to certify that a particular MongoDB package is a valid and unaltered MongoDB release.

Before installing MongoDB, you can validate packages using either a PGP signature or with MD5 and SHA checksums of the MongoDB packages. The PGP signatures store an encrypted hash of the software package, that you can validate to ensure that the package you have is consistent with the official package release. MongoDB also publishes MD5 and SHA hashes of the official packages that you can use to confirm that you have a valid package.

Considerations

MongoDB signs each release branch with a different PGP key.

The public .asc and .pub key files for each branch are available for download. For example, the 2.2 keys are available at the following URLs:

https://www.mongodb.org/static/pgp/server-2.2.asc
https://www.mongodb.org/static/pgp/server-2.2.pub

Replace 2.2 with the appropriate release number to download public key. Keys are available for all MongoDB releases beginning with 2.2.

Procedures

Use PGP/GPG

1

Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

Step 1: Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

2

Download the public signature file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.sig

Step 2: Download the public signature file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.sig

3

Download then import the key file.

If you have not downloaded and imported the key file, enter these commands:

curl -LO https://www.mongodb.org/static/pgp/server-2.6.asc
gpg --import server-2.6.asc

You should receive this message:

gpg: key AAB2461C: public key "MongoDB 2.6 Release Signing Key <packaging@mongodb.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)

Step 3: Download then import the key file.

If you have not downloaded and imported the key file, enter these commands:

curl -LO https://www.mongodb.org/static/pgp/server-2.6.asc
gpg --import server-2.6.asc

You should receive this message:

gpg: key AAB2461C: public key "MongoDB 2.6 Release Signing Key <packaging@mongodb.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)

4

Verify the MongoDB installation file.

Type this command:

gpg --verify mongodb-osx-x86_64-2.6.0.tgz.sig mongodb-osx-x86_64-2.6.0.tgz

You should receive this message:

gpg: Signature made Thu Mar  6 15:11:28 2014 EST using RSA key ID AAB2461C
gpg: Good signature from "MongoDB 2.6 Release Signing Key <packaging@mongodb.com>"

Download and import the key file, as described above, if you receive a message like this one:

gpg: Signature made Thu Mar  6 15:11:28 2014 EST using RSA key ID AAB2461C
gpg: Can't check signature: public key not found

gpg will return the following message if the package is

properly signed, but you do not currently trust the signing key in your local trustdb.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: DFFA 3DCF 326E 302C 4787  673A 01C4 E7FA AAB2 461C

Step 4: Verify the MongoDB installation file.

Type this command:

gpg --verify mongodb-osx-x86_64-2.6.0.tgz.sig mongodb-osx-x86_64-2.6.0.tgz

You should receive this message:

gpg: Signature made Thu Mar  6 15:11:28 2014 EST using RSA key ID AAB2461C
gpg: Good signature from "MongoDB 2.6 Release Signing Key <packaging@mongodb.com>"

Download and import the key file, as described above, if you receive a message like this one:

gpg: Signature made Thu Mar  6 15:11:28 2014 EST using RSA key ID AAB2461C
gpg: Can't check signature: public key not found

gpg will return the following message if the package is

properly signed, but you do not currently trust the signing key in your local trustdb.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: DFFA 3DCF 326E 302C 4787  673A 01C4 E7FA AAB2 461C

Use SHA

MongoDB provides checksums using both the SHA-1 and SHA-256 hash functions. You can use either, as you like.

1

Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

Step 1: Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

2

Download the SHA1 and SHA256 file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.3.tgz.sha1
curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.3.tgz.sha256

Step 2: Download the SHA1 and SHA256 file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.3.tgz.sha1
curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.3.tgz.sha256

3

Use the SHA-256 checksum to verify the MongoDB package file.

Compute the checksum of the package file:

shasum mongodb-linux-x86_64-2.6.3.tgz

which will generate this result:

fe511ee40428edda3a507f70d2b91d16b0483674 mongodb-osx-x86_64-2.6.3.tgz

Enter this command:

cat mongodb-linux-x86_64-2.6.3.tgz.sha1

which will generate this result:

fe511ee40428edda3a507f70d2b91d16b0483674 mongodb-osx-x86_64-2.6.3.tgz

The output of the shasum and cat commands should be identical.

Step 3: Use the SHA-256 checksum to verify the MongoDB package file.

Compute the checksum of the package file:

shasum mongodb-linux-x86_64-2.6.3.tgz

which will generate this result:

fe511ee40428edda3a507f70d2b91d16b0483674 mongodb-osx-x86_64-2.6.3.tgz

Enter this command:

cat mongodb-linux-x86_64-2.6.3.tgz.sha1

which will generate this result:

fe511ee40428edda3a507f70d2b91d16b0483674 mongodb-osx-x86_64-2.6.3.tgz

The output of the shasum and cat commands should be identical.

3

Use the SHA-1 checksum to verify the MongoDB package file.

Compute the checksum of the package file:

shasum -a 256 mongodb-linux-x86_64-2.6.3.tgz

which will generate this result:

be3a5e9f4e9c8e954e9af7053776732387d2841a019185eaf2e52086d4d207a3  mongodb-osx-x86_64-2.6.3.tgz

Enter this command:

cat mongodb-linux-x86_64-2.6.3.tgz.sha256

which will generate this result:

be3a5e9f4e9c8e954e9af7053776732387d2841a019185eaf2e52086d4d207a3  mongodb-osx-x86_64-2.6.3.tgz

The output of the shasum and cat commands should be identical.

Step 3: Use the SHA-1 checksum to verify the MongoDB package file.

Compute the checksum of the package file:

shasum -a 256 mongodb-linux-x86_64-2.6.3.tgz

which will generate this result:

be3a5e9f4e9c8e954e9af7053776732387d2841a019185eaf2e52086d4d207a3  mongodb-osx-x86_64-2.6.3.tgz

Enter this command:

cat mongodb-linux-x86_64-2.6.3.tgz.sha256

which will generate this result:

be3a5e9f4e9c8e954e9af7053776732387d2841a019185eaf2e52086d4d207a3  mongodb-osx-x86_64-2.6.3.tgz

The output of the shasum and cat commands should be identical.

Use MD5

1

Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

Step 1: Download the MongoDB installation file.

Download the binaries from https://www.mongodb.org/downloads based on your environment.

For example, to download the 2.6.0 release for OS X through the shell, type this command:

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz

2

Download the MD5 file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.md5

Step 2: Download the MD5 file.

curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.md5

3

Verify the checksum values for the MongoDB package file (Linux).

Compute the checksum of the package file:

md5 mongodb-linux-x86_64-2.6.0.tgz

which will generate this result:

MD5 (mongodb-linux-x86_64-2.6.0.tgz) = a937d49881f90e1a024b58d642011dc4

Enter this command:

cat mongodb-linux-x86_64-2.6.0.tgz.md5

which will generate this result:

a937d49881f90e1a024b58d642011dc4

The output of the md5 and cat commands should be identical.

Step 3: Verify the checksum values for the MongoDB package file (Linux).

Compute the checksum of the package file:

md5 mongodb-linux-x86_64-2.6.0.tgz

which will generate this result:

MD5 (mongodb-linux-x86_64-2.6.0.tgz) = a937d49881f90e1a024b58d642011dc4

Enter this command:

cat mongodb-linux-x86_64-2.6.0.tgz.md5

which will generate this result:

a937d49881f90e1a024b58d642011dc4

The output of the md5 and cat commands should be identical.

4

Verify the MongoDB installation file (OS X).

Compute the checksum of the package file:

md5sum -c mongodb-osx-x86_64-2.6.0.tgz.md5 mongodb-osx-x86_64-2.6.0.tgz

which will generate this result:

mongodb-osx-x86_64-2.6.0-rc1.tgz ok

Step 4: Verify the MongoDB installation file (OS X).

Compute the checksum of the package file:

md5sum -c mongodb-osx-x86_64-2.6.0.tgz.md5 mongodb-osx-x86_64-2.6.0.tgz

which will generate this result:

mongodb-osx-x86_64-2.6.0-rc1.tgz ok

Getting Started with MongoDB

This tutorial provides an introduction to basic database operations using the mongo shell. mongo is a part of the standard MongoDB distribution and provides a full JavaScript environment with complete access to the JavaScript language and all standard functions as well as a full database interface for MongoDB. See the mongo JavaScript API [http://api.mongodb.org/js] documentation and the mongo shell JavaScript Method Reference.

The tutorial assumes that you’re running MongoDB on a Linux or OS X operating system and that you have a running database server; MongoDB does support Windows and provides a Windows distribution with identical operation. For instructions on installing MongoDB and starting the database server, see the appropriate installation document.

Connect to a Database

In this section, you connect to the database server, which runs as mongod, and begin using the mongo shell to select a logical database within the database instance and access the help text in the mongo shell.

Connect to a mongod

From a system prompt, start mongo by issuing the mongo command, as follows:

mongo

By default, mongo looks for a database server listening on port 27017 on the localhost interface. To connect to a server on a different port or interface, use the --port and --host options.

Select a Database

After starting the mongo shell your session will use the test database by default. At any time, issue the following operation at the mongo to report the name of the current database:

db

From the mongo shell, display the list of databases, with the following operation:

show dbs

Switch to a new database named mydb, with the following operation:

use mydb

Confirm that your session has the mydb database as context, by checking the value of the db object, which returns the name of the current database, as follows:

db

At this point, if you issue the show dbs operation again, it will not include the mydb database. MongoDB will not permanently create a database until you insert data into that database. The Create a Collection and Insert Documents section describes the process for inserting data.

New in version 2.4: show databases also returns a list of databases.

Display mongo Help

At any point, you can access help for the mongo shell using the following operation:

help

Furthermore, you can append the .help() method to some JavaScript methods, any cursor object, as well as the db and db.collection objects to return additional help information.

Create a Collection and Insert Documents

In this section, you insert documents into a new collection named testData within the new database named mydb.

MongoDB will create a collection implicitly upon its first use. You do not need to create a collection before inserting data. Furthermore, because MongoDB uses dynamic schemas, you also need not specify the structure of your documents before inserting them into the collection.

From the mongo shell, confirm you are in the mydb database by issuing the following:

db

If mongo does not return mydb for the previous operation, set the context to the mydb database, with the following operation:

use mydb

Create two documents named j and k by using the following sequence of JavaScript operations:

j = { name : "mongo" }
k = { x : 3 }

Insert the j and k documents into the testData collection with the following sequence of operations:

db.testData.insert( j )
db.testData.insert( k )

When you insert the first document, the mongod will create both the mydb database and the testData collection.

Confirm that the testData collection exists. Issue the following operation:

show collections

The mongo shell will return the list of the collections in the current (i.e. mydb) database. At this point, the only collection with user data is testData.

Confirm that the documents exist in the testData collection by issuing a query on the collection using the find() method:

db.testData.find()

This operation returns the following results. The ObjectId values will be unique:

{ "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" }
{ "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 }

All MongoDB documents must have an _id field with a unique value. These operations do not explicitly specify a value for the _id field, so mongo creates a unique ObjectId value for the field before inserting it into the collection.

Insert Documents using a For Loop or a JavaScript Function

To perform the remaining procedures in this tutorial, first add more documents to your database using one or both of the procedures described in Generate Test Data.

Working with the Cursor

When you query a collection, MongoDB returns a “cursor” object that contains the results of the query. The mongo shell then iterates over the cursor to display the results. Rather than returning all results at once, the shell iterates over the cursor 20 times to display the first 20 results and then waits for a request to iterate over the remaining results. In the shell, enter it to iterate over the next set of results.

The procedures in this section show other ways to work with a cursor. For comprehensive documentation on cursors, see Iterate the Returned Cursor.

Iterate over the Cursor with a Loop

Before using this procedure, add documents to a collection using one of the procedures in Generate Test Data. You can name your database and collections anything you choose, but this procedure will assume the database named test and a collection named testData.

In the MongoDB JavaScript shell, query the testData collection and assign the resulting cursor object to the c variable:

var c = db.testData.find()

Print the full result set by using a while loop to iterate over the c variable:

while ( c.hasNext() ) printjson( c.next() )

The hasNext() function returns true if the cursor has documents. The next() method returns the next document. The printjson() method renders the document in a JSON-like format.

The operation displays all documents:

{ "_id" : ObjectId("51a7dc7b2cacf40b79990be6"), "x" : 1 }
{ "_id" : ObjectId("51a7dc7b2cacf40b79990be7"), "x" : 2 }
{ "_id" : ObjectId("51a7dc7b2cacf40b79990be8"), "x" : 3 }
...

Use Array Operations with the Cursor

The following procedure lets you manipulate a cursor object as if it were an array:

In the mongo shell, query the testData collection and assign the resulting cursor object to the c variable:

var c = db.testData.find()

To find the document at the array index 4, use the following operation:

printjson( c [ 4 ] )

MongoDB returns the following:

{ "_id" : ObjectId("51a7dc7b2cacf40b79990bea"), "x" : 5 }

When you access documents in a cursor using the array index notation, mongo first calls the cursor.toArray() method and loads into RAM all documents returned by the cursor. The index is then applied to the resulting array. This operation iterates the cursor completely and exhausts the cursor.

For very large result sets, mongo may run out of available memory.

For more information on the cursor, see Iterate the Returned Cursor.

Query for Specific Documents

MongoDB has a rich query system that allows you to select and filter the documents in a collection along specific fields and values. See Query Documents and Read Operations for a full account of queries in MongoDB.

In this procedure, you query for specific documents in the testData collection by passing a “query document” as a parameter to the find() method. A query document specifies the criteria the query must match to return a document.

In the mongo shell, query for all documents where the x field has a value of 18 by passing the { x : 18 } query document as a parameter to the find() method:

db.testData.find( { x : 18 } )

MongoDB returns one document that fits this criteria:

{ "_id" : ObjectId("51a7dc7b2cacf40b79990bf7"), "x" : 18 }

Return a Single Document from a Collection

With the findOne() method you can return a single document from a MongoDB collection. The findOne() method takes the same parameters as find(), but returns a document rather than a cursor.

To retrieve one document from the testData collection, issue the following command:

db.testData.findOne()

For more information on querying for documents, see the Query Documents and Read Operations documentation.

Limit the Number of Documents in the Result Set

To increase performance, you can constrain the size of the result by limiting the amount of data your application must receive over the network.

To specify the maximum number of documents in the result set, call the limit() method on a cursor, as in the following command:

db.testData.find().limit(3)

MongoDB will return the following result, with different ObjectId values:

{ "_id" : ObjectId("51a7dc7b2cacf40b79990be6"), "x" : 1 }
{ "_id" : ObjectId("51a7dc7b2cacf40b79990be7"), "x" : 2 }
{ "_id" : ObjectId("51a7dc7b2cacf40b79990be8"), "x" : 3 }

Next Steps with MongoDB

For more information on manipulating the documents in a database as you continue to learn MongoDB, consider the following resources:

MongoDB CRUD Operations

SQL to MongoDB Mapping Chart

MongoDB Drivers [http://docs.mongodb.org/ecosystem/drivers]

Additional Resources

MongoDB University: Free, Online Courses for Developers and DBAs [https://education.mongodb.com/]

MongoDB Architecture Guide [https://www.mongodb.com/lp/whitepaper/architecture-guide]

MongoDB Administration 101 Presentation [http://www.mongodb.com/presentations/webinar-mongodb-administration-101]

Generate Test Data

This tutorial describes how to quickly generate test data as needed to test basic MongoDB operations.

Insert Multiple Documents Using a For Loop

1

Insert new documents into the testData collection.

From the mongo shell, use the for loop. If the testData collection does not exist, MongoDB will implicitly create the collection.

for (var i = 1; i <= 25; i++) {
   db.testData.insert( { x : i } )
}

Step 1: Insert new documents into the testData collection.

From the mongo shell, use the for loop. If the testData collection does not exist, MongoDB will implicitly create the collection.

for (var i = 1; i <= 25; i++) {
   db.testData.insert( { x : i } )
}

2

Query the collection.

Use find() to query the collection:

db.testData.find()

The mongo shell displays the first 20 documents in the collection. Your ObjectId values will be different:

{ "_id" : ObjectId("53d7be30242b692a1138ac7d"), "x" : 1 }
{ "_id" : ObjectId("53d7be30242b692a1138ac7e"), "x" : 2 }
{ "_id" : ObjectId("53d7be30242b692a1138ac7f"), "x" : 3 }
{ "_id" : ObjectId("53d7be30242b692a1138ac80"), "x" : 4 }
{ "_id" : ObjectId("53d7be30242b692a1138ac81"), "x" : 5 }
{ "_id" : ObjectId("53d7be30242b692a1138ac82"), "x" : 6 }
{ "_id" : ObjectId("53d7be30242b692a1138ac83"), "x" : 7 }
{ "_id" : ObjectId("53d7be30242b692a1138ac84"), "x" : 8 }
{ "_id" : ObjectId("53d7be30242b692a1138ac85"), "x" : 9 }
{ "_id" : ObjectId("53d7be30242b692a1138ac86"), "x" : 10 }
{ "_id" : ObjectId("53d7be30242b692a1138ac87"), "x" : 11 }
{ "_id" : ObjectId("53d7be30242b692a1138ac88"), "x" : 12 }
{ "_id" : ObjectId("53d7be30242b692a1138ac89"), "x" : 13 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8a"), "x" : 14 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8b"), "x" : 15 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8c"), "x" : 16 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8d"), "x" : 17 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8e"), "x" : 18 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8f"), "x" : 19 }
{ "_id" : ObjectId("53d7be30242b692a1138ac90"), "x" : 20 }
Type "it" for more

Step 2: Query the collection.

Use find() to query the collection:

db.testData.find()

The mongo shell displays the first 20 documents in the collection. Your ObjectId values will be different:

{ "_id" : ObjectId("53d7be30242b692a1138ac7d"), "x" : 1 }
{ "_id" : ObjectId("53d7be30242b692a1138ac7e"), "x" : 2 }
{ "_id" : ObjectId("53d7be30242b692a1138ac7f"), "x" : 3 }
{ "_id" : ObjectId("53d7be30242b692a1138ac80"), "x" : 4 }
{ "_id" : ObjectId("53d7be30242b692a1138ac81"), "x" : 5 }
{ "_id" : ObjectId("53d7be30242b692a1138ac82"), "x" : 6 }
{ "_id" : ObjectId("53d7be30242b692a1138ac83"), "x" : 7 }
{ "_id" : ObjectId("53d7be30242b692a1138ac84"), "x" : 8 }
{ "_id" : ObjectId("53d7be30242b692a1138ac85"), "x" : 9 }
{ "_id" : ObjectId("53d7be30242b692a1138ac86"), "x" : 10 }
{ "_id" : ObjectId("53d7be30242b692a1138ac87"), "x" : 11 }
{ "_id" : ObjectId("53d7be30242b692a1138ac88"), "x" : 12 }
{ "_id" : ObjectId("53d7be30242b692a1138ac89"), "x" : 13 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8a"), "x" : 14 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8b"), "x" : 15 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8c"), "x" : 16 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8d"), "x" : 17 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8e"), "x" : 18 }
{ "_id" : ObjectId("53d7be30242b692a1138ac8f"), "x" : 19 }
{ "_id" : ObjectId("53d7be30242b692a1138ac90"), "x" : 20 }
Type "it" for more

3

Iterate through the cursor.

The find() method returns a cursor. To iterate the cursor and return more documents, type it in the mongo shell. The shell will exhaust the cursor and return these documents:

{ "_id" : ObjectId("53d7be30242b692a1138ac91"), "x" : 21 }
{ "_id" : ObjectId("53d7be30242b692a1138ac92"), "x" : 22 }
{ "_id" : ObjectId("53d7be30242b692a1138ac93"), "x" : 23 }
{ "_id" : ObjectId("53d7be30242b692a1138ac94"), "x" : 24 }
{ "_id" : ObjectId("53d7be30242b692a1138ac95"), "x" : 25 }

Step 3: Iterate through the cursor.

The find() method returns a cursor. To iterate the cursor and return more documents, type it in the mongo shell. The shell will exhaust the cursor and return these documents:

{ "_id" : ObjectId("53d7be30242b692a1138ac91"), "x" : 21 }
{ "_id" : ObjectId("53d7be30242b692a1138ac92"), "x" : 22 }
{ "_id" : ObjectId("53d7be30242b692a1138ac93"), "x" : 23 }
{ "_id" : ObjectId("53d7be30242b692a1138ac94"), "x" : 24 }
{ "_id" : ObjectId("53d7be30242b692a1138ac95"), "x" : 25 }

Insert Multiple Documents with a mongo Shell Function

You can create a JavaScript function in your shell session to generate the above data. The insertData() JavaScript function that follows creates new data for use in testing or training by either creating a new collection or appending data to an existing collection:

function insertData(dbName, colName, num) {

  var col = db.getSiblingDB(dbName).getCollection(colName);

  for (i = 0; i < num; i++) {
    col.insert({x:i});
  }

  print(col.count());

}

The insertData() function takes three parameters: a database, a new or existing collection, and the number of documents to create. The function creates documents with an x field set to an incremented integer, as in the following example documents:

{ "_id" : ObjectId("51a4da9b292904caffcff6eb"), "x" : 0 }
{ "_id" : ObjectId("51a4da9b292904caffcff6ec"), "x" : 1 }
{ "_id" : ObjectId("51a4da9b292904caffcff6ed"), "x" : 2 }

Store the function in your .mongorc.js file. The mongo shell loads and parses the .mongorc.js file on startup so your function is available every time you start a session.

Example

Specify database name, collection name, and the number of documents to insert as arguments to insertData().

insertData("test", "testData", 400)

This operation inserts 400 documents into the testData collection in the test database. If the collection and database do not exist, MongoDB creates them implicitly before inserting documents.

Additional Resources

Python utils to create random JSON data and import into mongoDB [https://github.com/10gen-labs/ipsum]

MongoDB CRUD Operations

MongoDB provides rich semantics for reading and manipulating data. CRUD stands for create, read, update, and delete. These terms are the foundation for all interactions with the database.

MongoDB CRUD Introduction

An introduction to the MongoDB data model as well as queries and data manipulations.

MongoDB CRUD Concepts

The core documentation of query and data manipulation.

MongoDB CRUD Tutorials

Examples of basic query and data modification operations.

MongoDB CRUD Reference

Reference material for the query and data manipulation interfaces.

MongoDB CRUD Introduction

MongoDB CRUD Concepts

Read Operations

Read Operations Overview

Cursors

Query Optimization

Query Plans

Distributed Queries

Write Operations

Write Operations Overview

Write Concern

Atomicity and Transactions

Distributed Write Operations

Write Operation Performance

Bulk Write Operations

Storage

MongoDB CRUD Tutorials

Insert Documents

Query Documents

Modify Documents

Remove Documents

Limit Fields to Return from a Query

Limit Number of Elements in an Array after an Update

Iterate a Cursor in the mongo Shell

Analyze Query Performance

Perform Two Phase Commits

Update Document if Current

Create Tailable Cursor

Create an Auto-Incrementing Sequence Field

MongoDB CRUD Reference

Write Concern Reference

SQL to MongoDB Mapping Chart

The bios Example Collection

MongoDB CRUD Introduction

MongoDB stores data in the form of documents, which are JSON-like field and value pairs. Documents are analogous to structures in programming languages that associate keys with values (e.g. dictionaries, hashes, maps, and associative arrays). Formally, MongoDB documents are BSON documents. BSON is a binary representation of JSON with additional type information. In the documents, the value of a field can be any of the BSON data types, including other documents, arrays, and arrays of documents. For more information, see Documents.

MongoDB stores all documents in collections. A collection is a group of related documents that have a set of shared common indexes. Collections are analogous to a table in relational databases.

Database Operations

Query

In MongoDB a query targets a specific collection of documents. Queries specify criteria, or conditions, that identify the documents that MongoDB returns to the clients. A query may include a projection that specifies the fields from the matching documents to return. You can optionally modify queries to impose limits, skips, and sort orders.

In the following diagram, the query process specifies a query criteria and a sort modifier:

See Read Operations Overview for more information.

Data Modification

Data modification refers to operations that create, update, or delete data. In MongoDB, these operations modify the data of a single collection. For the update and delete operations, you can specify the criteria to select the documents to update or remove.

In the following diagram, the insert operation adds a new document to the users collection.

See Write Operations Overview for more information.

Related Features

Indexes

To enhance the performance of common queries and updates, MongoDB has full support for secondary indexes. These indexes allow applications to store a view of a portion of the collection in an efficient data structure. Most indexes store an ordered representation of all values of a field or a group of fields. Indexes may also enforce uniqueness, store objects in a geospatial representation, and facilitate text search.

Replica Set Read Preference

For replica sets and sharded clusters with replica set components, applications specify read preferences. A read preference determines how the client direct read operations to the set.

Write Concern

Applications can also control the behavior of write operations using write concern. Particularly useful for deployments with replica sets, the write concern semantics allow clients to specify the assurance that MongoDB provides when reporting on the success of a write operation.

Aggregation

In addition to the basic queries, MongoDB provides several data aggregation features. For example, MongoDB can return counts of the number of documents that match a query, or return the number of distinct values for a field, or process a collection of documents using a versatile stage-based data processing pipeline or map-reduce operations.

MongoDB CRUD Concepts

The Read Operations and Write Operations documents introduce the behavior and operations of read and write operations for MongoDB deployments.

Read Operations

Queries are the core operations that return data in MongoDB. Introduces queries, their behavior, and performances.

Cursors

Queries return iterable objects, called cursors, that hold the full result set.

Query Optimization

Analyze and improve query performance.

Distributed Queries

Describes how sharded clusters and replica sets affect the performance of read operations.

Write Operations

Write operations insert, update, or remove documents in MongoDB. Introduces data create and modify operations, their behavior, and performances.

Write Concern

Describes the kind of guarantee MongoDB provides when reporting on the success of a write operation.

Distributed Write Operations

Describes how MongoDB directs write operations on sharded clusters and replica sets and the performance characteristics of these operations.

Continue reading from Write Operations for additional background on the behavior of data modification operations in MongoDB.

Read Operations

Read Operations Overview

Cursors

Query Optimization

Query Plans

Distributed Queries

Write Operations

Write Operations Overview

Write Concern

Atomicity and Transactions

Distributed Write Operations

Write Operation Performance

Bulk Write Operations

Storage

Read Operations

The following documents describe read operations:

Read Operations Overview

A high level overview of queries and projections in MongoDB, including a discussion of syntax and behavior.

Cursors

Queries return iterable objects, called cursors, that hold the full result set.

Query Optimization

Analyze and improve query performance.

Query Plans

MongoDB executes queries using optimal plans.

Distributed Queries

Describes how sharded clusters and replica sets affect the performance of read operations.

Read Operations Overview

Cursors

Query Optimization

Query Plans

Distributed Queries

Read Operations Overview

Read operations, or queries, retrieve data stored in the database. In MongoDB, queries select documents from a single collection.

Queries specify criteria, or conditions, that identify the documents that MongoDB returns to the clients. A query may include a projection that specifies the fields from the matching documents to return. The projection limits the amount of data that MongoDB returns to the client over the network.

Query Interface

For query operations, MongoDB provides a db.collection.find() method. The method accepts both the query criteria and projections and returns a cursor to the matching documents. You can optionally modify the query to impose limits, skips, and sort orders.

The following diagram highlights the components of a MongoDB query operation:

The next diagram shows the same query in SQL:

Example

db.users.find( { age: { $gt: 18 } }, { name: 1, address: 1 } ).limit(5)

This query selects the documents in the users collection that match the condition age is greater than 18. To specify the greater than condition, query criteria uses the greater than (i.e. $gt) query selection operator. The query returns at most 5 matching documents (or more precisely, a cursor to those documents). The matching documents will return with only the _id, name and address fields. See Projections for details.

See

SQL to MongoDB Mapping Chart for additional examples of MongoDB queries and the corresponding SQL statements.

Query Behavior

MongoDB queries exhibit the following behavior:

All queries in MongoDB address a single collection.

You can modify the query to impose limits, skips, and sort orders.

The order of documents returned by a query is not defined unless you specify a sort().

Operations that modify existing documents (i.e. updates) use the same query syntax as queries to select documents to update.

In aggregation pipeline, the $match pipeline stage provides access to MongoDB queries.

MongoDB provides a db.collection.findOne() method as a special case of find() that returns a single document.

Query Statements

Consider the following diagram of the query process that specifies a query criteria and a sort modifier:

In the diagram, the query selects documents from the users collection. Using a query selection operator to define the conditions for matching documents, the query selects documents that have age greater than (i.e. $gt) 18. Then the sort() modifier sorts the results by age in ascending order.

For additional examples of queries, see Query Documents.

Projections

Queries in MongoDB return all fields in all matching documents by default. To limit the amount of data that MongoDB sends to applications, include a projection in the queries. By projecting results with a subset of fields, applications reduce their network overhead and processing requirements.

Projections, which are the second argument to the find() method, may either specify a list of fields to return or list fields to exclude in the result documents.

Important

Except for excluding the _id field in inclusive projections, you cannot mix exclusive and inclusive projections.

Consider the following diagram of the query process that specifies a query criteria and a projection:

In the diagram, the query selects from the users collection. The criteria matches the documents that have age equal to 18. Then the projection specifies that only the name field should return in the matching documents.

Projection Examples

Exclude One Field From a Result Set

db.records.find( { "user_id": { $lt: 42 } }, { "history": 0 } )

This query selects documents in the records collection that match the condition { "user_id": { $lt: 42 } }, and uses the projection { "history": 0 } to exclude the history field from the documents in the result set.

Return Two fields and the _id Field

db.records.find( { "user_id": { $lt: 42 } }, { "name": 1, "email": 1 } )

This query selects documents in the records collection that match the query { "user_id": { $lt: 42 } } and uses the projection { "name": 1, "email": 1 } to return just the _id field (implicitly included), name field, and the email field in the documents in the result set.

Return Two Fields and Exclude _id

db.records.find( { "user_id": { $lt: 42} }, { "_id": 0, "name": 1 , "email": 1 } )

This query selects documents in the records collection that match the query { "user_id": { $lt: 42} }, and only returns the name and email fields in the documents in the result set.

See

Limit Fields to Return from a Query for more examples of queries with projection statements.

Projection Behavior

MongoDB projections have the following properties:

By default, the _id field is included in the results. To suppress the _id field from the result set, specify _id: 0 in the projection document.

For fields that contain arrays, MongoDB provides the following projection operators: $elemMatch, $slice, and $.

For related projection functionality in the aggregation framework pipeline, use the $project pipeline stage.

Cursors

In the mongo shell, the primary method for the read operation is the db.collection.find() method. This method queries a collection and returns a cursor to the returning documents.

To access the documents, you need to iterate the cursor. However, in the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, then the cursor is automatically iterated up to 20 times [1] to print up to the first 20 documents in the results.

For example, in the mongo shell, the following read operation queries the inventory collection for documents that have type equal to 'food' and automatically print up to the first 20 matching documents:

db.inventory.find( { type: 'food' } );

To manually iterate the cursor to access the documents, see Iterate a Cursor in the mongo Shell.

[1]
You can use the DBQuery.shellBatchSize to change the number of iteration from the default value 20. See Executing Queries for more information.

Cursor Behaviors

Closure of Inactive Cursors

By default, the server will automatically close the cursor after 10 minutes of inactivity or if client has exhausted the cursor. To override this behavior, you can specify the noTimeout wire protocol flag [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol] in your query; however, you should either close the cursor manually or exhaust the cursor. In the mongo shell, you can set the noTimeout flag:

var myCursor = db.inventory.find().addOption(DBQuery.Option.noTimeout);

See your driver documentation for information on setting the noTimeout flag. For the mongo shell, see cursor.addOption() for a complete list of available cursor flags.

Cursor Isolation

Because the cursor is not isolated during its lifetime, intervening write operations on a document may result in a cursor that returns a document more than once if that document has changed. To handle this situation, see the information on snapshot mode.

Cursor Batches

The MongoDB server returns the query results in batches. Batch size will not exceed the maximum BSON document size. For most queries, the first batch returns 101 documents or just enough documents to exceed 1 megabyte. Subsequent batch size is 4 megabytes. To override the default size of the batch, see batchSize() and limit().

For queries that include a sort operation without an index, the server must load all the documents in memory to perform the sort before returning any results.

As you iterate through the cursor and reach the end of the returned batch, if there are more results, cursor.next() will perform a getmore operation to retrieve the next batch. To see how many documents remain in the batch as you iterate the cursor, you can use the objsLeftInBatch() method, as in the following example:

var myCursor = db.inventory.find();

var myFirstDocument = myCursor.hasNext() ? myCursor.next() : null;

myCursor.objsLeftInBatch();

Cursor Information

The db.serverStatus() method returns a document that includes a metrics field. The metrics field contains a cursor field with the following information:

number of timed out cursors since the last server restart

number of open cursors with the option DBQuery.Option.noTimeout set to prevent timeout after a period of inactivity

number of “pinned” open cursors

total number of open cursors

Consider the following example which calls the db.serverStatus() method and accesses the metrics field from the results and then the cursor field from the metrics field:

db.serverStatus().metrics.cursor

The result is the following document:

{
   "timedOut" : <number>
   "open" : {
      "noTimeout" : <number>,
      "pinned" : <number>,
      "total" : <number>
   }
}

See also

db.serverStatus()

Query Optimization

Indexes improve the efficiency of read operations by reducing the amount of data that query operations need to process. This simplifies the work associated with fulfilling queries within MongoDB.

Create an Index to Support Read Operations

If your application queries a collection on a particular field or set of fields, then an index on the queried field or a compound index on the set of fields can prevent the query from scanning the whole collection to find and return the query results. For more information about indexes, see the complete documentation of indexes in MongoDB.

Example

An application queries the inventory collection on the type field. The value of the type field is user-driven.

var typeValue = <someUserInput>;
db.inventory.find( { type: typeValue } );

To improve the performance of this query, add an ascending, or a descending, index to the inventory collection on the type field. [1] In the mongo shell, you can create indexes using the db.collection.ensureIndex() method:

db.inventory.ensureIndex( { type: 1 } )

This index can prevent the above query on type from scanning the whole collection to return the results.

To analyze the performance of the query with an index, see Analyze Query Performance.

In addition to optimizing read operations, indexes can support sort operations and allow for a more efficient storage utilization. See db.collection.ensureIndex() and Indexing Tutorials for more information about index creation.

[1]
For single-field indexes, the selection between ascending and descending order is immaterial. For compound indexes, the selection is important. See indexing order for more details.

Query Selectivity

Query selectivity refers to how well the query predicate excludes or filters out documents in a collection. Query selectivity can determine whether or not queries can use indexes effectively or even use indexes at all.

More selective queries match a smaller percentage of documents. For instance, an equality match on the unique _id field is highly selective as it can match at most one document.

Less selective queries match a larger percentage of documents. Less selective queries cannot use indexes effectively or even at all.

For instance, the inequality operators $nin and $ne are not very selective since they often match a large portion of the index. As a result, in many cases, a $nin or $ne query with an index may perform no better than a $nin or $ne query that must scan all documents in a collection.

The selectivity of regular expressions depends on the expressions themselves. For details, see regular expression and index use.

Covering a Query

An index covers a query when both of the following apply:

all the fields in the query are part of an index, and

all the fields returned in the results are in the same index.

For example, a collection inventory has the following index on the type and item fields:

db.inventory.ensureIndex( { type: 1, item: 1 } )

This index will cover the following operation which queries on the type and item fields and returns only the item field:

db.inventory.find(
   { type: "food", item:/^c/ },
   { item: 1, _id: 0 }
)

For the specified index to cover the query, the projection document must explicitly specify _id: 0 to exclude the _id field from the result since the index does not include the _id field.

Performance

Because the index contains all fields required by the query, MongoDB can both match the query conditions and return the results using only the index.

Querying only the index can be much faster than querying documents outside of the index. Index keys are typically smaller than the documents they catalog, and indexes are typically available in RAM or located sequentially on disk.

Limitations

An index cannot cover a query if:

the query is on a sharded collection and run against a mongos.

Changed in version 2.6.4: In earlier versions, an index cannot cover a query on a sharded collection when run against either a mongos or the primary.

any of the indexed fields in any of the documents in the collection includes an array. If an indexed field is an array, the index becomes a multi-key index index and cannot support a covered query.

any of the indexed field in the query predicate or returned in the projection are fields in embedded documents. [2] For example, consider a collection users with documents of the following form:

{ _id: 1, user: { login: "tester" } }

The collection has the following index:

{ "user.login": 1 }

The { "user.login": 1 } index does not cover the following query:

db.users.find( { "user.login": "tester" }, { "user.login": 1, _id: 0 } )

However, the query can use the { "user.login": 1 } index to find matching documents.

indexOnly

To determine whether a query is a covered query, use the explain() method. If the explain() output displays true for the indexOnly field, an index covers the query, and MongoDB queries only that index to match the query and return the results.

For more information see Measure Index Use.

[2]
To index fields in embedded documents, use dot notation.

Query Plans

The MongoDB query optimizer processes queries and chooses the most efficient query plan for a query given the available indexes. The query system then uses this query plan each time the query runs.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

The query optimizer occasionally reevaluates query plans as the content of the collection changes to ensure optimal query plans. You can also specify which indexes the optimizer evaluates with Index Filters.

You can use the explain() method to view statistics about the query plan for a given query. This information can help as you develop indexing strategies.

Query Optimization

To create a new query plan, the query optimizer:

runs the query against several candidate indexes in parallel.

records the matches in a common results buffer or buffers.

If the candidate plans include only ordered query plans, there is a single common results buffer.

If the candidate plans include only unordered query plans, there is a single common results buffer.

If the candidate plans include both ordered query plans and unordered query plans, there are two common results buffers, one for the ordered plans and the other for the unordered plans.

If an index returns a result already returned by another index, the optimizer skips the duplicate match. In the case of the two buffers, both buffers are de-duped.

stops the testing of candidate plans and selects an index when one of the following events occur:

An unordered query plan has returned all the matching results; or

An ordered query plan has returned all the matching results; or

An ordered query plan has returned a threshold number of matching results:

Version 2.0: Threshold is the query batch size. The default batch size is 101.

Version 2.2: Threshold is 101.

The selected index becomes the index specified in the query plan; future iterations of this query or queries with the same query pattern will use this index. Query pattern refers to query select conditions that differ only in the values, as in the following two queries with the same query pattern:

db.inventory.find( { type: 'food' } )
db.inventory.find( { type: 'utensil' } )

Query Plan Revision

As collections change over time, the query optimizer deletes the query plan and re-evaluates after any of the following events:

The collection receives 1,000 write operations.

The reIndex rebuilds the index.

You add or drop an index.

The mongod process restarts.

You run a query with explain().

Cached Query Plan Interface

New in version 2.6.

MongoDB provides Query Plan Cache Methods to view and modify the cached query plans.

Index Filters

New in version 2.6.

Index filters determine which indexes the optimizer evaluates for a query shape. A query shape consists of a combination of query, sort, and projection specifications. If an index filter exists for a given query shape, the optimizer only considers those indexes specified in the filter.

When an index filter exists for the query shape, MongoDB ignores the hint(). To see whether MongoDB applied an index filter for a query, check the explain.filterSet field of the explain() output.

Index filters only affects which indexes the optimizer evaluates; the optimizer may still select the collection scan as the winning plan for a given query shape.

Index filters exist for the duration of the server process and do not persist after shutdown. MongoDB also provides a command to manually remove filters.

Because index filters overrides the expected behavior of the optimizer as well as the hint() method, use index filters sparingly.

See planCacheListFilters, planCacheClearFilters, and planCacheSetFilter.

Distributed Queries

Read Operations to Sharded Clusters

Sharded clusters allow you to partition a data set among a cluster of mongod instances in a way that is nearly transparent to the application. For an overview of sharded clusters, see the Sharding section of this manual.

For a sharded cluster, applications issue operations to one of the mongos instances associated with the cluster.

Read operations on sharded clusters are most efficient when directed to a specific shard. Queries to sharded collections should include the collection’s shard key. When a query includes a shard key, the mongos can use cluster metadata from the config database to route the queries to shards.

If a query does not include the shard key, the mongos must direct the query to all shards in the cluster. These scatter gather queries can be inefficient. On larger clusters, scatter gather queries are unfeasible for routine operations.

For more information on read operations in sharded clusters, see the Sharded Cluster Query Routing and Shard Keys sections.

Read Operations to Replica Sets

Replica sets use read preferences to determine where and how to route read operations to members of the replica set. By default, MongoDB always reads data from a replica set’s primary. You can modify that behavior by changing the read preference mode.

You can configure the read preference mode on a per-connection or per-operation basis to allow reads from secondaries to:

reduce latency in multi-data-center deployments,

improve read throughput by distributing high read-volumes (relative to write volume),

for backup operations, and/or

to allow reads during failover situations.

Read operations from secondary members of replica sets are not guaranteed to reflect the current state of the primary, and the state of secondaries will trail the primary by some amount of time. Often, applications don’t rely on this kind of strict consistency, but application developers should always consider the needs of their application before setting read preference.

For more information on read preference or on the read preference modes, see Read Preference and Read Preference Modes.

Write Operations

The following documents describe write operations:

Write Operations Overview

Provides an overview of MongoDB’s data insertion and modification operations, including aspects of the syntax, and behavior.

Write Concern

Describes the kind of guarantee MongoDB provides when reporting on the success of a write operation.

Atomicity and Transactions

Describes write operation atomicity in MongoDB.

Distributed Write Operations

Describes how MongoDB directs write operations on sharded clusters and replica sets and the performance characteristics of these operations.

Write Operation Performance

Introduces the performance constraints and factors for writing data to MongoDB deployments.

Bulk Write Operations

Provides an overview of MongoDB’s bulk write operations.

Storage

Introduces the storage allocation strategies available for MongoDB collections.

Write Operations Overview

Write Concern

Atomicity and Transactions

Distributed Write Operations

Write Operation Performance

Bulk Write Operations

Storage

Write Operations Overview

A write operation is any operation that creates or modifies data in the MongoDB instance. In MongoDB, write operations target a single collection. All write operations in MongoDB are atomic on the level of a single document.

There are three classes of write operations in MongoDB: insert, update, and remove. Insert operations add new data to a collection. Update operations modify existing data, and remove operations delete data from a collection. No insert, update, or remove can affect more than one document atomically.

For the update and remove operations, you can specify criteria, or conditions, that identify the documents to update or remove. These operations use the same query syntax to specify the criteria as read operations.

MongoDB allows applications to determine the acceptable level of acknowledgement required of write operations. See Write Concern for more information.

Insert

In MongoDB, the db.collection.insert() method adds new documents to a collection.

The following diagram highlights the components of a MongoDB insert operation:

The following diagram shows the same query in SQL:

Example

The following operation inserts a new document into the users collection. The new document has four fields name, age, and status, and an _id field. MongoDB always adds the _id field to the new document if that field does not exist.

db.users.insert(
   {
      name: "sue",
      age: 26,
      status: "A"
   }
)

For more information and examples, see db.collection.insert().

Insert Behavior

If you add a new document without the _id field, the client library or the mongod instance adds an _id field and populates the field with a unique ObjectId.

If you specify the _id field, the value must be unique within the collection. For operations with write concern, if you try to create a document with a duplicate _id value, mongod returns a duplicate key exception.

Other Methods to Add Documents

You can also add new documents to a collection using methods that have an upsert option. If the option is set to true, these methods will either modify existing documents or add a new document when no matching documents exist for the query. For more information, see Update Behavior with the upsert Option.

Update

In MongoDB, the db.collection.update() method modifies existing documents in a collection. The db.collection.update() method can accept query criteria to determine which documents to update as well as an options document that affects its behavior, such as the multi option to update multiple documents.

Operations performed by an update are atomic within a single document. For example, you can safely use the $inc and $mul operators to modify frequently-changed fields in concurrent applications.

The following diagram highlights the components of a MongoDB update operation:

The following diagram shows the same query in SQL:

Example

db.users.update(
   { age: { $gt: 18 } },
   { $set: { status: "A" } },
   { multi: true }
)

This update operation on the users collection sets the status field to A for the documents that match the criteria of age greater than 18.

For more information, see db.collection.update() and update() Examples.

Default Update Behavior

By default, the db.collection.update() method updates a single document. However, with the multi option, update() can update all documents in a collection that match a query.

The db.collection.update() method either updates specific fields in the existing document or replaces the document. See db.collection.update() for details as well as examples.

When performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk.

MongoDB preserves the order of the document fields following write operations except for the following cases:

The _id field is always the first field in the document.

Updates that include renaming of field names may result in the reordering of fields in the document.

Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.

Update Behavior with the upsert Option

If the update() method includes upsert: true and no documents match the query portion of the update operation, then the update operation creates a new document. If there are matching documents, then the update operation with the upsert: true modifies the matching document or documents.

By specifying upsert: true, applications can indicate, in a single operation, that if no matching documents are found for the update, an insert should be performed. See update() for details on performing an upsert.

Changed in version 2.6: In 2.6, the new Bulk() methods and the underlying update command allow you to perform many updates with upsert: true operations in a single call.

If you create documents using the upsert option to update() consider using a a unique index to prevent duplicated operations.

Remove

In MongoDB, the db.collection.remove() method deletes documents from a collection. The db.collection.remove() method accepts a query criteria to determine which documents to remove.

The following diagram highlights the components of a MongoDB remove operation:

The following diagram shows the same query in SQL:

Example

db.users.remove(
   { status: "D" }
)

This delete operation on the users collection removes all documents that match the criteria of status equal to D.

For more information, see db.collection.remove() method and Remove Documents.

Remove Behavior

By default, db.collection.remove() method removes all documents that match its query. However, the method can accept a flag to limit the delete operation to a single document.

Isolation of Write Operations

The modification of a single document is always atomic, even if the write operation modifies multiple embedded documents within that document. No other operations are atomic.

If a write operation modifies multiple documents, the operation as a whole is not atomic, and other operations may interleave. You can, however, attempt to isolate a write operation that affects multiple documents using the isolation operator.

For more information Atomicity and Transactions.

Additional Methods

The db.collection.save() method can either update an existing document or insert a document if the document cannot be found by the _id field. See db.collection.save() for more information and examples.

MongoDB also provides methods to perform write operations in bulk. See Bulk() for more information.

Write Concern

Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concerns determine the level of guarantee. When inserts, updates and deletes have a weak write concern, write operations return quickly. In some failure cases, write operations issued with weak write concerns may not persist. With stronger write concerns, clients wait after sending a write operation for MongoDB to confirm the write operations.

MongoDB provides different levels of write concern to better address the specific needs of applications. Clients may adjust write concern to ensure that the most important operations persist successfully to an entire MongoDB deployment. For other less critical operations, clients can adjust the write concern to ensure faster performance rather than ensure persistence to the entire deployment.

Changed in version 2.6: A new protocol for write operations integrates write concern with the write operations.

For details on write concern configurations, see Write Concern Reference.

Considerations

Default Write Concern

The mongo shell and the MongoDB drivers use Acknowledged as the default write concern.

See Acknowledged for more information, including when this write concern became the default.

Read Isolation

MongoDB allows clients to read documents inserted or modified before it commits these modifications to disk, regardless of write concern level or journaling configuration. As a result, applications may observe two classes of behaviors:

For systems with multiple concurrent readers and writers, MongoDB will allow clients to read the results of a write operation before the write operation returns.

If the mongod terminates before the journal commits, even if a write returns successfully, queries may have read data that will not exist after the mongod restarts.

Other database systems refer to these isolation semantics as read uncommitted. For all inserts and updates, MongoDB modifies each document in isolation: clients never see documents in intermediate states. For multi-document operations, MongoDB does not provide any multi-document transactions or isolation.

When mongod returns a successful journaled write concern, the data is fully committed to disk and will be available after mongod restarts.

For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of the voting members of the set. [1] MongoDB regularly commits data to the journal regardless of journaled write concern: use the commitIntervalMs to control how often a mongod commits the journal.

[1]
For the purposes of write concern, w:majority refers to a majority of all the members in the set. As a result, arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

Timeouts

Clients can set a wtimeout value as part of a replica acknowledged write concern. If the write concern is not satisfied in the specified interval, the operation returns an error, even if the write concern will eventually succeed.

MongoDB does not “rollback” or undo modifications made before the wtimeout interval expired.

Write Concern Levels

MongoDB has the following levels of conceptual write concern, listed from weakest to strongest:

Unacknowledged

With an unacknowledged write concern, MongoDB does not acknowledge the receipt of write operations. Unacknowledged is similar to errors ignored; however, drivers will attempt to receive and handle network errors when possible. The driver’s ability to detect network errors depends on the system’s networking configuration.

Before the releases outlined in Default Write Concern Change, this was the default write concern.

Acknowledged

With a receipt acknowledged write concern, the mongod confirms that it received the write operation and applied the change to the in-memory view of data. Acknowledged write concern allows clients to catch network, duplicate key, and other errors.

MongoDB uses the acknowledged write concern by default starting in the driver releases outlined in Releases.

Changed in version 2.6: The mongo shell write methods now incorporates the write concern in the write methods and provide the default write concern whether run interactively or in a script. See Write Method Acknowledgements for details.

Acknowledged write concern does not confirm that the write operation has persisted to the disk system.

Journaled

With a journaled write concern, the MongoDB acknowledges the write operation only after committing the data to the journal. This write concern ensures that MongoDB can recover the data following a shutdown or power interruption.

You must have journaling enabled to use this write concern.

With a journaled write concern, write operations must wait for the next journal commit. To reduce latency for these operations, MongoDB also increases the frequency that it commits operations to the journal. See commitIntervalMs for more information.

Note

Requiring journaled write concern in a replica set only requires a journal commit of the write operation to the primary of the set regardless of the level of replica acknowledged write concern.

Replica Acknowledged

Replica sets present additional considerations with regards to write concern. The default write concern only requires acknowledgement from the primary.

With replica acknowledged write concern, you can guarantee that the write operation propagates to additional members of the replica set. See Write Concern for Replica Sets for more information.

Note

Requiring journaled write concern in a replica set only requires a journal commit of the write operation to the primary of the set regardless of the level of replica acknowledged write concern.

See also

Write Concern Reference

Atomicity and Transactions

In MongoDB, a write operation is atomic on the level of a single document, even if the operation modifies multiple embedded documents within a single document.

When a single write operation modifies multiple documents, the modification of each document is atomic, but the operation as a whole is not atomic and other operations may interleave. However, you can isolate a single write operation that affects multiple documents using the $isolated operator.

$isolated Operator

Using the $isolated operator, a write operation that affect multiple documents can prevent other processes from interleaving once the write operation modifies the first document. This ensures that no client sees the changes until the write operation completes or errors out.

Isolated write operation does not provide “all-or-nothing” atomicity. That is, an error during the write operation does not roll back all its changes that preceded the error.

The $isolated does not work on sharded clusters.

For an example of an update operation that uses the $isolated operator, see $isolated. For an example of a remove operation that uses the $isolated operator, see Isolate Remove Operations.

Transaction-Like Semantics

Since a single document can contain multiple embedded documents, single-document atomicity is sufficient for many practical use cases. For cases where a sequence of write operations must operate as if in a single transaction, you can implement a two-phase commit in your application.

However, two-phase commits can only offer transaction-like semantics. Using two-phase commit ensures data consistency, but it is possible for applications to return intermediate data during the two-phase commit or rollback.

For more information on two-phase commit and rollback, see Perform Two Phase Commits.

Concurrency Control

Concurrency control allows multiple applications to run concurrently without causing data inconsistency or conflicts.

An approach may be to create a unique index on a field (or fields) that should have only unique values (or unique combination of values) prevents duplicate insertions or updates that result in duplicate values. For examples of use cases, see update() and Unique Index and findAndModify() and Unique Index.

Another approach is to specify the expected current value of a field in the query predicate for the write operations. For an example, see Update if Current.

The two-phase commit pattern provides a variation where the query predicate includes the application identifier as well as the expected state of the data in the write operation.

Distributed Write Operations

Write Operations on Sharded Clusters

For sharded collections in a sharded cluster, the mongos directs write operations from applications to the shards that are responsible for the specific portion of the data set. The mongos uses the cluster metadata from the config database to route the write operation to the appropriate shards.

MongoDB partitions data in a sharded collection into ranges based on the values of the shard key. Then, MongoDB distributes these chunks to shards. The shard key determines the distribution of chunks to shards. This can affect the performance of write operations in the cluster.

Important

Update operations that affect a single document must include the shard key or the _id field. Updates that affect multiple documents are more efficient in some situations if they have the shard key, but can be broadcast to all shards.

If the value of the shard key increases or decreases with every insert, all insert operations target a single shard. As a result, the capacity of a single shard becomes the limit for the insert capacity of the sharded cluster.

For more information, see Sharded Cluster Tutorials and Bulk Write Operations.

Write Operations on Replica Sets

In replica sets, all write operations go to the set’s primary, which applies the write operation then records the operations on the primary’s operation log or oplog. The oplog is a reproducible sequence of operations to the data set. Secondary members of the set are continuously replicating the oplog and applying the operations to themselves in an asynchronous process.

Large volumes of write operations, particularly bulk operations, may create situations where the secondary members have difficulty applying the replicating operations from the primary at a sufficient rate: this can cause the secondary’s state to fall behind that of the primary. Secondaries that are significantly behind the primary present problems for normal operation of the replica set, particularly failover in the form of rollbacks as well as general read consistency.

To help avoid this issue, you can customize the write concern to return confirmation of the write operation to another member [1] of the replica set every 100 or 1,000 operations. This provides an opportunity for secondaries to catch up with the primary. Write concern can slow the overall progress of write operations but ensure that the secondaries can maintain a largely current state with respect to the primary.

For more information on replica sets and write operations, see Replica Acknowledged, Oplog Size, and Change the Size of the Oplog.

[1]

Intermittently issuing a write concern with a w value of 2 or majority will slow the throughput of write traffic; however, this practice will allow the secondaries to remain current with the state of the primary.

Changed in version 2.6: In Master/Slave deployments, MongoDB treats w: "majority" as equivalent to w: 1. In earlier versions of MongoDB, w: "majority" produces an error in master/slave deployments.

Write Operation Performance

Indexes

After every insert, update, or delete operation, MongoDB must update every index associated with the collection in addition to the data itself. Therefore, every index on a collection adds some amount of overhead for the performance of write operations. [1]

In general, the performance gains that indexes provide for read operations are worth the insertion penalty. However, in order to optimize write performance when possible, be careful when creating new indexes and evaluate the existing indexes to ensure that your queries actually use these indexes.

For indexes and queries, see Query Optimization. For more information on indexes, see Indexes and Indexing Strategies.

[1]
For inserts and updates to un-indexed fields, the overhead for sparse indexes is less than for non-sparse indexes. Also for non-sparse indexes, updates that do not change the record size have less indexing overhead.

Document Growth

If an update operation causes a document to exceed the currently allocated record size, MongoDB relocates the document on disk with enough contiguous space to hold the document. These relocations take longer than in-place updates, particularly if the collection has indexes. If a collection has indexes, MongoDB must update all index entries. Thus, for a collection with many indexes, the move will impact the write throughput.

Some update operations, such as the $inc operation, do not cause an increase in document size. For these update operations, MongoDB can apply the updates in-place. Other update operations, such as the $push operation, change the size of the document.

In-place-updates are significantly more efficient than updates that cause document growth. When possible, use data models that minimize the need for document growth.

See Storage for more information.

Storage Performance

Hardware

The capability of the storage system creates some important physical limits for the performance of MongoDB’s write operations. Many unique factors related to the storage system of the drive affect write performance, including random access patterns, disk caches, disk readahead and RAID configurations.

Solid state drives (SSDs) can outperform spinning hard disks (HDDs) by 100 times or more for random workloads.

See

Production Notes for recommendations regarding additional hardware and configuration options.

Journaling

MongoDB uses write ahead logging to an on-disk journal to guarantee write operation durability and to provide crash resiliency. Before applying a change to the data files, MongoDB writes the change operation to the journal.

While the durability assurance provided by the journal typically outweigh the performance costs of the additional write operations, consider the following interactions between the journal and performance:

if the journal and the data file reside on the same block device, the data files and the journal may have to contend for a finite number of available write operations. Moving the journal to a separate device may increase the capacity for write operations.

if applications specify write concern that includes journaled, mongod will decrease the duration between journal commits, which can increases the overall write load.

the duration between journal commits is configurable using the commitIntervalMs run-time option. Decreasing the period between journal commits will increase the number of write operations, which can limit MongoDB’s capacity for write operations. Increasing the amount of time between commits may decrease the total number of write operation, but also increases the chance that the journal will not record a write operation in the event of a failure.

For additional information on journaling, see Journaling Mechanics.

Bulk Write Operations

Overview

MongoDB provides clients the ability to perform write operations in bulk. Bulk write operations affect a single collection. MongoDB allows applications to determine the acceptable level of acknowledgement required for bulk write operations.

New Bulk methods provide the ability to perform bulk insert, update, and remove operations. MongoDB also supports bulk insert through passing an array of documents to the db.collection.insert() method.

Changed in version 2.6: Previous versions of MongoDB provided the ability for bulk inserts only. With previous versions, clients could perform bulk inserts by passing an array of documents to the db.collection.insert() [http://docs.mongodb.org/v2.4/core/bulk-inserts] method. To see the documentation for earlier versions, see Bulk Inserts [http://docs.mongodb.org/v2.4/core/bulk-inserts].

Ordered vs Unordered Operations

Bulk write operations can be either ordered or unordered. With an ordered list of operations, MongoDB executes the operations serially. If an error occurs during the processing of one of the write operations, MongoDB will return without processing any remaining write operations in the list.

With an unordered list of operations, MongoDB can execute the operations in parallel. If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.

Bulk Methods

To use the Bulk() methods:

Initialize a list of operations using either db.collection.initializeUnorderedBulkOp() or db.collection.initializeOrderedBulkOp().

Add write operations to the list using the following methods:

Bulk.insert()

Bulk.find()

Bulk.find.upsert()

Bulk.find.update()

Bulk.find.updateOne()

Bulk.find.replaceOne()

Bulk.find.remove()

Bulk.find.removeOne()

To execute the list of operations, use the Bulk.execute() method. You can specify the write concern for the list in the Bulk.execute() method.

Once executed, you cannot re-execute the list without reinitializing.

For example,

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { _id: 1, item: "abc123", status: "A", soldQty: 5000 } );
bulk.insert( { _id: 2, item: "abc456", status: "A", soldQty: 150 } );
bulk.insert( { _id: 3, item: "abc789", status: "P", soldQty: 0 } );
bulk.execute( { w: "majority", wtimeout: 5000 } );

For more examples, refer to the reference page for each Bulk Operation Methods method. For information and examples on performing bulk insert using the db.collection.insert(), see db.collection.insert().

See also

New Write Operation Protocol

Bulk Execution Mechanics

When executing an ordered list of operations, MongoDB groups adjacent operations by the operation type. When executing an unordered list of operations, MongoDB groups and may also reorder the operations to increase performance. As such, when performing unordered bulk operations, applications should not depend on the ordering.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

For more information, see Bulk.execute().

Strategies for Bulk Inserts to a Sharded Collection

Large bulk insert operations, including initial data inserts or routine data import, can affect sharded cluster performance. For bulk inserts, consider the following strategies:

Pre-Split the Collection

If the sharded collection is empty, then the collection has only one initial chunk, which resides on a single shard. MongoDB must then take time to receive data, create splits, and distribute the split chunks to the available shards. To avoid this performance cost, you can pre-split the collection, as described in Split Chunks in a Sharded Cluster.

Insert to Multiple mongos

To parallelize import processes, send bulk insert or insert operations to more than one mongos instance. For empty collections, first pre-split the collection as described in Split Chunks in a Sharded Cluster.

Avoid Monotonic Throttling

If your shard key increases monotonically during an insert, then all inserted data goes to the last chunk in the collection, which will always end up on a single shard. Therefore, the insert capacity of the cluster will never exceed the insert capacity of that single shard.

If your insert volume is larger than what a single shard can process, and if you cannot avoid a monotonically increasing shard key, then consider the following modifications to your application:

Reverse the binary bits of the shard key. This preserves the information and avoids correlating insertion order with increasing sequence of values.

Swap the first and last 16-bit words to “shuffle” the inserts.

Example

The following example, in C++, swaps the leading and trailing 16-bit word of BSON ObjectIds generated so they are no longer monotonically increasing.

using namespace mongo;
OID make_an_id() {
  OID x = OID::gen();
  const unsigned char *p = x.getData();
  swap( (unsigned short&) p[0], (unsigned short&) p[10] );
  return x;
}

void foo() {
  // create an object
  BSONObj o = BSON( "_id" << make_an_id() << "x" << 3 << "name" << "jane" );
  // now we may insert o into a sharded collection
}

See also

Shard Keys for information on choosing a sharded key. Also see Shard Key Internals (in particular, Choosing a Shard Key).

Storage

Data Model

MongoDB stores data in the form of BSON documents, which are rich mappings of keys, or field names, to values. BSON supports a rich collection of types, and fields in BSON documents may hold arrays of values or embedded documents. All documents in MongoDB must be less than 16MB, which is the BSON document size.

Every document in MongoDB is stored in a record which contains the document itself and extra space, or padding, which allows the document to grow as the result of updates.

All records are contiguously located on disk, and when a document becomes larger than the allocated record, MongoDB must allocate a new record. New allocations require MongoDB to move a document and update all indexes that refer to the document, which takes more time than in-place updates and leads to storage fragmentation.

All records are part of a collection, which is a logical grouping of documents in a MongoDB database. The documents in a collection share a set of indexes, and typically these documents share common fields and structure.

In MongoDB the database construct is a group of related collections. Each database has a distinct set of data files and can contain a large number of collections. Also, each database has one distinct write lock, that blocks operations to the database during write operations. A single MongoDB deployment may have many databases.

Journal

In order to ensure that all modifications to a MongoDB data set are durably written to disk, MongoDB records all modifications to a journal that it writes to disk more frequently than it writes the data files. The journal allows MongoDB to successfully recover data from data files after a mongod instance exits without flushing all changes.

See Journaling Mechanics for more information about the journal in MongoDB.

Record Allocation Strategies

MongoDB supports multiple record allocation strategies that determine how mongod adds padding to a document when creating a record. Because documents in MongoDB may grow after insertion and all records are contiguous on disk, the padding can reduce the need to relocate documents on disk following updates. Relocations are less efficient than in-place updates, and can lead to storage fragmentation. As a result, all padding strategies trade additional space for increased efficiency and decreased fragmentation.

Different allocation strategies support different kinds of workloads: the power of 2 allocations are more efficient for insert/update/delete workloads; while exact fit allocations is ideal for collections without update and delete workloads.

Power of 2 Sized Allocations

Changed in version 2.6: For all new collections, usePowerOf2Sizes became the default allocation strategy. To change the default allocation strategy, use the newCollectionsUsePowerOf2Sizes parameter.

mongod uses an allocation strategy called usePowerOf2Sizes where each record has a size in bytes that is a power of 2 (e.g. 32, 64, 128, 256, 512...16777216.) The smallest allocation for a document is 32 bytes. The power of 2 sizes allocation strategy has two key properties:

there are a limited number of record allocation sizes, which makes it easier for mongod to reuse existing allocations, which will reduce fragmentation in some cases.

in many cases, the record allocations are significantly larger than the documents they hold. This allows documents to grow while minimizing or eliminating the chance that the mongod will need to allocate a new record if the document grows.

The usePowerOf2Sizes strategy does not eliminate document reallocation as a result of document growth, but it minimizes its occurrence in many common operations.

Exact Fit Allocation

The exact fit allocation strategy allocates record sizes based on the size of the document and an additional padding factor. Each collection has its own padding factor, which defaults to 1 when you insert the first document in a collection. MongoDB dynamically adjusts the padding factor up to 2 depending on the rate of growth of the documents over the life of the collection.

To estimate total record size, compute the product of the padding factor and the size of the document. That is:

record size = paddingFactor * <document size>

The size of each record in a collection reflects the size of the padding factor at the time of allocation. See the paddingFactor field in the output of db.collection.stats() to see the current padding factor for a collection.

On average, this exact fit allocation strategy uses less storage space than the usePowerOf2Sizes strategy but will result in higher levels of storage fragmentation if documents grow beyond the size of their initial allocation.

The compact and repairDatabase operations remove padding by default, as do the mongodump and mongorestore. compact does allow you to specify a padding for records during compaction.

Capped Collections

Capped collections are fixed-size collections that support high-throughput operations that store records in insertion order. Capped collections work like circular buffers: once a collection fills its allocated space, it makes room for new documents by overwriting the oldest documents in the collection.

See Capped Collections for more information.

MongoDB CRUD Tutorials

The following tutorials provide instructions for querying and modifying data. For a higher-level overview of these operations, see MongoDB CRUD Operations.

Insert Documents

Insert new documents into a collection.

Query Documents

Find documents in a collection using search criteria.

Modify Documents

Modify documents in a collection

Remove Documents

Remove documents from a collection.

Limit Fields to Return from a Query

Limit which fields are returned by a query.

Limit Number of Elements in an Array after an Update

Use $push with modifiers to sort and maintain an array of fixed size.

Iterate a Cursor in the mongo Shell

Access documents returned by a find query by iterating the cursor, either manually or using the iterator index.

Analyze Query Performance

Use query introspection (i.e. explain) to analyze the efficiency of queries and determine how a query uses available indexes.

Perform Two Phase Commits

Use two-phase commits when writing data to multiple documents.

Update Document if Current

Update a document only if it has not changed since it was last read.

Create Tailable Cursor

Create tailable cursors for use in capped collections with high numbers of write operations for which an index would be too expensive.

Create an Auto-Incrementing Sequence Field

Describes how to create an incrementing sequence number for the _id field using a Counters Collection or an Optimistic Loop.

Insert Documents

Query Documents

Modify Documents

Remove Documents

Limit Fields to Return from a Query

Limit Number of Elements in an Array after an Update

Iterate a Cursor in the mongo Shell

Analyze Query Performance

Perform Two Phase Commits

Update Document if Current

Create Tailable Cursor

Create an Auto-Incrementing Sequence Field

Insert Documents

In MongoDB, the db.collection.insert() method adds new documents into a collection.

Insert a Document

1

Insert a document into a collection.

Insert a document into a collection named inventory. The operation will create the collection if the collection does not currently exist.

db.inventory.insert(
   {
     item: "ABC1",
     details: {
        model: "14Q3",
        manufacturer: "XYZ Company"
     },
     stock: [ { size: "S", qty: 25 }, { size: "M", qty: 50 } ],
     category: "clothing"
   }
)

The operation returns a WriteResult object with the status of the operation. A successful insert of the document returns the following object:

WriteResult({ "nInserted" : 1 })

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the WriteResult object will contain the error information.

Step 1: Insert a document into a collection.

Insert a document into a collection named inventory. The operation will create the collection if the collection does not currently exist.

db.inventory.insert(
   {
     item: "ABC1",
     details: {
        model: "14Q3",
        manufacturer: "XYZ Company"
     },
     stock: [ { size: "S", qty: 25 }, { size: "M", qty: 50 } ],
     category: "clothing"
   }
)

The operation returns a WriteResult object with the status of the operation. A successful insert of the document returns the following object:

WriteResult({ "nInserted" : 1 })

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the WriteResult object will contain the error information.

2

Review the inserted document.

If the insert operation is successful, verify the insertion by querying the collection.

db.inventory.find()

The document you inserted should return.

{ "_id" : ObjectId("53d98f133bb604791249ca99"), "item" : "ABC1", "details" : { "model" : "14Q3", "manufacturer" : "XYZ Company" }, "stock" : [ { "size" : "S", "qty" : 25 }, { "size" : "M", "qty" : 50 } ], "category" : "clothing" }

The returned document shows that MongoDB added an _id field to the document. If a client inserts a document that does not contain the _id field, MongoDB adds the field with the value set to a generated ObjectId [http://docs.mongodb.org/manual/reference/object-id]. The ObjectId [http://docs.mongodb.org/manual/reference/object-id] values in your documents will differ from the ones shown.

Step 2: Review the inserted document.

If the insert operation is successful, verify the insertion by querying the collection.

db.inventory.find()

The document you inserted should return.

{ "_id" : ObjectId("53d98f133bb604791249ca99"), "item" : "ABC1", "details" : { "model" : "14Q3", "manufacturer" : "XYZ Company" }, "stock" : [ { "size" : "S", "qty" : 25 }, { "size" : "M", "qty" : 50 } ], "category" : "clothing" }

The returned document shows that MongoDB added an _id field to the document. If a client inserts a document that does not contain the _id field, MongoDB adds the field with the value set to a generated ObjectId [http://docs.mongodb.org/manual/reference/object-id]. The ObjectId [http://docs.mongodb.org/manual/reference/object-id] values in your documents will differ from the ones shown.

Insert an Array of Documents

You can pass an array of documents to the db.collection.insert() method to insert multiple documents.

1

Create an array of documents.

Define a variable mydocuments that holds an array of documents to insert.

var mydocuments =
    [
      {
        item: "ABC2",
        details: { model: "14Q3", manufacturer: "M1 Corporation" },
        stock: [ { size: "M", qty: 50 } ],
        category: "clothing"
      },
      {
        item: "MNO2",
        details: { model: "14Q3", manufacturer: "ABC Company" },
        stock: [ { size: "S", qty: 5 }, { size: "M", qty: 5 }, { size: "L", qty: 1 } ],
        category: "clothing"
      },
      {
        item: "IJK2",
        details: { model: "14Q2", manufacturer: "M5 Corporation" },
        stock: [ { size: "S", qty: 5 }, { size: "L", qty: 1 } ],
        category: "houseware"
      }
    ];

Step 1: Create an array of documents.

Define a variable mydocuments that holds an array of documents to insert.

var mydocuments =
    [
      {
        item: "ABC2",
        details: { model: "14Q3", manufacturer: "M1 Corporation" },
        stock: [ { size: "M", qty: 50 } ],
        category: "clothing"
      },
      {
        item: "MNO2",
        details: { model: "14Q3", manufacturer: "ABC Company" },
        stock: [ { size: "S", qty: 5 }, { size: "M", qty: 5 }, { size: "L", qty: 1 } ],
        category: "clothing"
      },
      {
        item: "IJK2",
        details: { model: "14Q2", manufacturer: "M5 Corporation" },
        stock: [ { size: "S", qty: 5 }, { size: "L", qty: 1 } ],
        category: "houseware"
      }
    ];

2

Insert the documents.

Pass the mydocuments array to the db.collection.insert() to perform a bulk insert.

db.inventory.insert( mydocuments );

The method returns a BulkWriteResult object with the status of the operation. A successful insert of the documents returns the following object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 3,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the BulkWriteResult object will contain information regarding the error.

The inserted documents will each have an _id field added by MongoDB.

Step 2: Insert the documents.

Pass the mydocuments array to the db.collection.insert() to perform a bulk insert.

db.inventory.insert( mydocuments );

The method returns a BulkWriteResult object with the status of the operation. A successful insert of the documents returns the following object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 3,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the BulkWriteResult object will contain information regarding the error.

The inserted documents will each have an _id field added by MongoDB.

Insert Multiple Documents with Bulk

New in version 2.6.

MongoDB provides a Bulk() API that you can use to perform multiple write operations in bulk. The following sequence of operations describes how you would use the Bulk() API to insert a group of documents into a MongoDB collection.

1

Initialize a Bulk operations builder.

Initialize a Bulk operations builder for the collection inventory.

var bulk = db.inventory.initializeUnorderedBulkOp();

The operation returns an unordered operations builder which maintains a list of operations to perform. Unordered operations means that MongoDB can execute in parallel as well as in nondeterministic order. If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

You can also initialize an ordered operations builder; see db.collection.initializeOrderedBulkOp() for details.

Step 1: Initialize a Bulk operations builder.

Initialize a Bulk operations builder for the collection inventory.

var bulk = db.inventory.initializeUnorderedBulkOp();

The operation returns an unordered operations builder which maintains a list of operations to perform. Unordered operations means that MongoDB can execute in parallel as well as in nondeterministic order. If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

You can also initialize an ordered operations builder; see db.collection.initializeOrderedBulkOp() for details.

2

Add insert operations to the bulk object.

Add two insert operations to the bulk object using the Bulk.insert() method.

bulk.insert(
   {
     item: "BE10",
     details: { model: "14Q2", manufacturer: "XYZ Company" },
     stock: [ { size: "L", qty: 5 } ],
     category: "clothing"
   }
);
bulk.insert(
   {
     item: "ZYT1",
     details: { model: "14Q1", manufacturer: "ABC Company"  },
     stock: [ { size: "S", qty: 5 }, { size: "M", qty: 5 } ],
     category: "houseware"
   }
);

Step 2: Add insert operations to the bulk object.

Add two insert operations to the bulk object using the Bulk.insert() method.

bulk.insert(
   {
     item: "BE10",
     details: { model: "14Q2", manufacturer: "XYZ Company" },
     stock: [ { size: "L", qty: 5 } ],
     category: "clothing"
   }
);
bulk.insert(
   {
     item: "ZYT1",
     details: { model: "14Q1", manufacturer: "ABC Company"  },
     stock: [ { size: "S", qty: 5 }, { size: "M", qty: 5 } ],
     category: "houseware"
   }
);

3

Execute the bulk operation.

Call the execute() method on the bulk object to execute the operations in its list.

bulk.execute();

The method returns a BulkWriteResult object with the status of the operation. A successful insert of the documents returns the following object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the BulkWriteResult object will contain information regarding the error.

Step 3: Execute the bulk operation.

Call the execute() method on the bulk object to execute the operations in its list.

bulk.execute();

The method returns a BulkWriteResult object with the status of the operation. A successful insert of the documents returns the following object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

The nInserted field specifies the number of documents inserted. If the operation encounters an error, the BulkWriteResult object will contain information regarding the error.

Additional Examples and Methods

For more examples, see db.collection.insert().

The db.collection.update() method, the db.collection.findAndModify(), and the db.collection.save() method can also add new documents. See the individual reference pages for the methods for more information and examples.

Query Documents

In MongoDB, the db.collection.find() method retrieves documents from a collection. [1] The db.collection.find() method returns a cursor to the retrieved documents.

This tutorial provides examples of read operations using the db.collection.find() method in the mongo shell. In these examples, the retrieved documents contain all their fields. To restrict the fields to return in the retrieved documents, see Limit Fields to Return from a Query.

[1]
The db.collection.findOne() method also performs a read operation to return a single document. Internally, the db.collection.findOne() method is the db.collection.find() method with a limit of 1.

Select All Documents in a Collection

An empty query document ({}) selects all documents in the collection:

db.inventory.find( {} )

Not specifying a query document to the find() is equivalent to specifying an empty query document. Therefore the following operation is equivalent to the previous operation:

db.inventory.find()

Specify Equality Condition

To specify equality condition, use the query document { <field>: <value> } to select all documents that contain the <field> with the specified <value>.

The following example retrieves from the inventory collection all documents where the type field has the value snacks:

db.inventory.find( { type: "snacks" } )

Specify Conditions Using Query Operators

A query document can use the query operators to specify conditions in a MongoDB query.

The following example selects all documents in the inventory collection where the value of the type field is either 'food' or 'snacks':

db.inventory.find( { type: { $in: [ 'food', 'snacks' ] } } )

Although you can express this query using the $or operator, use the $in operator rather than the $or operator when performing equality checks on the same field.

Refer to the Query and Projection Operators document for the complete list of query operators.

Specify AND Conditions

A compound query can specify conditions for more than one field in the collection’s documents. Implicitly, a logical AND conjunction connects the clauses of a compound query so that the query selects the documents in the collection that match all the conditions.

In the following example, the query document specifies an equality match on the field type and a less than ($lt) comparison match on the field price:

db.inventory.find( { type: 'food', price: { $lt: 9.95 } } )

This query selects all documents where the type field has the value 'food' and the value of the price field is less than 9.95. See comparison operators for other comparison operators.

Specify OR Conditions

Using the $or operator, you can specify a compound query that joins each clause with a logical OR conjunction so that the query selects the documents in the collection that match at least one condition.

In the following example, the query document selects all documents in the collection where the field qty has a value greater than ($gt) 100 or the value of the price field is less than ($lt) 9.95:

db.inventory.find(
   {
     $or: [ { qty: { $gt: 100 } }, { price: { $lt: 9.95 } } ]
   }
)

Specify AND as well as OR Conditions

With additional clauses, you can specify precise conditions for matching documents.

In the following example, the compound query document selects all documents in the collection where the value of the type field is 'food' and either the qty has a value greater than ($gt) 100 or the value of the price field is less than ($lt) 9.95:

db.inventory.find(
   {
     type: 'food',
     $or: [ { qty: { $gt: 100 } }, { price: { $lt: 9.95 } } ]
   }
)

Embedded Documents

When the field holds an embedded document, a query can either specify an exact match on the embedded document or specify a match by individual fields in the embedded document using the dot notation.

Exact Match on the Embedded Document

To specify an equality match on the whole embedded document, use the query document { <field>: <value> } where <value> is the document to match. Equality matches on an embedded document require an exact match of the specified <value>, including the field order.

In the following example, the query matches all documents where the value of the field producer is an embedded document that contains only the field company with the value 'ABC123' and the field address with the value '123 Street', in the exact order:

db.inventory.find(
    {
      producer:
        {
          company: 'ABC123',
          address: '123 Street'
        }
    }
)

Equality Match on Fields within an Embedded Document

Use the dot notation to match by specific fields in an embedded document. Equality matches for specific fields in an embedded document will select documents in the collection where the embedded document contains the specified fields with the specified values. The embedded document can contain additional fields.

In the following example, the query uses the dot notation to match all documents where the value of the field producer is an embedded document that contains a field company with the value 'ABC123' and may contain other fields:

db.inventory.find( { 'producer.company': 'ABC123' } )

Arrays

When the field holds an array, you can query for an exact array match or for specific values in the array. If the array holds embedded documents, you can query for specific fields in the embedded documents using dot notation.

If you specify multiple conditions using the $elemMatch operator, the array must contain at least one element that satisfies all the conditions. See Single Element Satisfies the Criteria.

If you specify multiple conditions without using the $elemMatch operator, then some combination of the array elements, not necessarily a single element, must satisfy all the conditions; i.e. different elements in the array can satisfy different parts of the conditions. See Combination of Elements Satisfies the Criteria.

Consider an inventory collection that contains the following documents:

{ _id: 5, type: "food", item: "aaa", ratings: [ 5, 8, 9 ] }
{ _id: 6, type: "food", item: "bbb", ratings: [ 5, 9 ] }
{ _id: 7, type: "food", item: "ccc", ratings: [ 9, 5, 8 ] }

Exact Match on an Array

To specify equality match on an array, use the query document { <field>: <value> } where <value> is the array to match. Equality matches on the array require that the array field match exactly the specified <value>, including the element order.

The following example queries for all documents where the field ratings is an array that holds exactly three elements, 5, 8, and 9, in this order:

db.inventory.find( { ratings: [ 5, 8, 9 ] } )

The operation returns the following document:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }

Match an Array Element

Equality matches can specify a single element in the array to match. These specifications match if the array contains at least one element with the specified value.

The following example queries for all documents where ratings is an array that contains 5 as one of its elements:

db.inventory.find( { ratings: 5 } )

The operation returns the following documents:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }
{ "_id" : 6, "type" : "food", "item" : "bbb", "ratings" : [ 5, 9 ] }
{ "_id" : 7, "type" : "food", "item" : "ccc", "ratings" : [ 9, 5, 8 ] }

Match a Specific Element of an Array

Equality matches can specify equality matches for an element at a particular index or position of the array using the dot notation.

In the following example, the query uses the dot notation to match all documents where the ratings array contains 5 as the first element:

db.inventory.find( { 'ratings.0': 5 } )

The operation returns the following documents:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }
{ "_id" : 6, "type" : "food", "item" : "bbb", "ratings" : [ 5, 9 ] }

Specify Multiple Criteria for Array Elements

Single Element Satisfies the Criteria

Use $elemMatch operator to specify multiple criteria on the elements of an array such that at least one array element satisfies all the specified criteria.

The following example queries for documents where the ratings array contains at least one element that is greater than ($gt) 5 and less than ($lt) 9:

db.inventory.find( { ratings: { $elemMatch: { $gt: 5, $lt: 9 } } } )

The operation returns the following documents, whose ratings array contains the element 8 which meets the criteria:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }
{ "_id" : 7, "type" : "food", "item" : "ccc", "ratings" : [ 9, 5, 8 ] }

Combination of Elements Satisfies the Criteria

The following example queries for documents where the ratings array contains elements that in some combination satisfy the query conditions; e.g., one element can satisfy the greater than 5 condition and another element can satisfy the less than 9 condition, or a single element can satisfy both:

db.inventory.find( { ratings: { $gt: 5, $lt: 9 } } )

The operation returns the following documents:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }
{ "_id" : 6, "type" : "food", "item" : "bbb", "ratings" : [ 5, 9 ] }
{ "_id" : 7, "type" : "food", "item" : "ccc", "ratings" : [ 9, 5, 8 ] }

The document with the "ratings" : [ 5, 9 ] matches the query since the element 9 is greater than 5 (the first condition) and the element 5 is less than 9 (the second condition).

Array of Embedded Documents

Consider that the inventory collection includes the following documents:

{
  _id: 100,
  type: "food",
  item: "xyz",
  qty: 25,
  price: 2.5,
  ratings: [ 5, 8, 9 ],
  memos: [ { memo: "on time", by: "shipping" }, { memo: "approved", by: "billing" } ]
}

{
  _id: 101,
  type: "fruit",
  item: "jkl",
  qty: 10,
  price: 4.25,
  ratings: [ 5, 9 ],
  memos: [ { memo: "on time", by: "payment" }, { memo: "delayed", by: "shipping" } ]
}

Match a Field in the Embedded Document Using the Array Index

If you know the array index of the embedded document, you can specify the document using the embedded document’s position using the dot notation.

The following example selects all documents where the memos contains an array whose first element (i.e. index is 0) is a document that contains the field by whose value is 'shipping':

db.inventory.find( { 'memos.0.by': 'shipping' } )

The operation returns the following document:

{
   _id: 100,
   type: "food",
   item: "xyz",
   qty: 25,
   price: 2.5,
   ratings: [ 5, 8, 9 ],
   memos: [ { memo: "on time", by: "shipping" }, { memo: "approved", by: "billing" } ]
}

Match a Field Without Specifying Array Index

If you do not know the index position of the document in the array, concatenate the name of the field that contains the array, with a dot (.) and the name of the field in the embedded document.

The following example selects all documents where the memos field contains an array that contains at least one embedded document that contains the field by with the value 'shipping':

db.inventory.find( { 'memos.by': 'shipping' } )

The operation returns the following documents:

{
  _id: 100,
  type: "food",
  item: "xyz",
  qty: 25,
  price: 2.5,
  ratings: [ 5, 8, 9 ],
  memos: [ { memo: "on time", by: "shipping" }, { memo: "approved", by: "billing" } ]
}
{
  _id: 101,
  type: "fruit",
  item: "jkl",
  qty: 10,
  price: 4.25,
  ratings: [ 5, 9 ],
  memos: [ { memo: "on time", by: "payment" }, { memo: "delayed", by: "shipping" } ]
}

Specify Multiple Criteria for Array of Documents

Single Element Satisfies the Criteria

Use $elemMatch operator to specify multiple criteria on an array of embedded documents such that at least one embedded document satisfies all the specified criteria.

The following example queries for documents where the memos array has at least one embedded document that contains both the field memo equal to 'on time' and the field by equal to 'shipping':

db.inventory.find(
   {
     memos:
       {
          $elemMatch:
            {
               memo: 'on time',
               by: 'shipping'
            }
       }
    }
)

The operation returns the following document:

{
   _id: 100,
   type: "food",
   item: "xyz",
   qty: 25,
   price: 2.5,
   ratings: [ 5, 8, 9 ],
   memos: [ { memo: "on time", by: "shipping" }, { memo: "approved", by: "billing" } ]
}

Combination of Elements Satisfies the Criteria

The following example queries for documents where the memos array contains elements that in some combination satisfy the query conditions; e.g. one element satisfies the field memo equal to 'on time' condition and another element satisfies the field by equal to 'shipping' condition, or a single element can satisfy both criteria:

db.inventory.find(
  {
    'memos.memo': 'on time',
    'memos.by': 'shipping'
  }
)

The query returns the following documents:

{
  _id: 100,
  type: "food",
  item: "xyz",
  qty: 25,
  price: 2.5,
  ratings: [ 5, 8, 9 ],
  memos: [ { memo: "on time", by: "shipping" }, { memo: "approved", by: "billing" } ]
}
{
  _id: 101,
  type: "fruit",
  item: "jkl",
  qty: 10,
  price: 4.25,
  ratings: [ 5, 9 ],
  memos: [ { memo: "on time", by: "payment" }, { memo: "delayed", by: "shipping" } ]

}

Modify Documents

MongoDB provides the update() method to update the documents of a collection. The method accepts as its parameters:

an update conditions document to match the documents to update,

an update operations document to specify the modification to perform, and

an options document.

To specify the update condition, use the same structure and syntax as the query conditions.

By default, update() updates a single document. To update multiple documents, use the multi option.

Update Specific Fields in a Document

To change a field value, MongoDB provides update operators [http://docs.mongodb.org/manual/reference/operator/update], such as $set to modify values.

Some update operators, such as $set, will create the field if the field does not exist. See the individual update operator [http://docs.mongodb.org/manual/reference/operator/update] reference.

1

Use update operators to change field values.

For the document with item equal to "MNO2", use the $set operator to update the category field and the details field to the specified values and the $currentDate operator to update the field lastModified with the current date.

db.inventory.update(
    { item: "MNO2" },
    {
      $set: {
        category: "apparel",
        details: { model: "14Q3", manufacturer: "XYZ Company" }
      },
      $currentDate: { lastModified: true }
    }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

The nMatched field specifies the number of existing documents matched for the update, and nModified specifies the number of existing documents modified.

Step 1: Use update operators to change field values.

For the document with item equal to "MNO2", use the $set operator to update the category field and the details field to the specified values and the $currentDate operator to update the field lastModified with the current date.

db.inventory.update(
    { item: "MNO2" },
    {
      $set: {
        category: "apparel",
        details: { model: "14Q3", manufacturer: "XYZ Company" }
      },
      $currentDate: { lastModified: true }
    }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

The nMatched field specifies the number of existing documents matched for the update, and nModified specifies the number of existing documents modified.

2

Update an embedded field.

To update a field within an embedded document, use the dot notation. When using the dot notation, enclose the whole dotted field name in quotes.

The following updates the model field within the embedded details document.

db.inventory.update(
  { item: "ABC1" },
  { $set: { "details.model": "14Q2" } }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

Step 2: Update an embedded field.

To update a field within an embedded document, use the dot notation. When using the dot notation, enclose the whole dotted field name in quotes.

The following updates the model field within the embedded details document.

db.inventory.update(
  { item: "ABC1" },
  { $set: { "details.model": "14Q2" } }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

3

Update multiple documents.

By default, the update() method updates a single document. To update multiple documents, use the multi option in the update() method.

Update the category field to "apparel" and update the lastModified field to the current date for all documents that have category field equal to "clothing".

db.inventory.update(
   { category: "clothing" },
   {
     $set: { category: "apparel" },
     $currentDate: { lastModified: true }
   },
   { multi: true }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 3, "nUpserted" : 0, "nModified" : 3 })

Step 3: Update multiple documents.

By default, the update() method updates a single document. To update multiple documents, use the multi option in the update() method.

Update the category field to "apparel" and update the lastModified field to the current date for all documents that have category field equal to "clothing".

db.inventory.update(
   { category: "clothing" },
   {
     $set: { category: "apparel" },
     $currentDate: { lastModified: true }
   },
   { multi: true }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 3, "nUpserted" : 0, "nModified" : 3 })

Replace the Document

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to update().

The replacement document can have different fields from the original document. In the replacement document, you can omit the _id field since the _id field is immutable. If you do include the _id field, it must be the same value as the existing value.

1

Replace a document.

The following operation replaces the document with item equal to "BE10". The newly replaced document will only contain the the _id field and the fields in the replacement document.

db.inventory.update(
   { item: "BE10" },
   {
     item: "BE05",
     stock: [ { size: "S", qty: 20 }, { size: "M", qty: 5 } ],
     category: "apparel"
   }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

Step 1: Replace a document.

The following operation replaces the document with item equal to "BE10". The newly replaced document will only contain the the _id field and the fields in the replacement document.

db.inventory.update(
   { item: "BE10" },
   {
     item: "BE05",
     stock: [ { size: "S", qty: 20 }, { size: "M", qty: 5 } ],
     category: "apparel"
   }
)

The update operation returns a WriteResult object which contains the status of the operation. A successful update of the document returns the following object:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

upsert Option

By default, if no document matches the update query, the update() method does nothing.

However, by specifying upsert: true, the update() method either updates matching document or documents, or inserts a new document using the update specification if no matching document exists.

1

Specify upsert: true for the update replacement operation.

When you specify upsert: true for an update operation to replace a document and no matching documents are found, MongoDB creates a new document using the equality conditions in the update conditions document, and replaces this document, except for the _id field if specified, with the update document.

The following operation either updates a matching document by replacing it with a new document or adds a new document if no matching document exists.

db.inventory.update(
   { item: "TBD1" },
   {
     item: "TBD1",
     details: { "model" : "14Q4", "manufacturer" : "ABC Company" },
     stock: [ { "size" : "S", "qty" : 25 } ],
     category: "houseware"
   },
   { upsert: true }
)

The update operation returns a WriteResult object which contains the status of the operation, including whether the db.collection.update() method modified an existing document or added a new document.

WriteResult({
    "nMatched" : 0,
    "nUpserted" : 1,
    "nModified" : 0,
    "_id" : ObjectId("53dbd684babeaec6342ed6c7")
})

The nMatched field shows that the operation matched 0 documents.

The nUpserted of 1 shows that the update added a document.

The nModified of 0 specifies that no existing documents were updated.

The _id field shows the generated _id field for the added document.

Step 1: Specify upsert: true for the update replacement operation.

When you specify upsert: true for an update operation to replace a document and no matching documents are found, MongoDB creates a new document using the equality conditions in the update conditions document, and replaces this document, except for the _id field if specified, with the update document.

The following operation either updates a matching document by replacing it with a new document or adds a new document if no matching document exists.

db.inventory.update(
   { item: "TBD1" },
   {
     item: "TBD1",
     details: { "model" : "14Q4", "manufacturer" : "ABC Company" },
     stock: [ { "size" : "S", "qty" : 25 } ],
     category: "houseware"
   },
   { upsert: true }
)

The update operation returns a WriteResult object which contains the status of the operation, including whether the db.collection.update() method modified an existing document or added a new document.

WriteResult({
    "nMatched" : 0,
    "nUpserted" : 1,
    "nModified" : 0,
    "_id" : ObjectId("53dbd684babeaec6342ed6c7")
})

The nMatched field shows that the operation matched 0 documents.

The nUpserted of 1 shows that the update added a document.

The nModified of 0 specifies that no existing documents were updated.

The _id field shows the generated _id field for the added document.

2

Specify an upsert: true for the update specific fields operation.

When you specify an upsert: true for an update operation that modifies specific fields and no matching documents are found, MongoDB creates a new document using the equality conditions in the update conditions document, and applies the modification as specified in the update document.

The following update operation either updates specific fields of a matching document or adds a new document if no matching document exists.

db.inventory.update(
   { item: "TBD2" },
   {
     $set: {
        details: { "model" : "14Q3", "manufacturer" : "IJK Co." },
        category: "houseware"
     }
   },
   { upsert: true }
)

The update operation returns a WriteResult object which contains the status of the operation, including whether the db.collection.update() method modified an existing document or added a new document.

WriteResult({
    "nMatched" : 0,
    "nUpserted" : 1,
    "nModified" : 0,
    "_id" : ObjectId("53dbd7c8babeaec6342ed6c8")
})

The nMatched field shows that the operation matched 0 documents.

The nUpserted of 1 shows that the update added a document.

The nModified of 0 specifies that no existing documents were updated.

The _id field shows the generated _id field for the added document.

Step 2: Specify an upsert: true for the update specific fields operation.

When you specify an upsert: true for an update operation that modifies specific fields and no matching documents are found, MongoDB creates a new document using the equality conditions in the update conditions document, and applies the modification as specified in the update document.

The following update operation either updates specific fields of a matching document or adds a new document if no matching document exists.

db.inventory.update(
   { item: "TBD2" },
   {
     $set: {
        details: { "model" : "14Q3", "manufacturer" : "IJK Co." },
        category: "houseware"
     }
   },
   { upsert: true }
)

The update operation returns a WriteResult object which contains the status of the operation, including whether the db.collection.update() method modified an existing document or added a new document.

WriteResult({
    "nMatched" : 0,
    "nUpserted" : 1,
    "nModified" : 0,
    "_id" : ObjectId("53dbd7c8babeaec6342ed6c8")
})

The nMatched field shows that the operation matched 0 documents.

The nUpserted of 1 shows that the update added a document.

The nModified of 0 specifies that no existing documents were updated.

The _id field shows the generated _id field for the added document.

Additional Examples and Methods

For more examples, see Update examples in the db.collection.update() reference page.

The db.collection.findAndModify() and the db.collection.save() method can also modify existing documents or insert a new one. See the individual reference pages for the methods for more information and examples.

Remove Documents

In MongoDB, the db.collection.remove() method removes documents from a collection. You can remove all documents from a collection, remove all documents that match a condition, or limit the operation to remove just a single document.

This tutorial provides examples of remove operations using the db.collection.remove() method in the mongo shell.

Remove All Documents

To remove all documents from a collection, pass an empty query document {} to the remove() method. The remove() method does not remove the indexes.

The following example removes all documents from the inventory collection:

db.inventory.remove({})

To remove all documents from a collection, it may be more efficient to use the drop() method to drop the entire collection, including the indexes, and then recreate the collection and rebuild the indexes.

Remove Documents that Match a Condition

To remove the documents that match a deletion criteria, call the remove() method with the <query> parameter.

The following example removes all documents from the inventory collection where the type field equals food:

db.inventory.remove( { type : "food" } )

For large deletion operations, it may be more efficient to copy the documents that you want to keep to a new collection and then use drop() on the original collection.

Remove a Single Document that Matches a Condition

To remove a single document, call the remove() method with the justOne parameter set to true or 1.

The following example removes one document from the inventory collection where the type field equals food:

db.inventory.remove( { type : "food" }, 1 )

To delete a single document sorted by some specified order, use the findAndModify() method.

Limit Fields to Return from a Query

The projection document limits the fields to return for all matching documents. The projection document can specify the inclusion of fields or the exclusion of fields.

The specifications have the following forms:

Syntax | Description
<field>: <1 or true> | Specify the inclusion of a field.
<field>: <0 or false> | Specify the suppression of the field.

Important

The _id field is, by default, included in the result set. To suppress the _id field from the result set, specify _id: 0 in the projection document.

You cannot combine inclusion and exclusion semantics in a single projection with the exception of the _id field.

This tutorial offers various query examples that limit the fields to return for all matching documents. The examples in this tutorial use a collection inventory and use the db.collection.find() method in the mongo shell. The db.collection.find() method returns a cursor to the retrieved documents. For examples on query selection criteria, see Query Documents.

Return All Fields in Matching Documents

If you specify no projection, the find() method returns all fields of all documents that match the query.

db.inventory.find( { type: 'food' } )

This operation will return all documents in the inventory collection where the value of the type field is 'food'. The returned documents contain all its fields.

Return the Specified Fields and the _id Field Only

A projection can explicitly include several fields. In the following operation, find() method returns all documents that match the query. In the result set, only the item and qty fields and, by default, the _id field return in the matching documents.

db.inventory.find( { type: 'food' }, { item: 1, qty: 1 } )

Return Specified Fields Only

You can remove the _id field from the results by specifying its exclusion in the projection, as in the following example:

db.inventory.find( { type: 'food' }, { item: 1, qty: 1, _id:0 } )

This operation returns all documents that match the query. In the result set, only the item and qty fields return in the matching documents.

Return All But the Excluded Field

To exclude a single field or group of fields you can use a projection in the following form:

db.inventory.find( { type: 'food' }, { type:0 } )

This operation returns all documents where the value of the type field is food. In the result set, the type field does not return in the matching documents.

With the exception of the _id field you cannot combine inclusion and exclusion statements in projection documents.

Projection for Array Fields

For fields that contain arrays, MongoDB provides the following projection operators: $elemMatch, $slice, and $.

For example, the inventory collection contains the following document:

{ "_id" : 5, "type" : "food", "item" : "aaa", "ratings" : [ 5, 8, 9 ] }

Then the following operation uses the $slice projection operator to return just the first two elements in the ratings array.

db.inventory.find( { _id: 5 }, { ratings: { $slice: 2 } } )

$elemMatch, $slice, and $ are the only way to project portions of an array. For instance, you cannot project a portion of an array using the array index; e.g. { "ratings.0": 1 } projection will not project the array with the first element.

Limit Number of Elements in an Array after an Update

New in version 2.4.

Synopsis

Consider an application where users may submit many scores (e.g. for a test), but the application only needs to track the top three test scores.

This pattern uses the $push operator with the $each, $sort, and $slice modifiers to sort and maintain an array of fixed size.

Pattern

Consider the following document in the collection students:

{
  _id: 1,
  scores: [
    { attempt: 1, score: 10 },
    { attempt: 2 , score:8 }
  ]
}

The following update uses the $push operator with:

the $each modifier to append to the array 2 new elements,

the $sort modifier to order the elements by ascending (1) score, and

the $slice modifier to keep the last 3 elements of the ordered array.

db.students.update(
   { _id: 1 },
   {
     $push: {
        scores: {
           $each: [ { attempt: 3, score: 7 }, { attempt: 4, score: 4 } ],
           $sort: { score: 1 },
           $slice: -3
        }
     }
   }
)

Note

When using the $sort modifier on the array element, access the field in the embedded document element directly instead of using the dot notation on the array field.

After the operation, the document contains only the top 3 scores in the scores array:

{
   "_id" : 1,
   "scores" : [
     { "attempt" : 3, "score" : 7 },
     { "attempt" : 2, "score" : 8 },
     { "attempt" : 1, "score" : 10 }
   ]
}

See also

$push operator,

$each modifier,

$sort modifier, and

$slice modifier.

Iterate a Cursor in the mongo Shell

The db.collection.find() method returns a cursor. To access the documents, you need to iterate the cursor. However, in the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, then the cursor is automatically iterated up to 20 times to print up to the first 20 documents in the results. The following describes ways to manually iterate the cursor to access the documents or to use the iterator index.

Manually Iterate the Cursor

In the mongo shell, when you assign the cursor returned from the find() method to a variable using the var keyword, the cursor does not automatically iterate.

You can call the cursor variable in the shell to iterate up to 20 times [1] and print the matching documents, as in the following example:

var myCursor = db.inventory.find( { type: 'food' } );

myCursor

You can also use the cursor method next() to access the documents, as in the following example:

var myCursor = db.inventory.find( { type: 'food' } );

while (myCursor.hasNext()) {
   print(tojson(myCursor.next()));
}

As an alternative print operation, consider the printjson() helper method to replace print(tojson()):

var myCursor = db.inventory.find( { type: 'food' } );

while (myCursor.hasNext()) {
   printjson(myCursor.next());
}

You can use the cursor method forEach() to iterate the cursor and access the documents, as in the following example:

var myCursor =  db.inventory.find( { type: 'food' } );

myCursor.forEach(printjson);

See JavaScript cursor methods and your driver documentation for more information on cursor methods.

[1]
You can use the DBQuery.shellBatchSize to change the number of iteration from the default value 20. See Executing Queries for more information.

Iterator Index

In the mongo shell, you can use the toArray() method to iterate the cursor and return the documents in an array, as in the following:

var myCursor = db.inventory.find( { type: 'food' } );
var documentArray = myCursor.toArray();
var myDocument = documentArray[3];

The toArray() method loads into RAM all documents returned by the cursor; the toArray() method exhausts the cursor.

Additionally, some drivers provide access to the documents by using an index on the cursor (i.e. cursor[index]). This is a shortcut for first calling the toArray() method and then using an index on the resulting array.

Consider the following example:

var myCursor = db.inventory.find( { type: 'food' } );
var myDocument = myCursor[3];

The myCursor[3] is equivalent to the following example:

myCursor.toArray() [3];

Analyze Query Performance

The explain() cursor method provides statistics about the performance of a query. This data output can be useful in measuring if and how a query uses an index. [1]

Evaluate the Performance of a Query

Consider a collection inventory with the following documents:

{ "_id" : 1, "item" : "f1", type: "food", quantity: 500 }
{ "_id" : 2, "item" : "f2", type: "food", quantity: 100 }
{ "_id" : 3, "item" : "p1", type: "paper", quantity: 200 }
{ "_id" : 4, "item" : "p2", type: "paper", quantity: 150 }
{ "_id" : 5, "item" : "f3", type: "food", quantity: 300 }
{ "_id" : 6, "item" : "t1", type: "toys", quantity: 500 }
{ "_id" : 7, "item" : "a1", type: "apparel", quantity: 250 }
{ "_id" : 8, "item" : "a2", type: "apparel", quantity: 400 }
{ "_id" : 9, "item" : "t2", type: "toys", quantity: 50 }
{ "_id" : 10, "item" : "f4", type: "food", quantity: 75 }

Query with No Index

The following query retrieves documents where the quantity field has a value between 100 and 200, inclusive:

db.inventory.find( { quantity: { $gte: 100, $lte: 200 } } )

The query returns the following documents:

{ "_id" : 2, "item" : "f2", "type" : "food", "quantity" : 100 }
{ "_id" : 3, "item" : "p1", "type" : "paper", "quantity" : 200 }
{ "_id" : 4, "item" : "p2", "type" : "paper", "quantity" : 150 }

To view the query plan selected, use the explain() method:

db.inventory.find( { quantity: { $gte: 100, $lte: 200 } } ).explain()

The explain() method returns this output:

{
   "cursor" : "BasicCursor",
   "isMultiKey" : false,
   "n" : 3,
   "nscannedObjects" : 10,
   "nscanned" : 10,
   "nscannedObjectsAllPlans" : 10,
   "nscannedAllPlans" : 10,
   "scanAndOrder" : false,
   "indexOnly" : false,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BasicCursor to indicate a collection scan.

n displays 3 to indicate that the query matches and returns three documents.

nscanned and nscannedObjects display 10 to indicate that MongoDB had to scan ten documents (i.e. all documents in the collection) to find the three matching documents.

The difference between the number of matching documents and the number documents scanned may suggest that, to improve efficiency, the query might benefit from the use of an index.

Query with Index

To support the query on the quantity field, add an index on the quantity field:

db.inventory.ensureIndex( { quantity: 1 } )

To view the query plan statistics, use the explain() method:

db.inventory.find( { quantity: { $gte: 100, $lte: 200 } } ).explain()

The explain() method returns this output:

{
   "cursor" : "BtreeCursor quantity_1",
   "isMultiKey" : false,
   "n" : 3,
   "nscannedObjects" : 3,
   "nscanned" : 3,
   "nscannedObjectsAllPlans" : 3,
   "nscannedAllPlans" : 3,
   "scanAndOrder" : false,
   "indexOnly" : false,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "indexBounds" : { "quantity" : [ [ 100, 200 ] ] },
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BtreeCursor quantity_1 to indicate index use and the name of the index.

n displays 3 to indicate that the query matches and returns three documents.

nscanned displays 3 to indicate that MongoDB scanned three index entries.

nscannedObjects displays 3 to indicate that MongoDB scanned three documents.

When run with an index, the query scanned 3 index entries and 3 documents to return 3 matching documents. Without the index, to return the 3 matching documents, the query had to scan the whole collection, scanning 10 documents.

Compare Performance of Indexes

To manually compare the performance of a query using more than one index, you can use the hint() method in conjunction with the explain() method.

Consider the following query:

db.inventory.find( { quantity: { $gte: 100, $lte: 300 }, type: "food" } )

The query returns the following documents:

{ "_id" : 2, "item" : "f2", "type" : "food", "quantity" : 100 }
{ "_id" : 5, "item" : "f3", "type" : "food", "quantity" : 300 }

To support the query, add a compound index. With compound indexes, the order of the fields matter.

For example, add the following two compound indexes. The first index orders by quantity field first, and then the type field. The second index orders by type first, and then the quantity field.

db.inventory.ensureIndex( { quantity: 1, type: 1 } )
db.inventory.ensureIndex( { type: 1, quantity: 1 } )

Evaluate the effect of the first index on the query:

db.inventory.find( { quantity: { $gte: 100, $lte: 300 }, type: "food" } ).hint({ quantity: 1, type: 1 }).explain()

The explain() method returns the following output:

{
   "cursor" : "BtreeCursor quantity_1_type_1",
   "isMultiKey" : false,
   "n" : 2,
   "nscannedObjects" : 2,
   "nscanned" : 5,
   ...
}

MongoDB scanned 5 index keys (nscanned) to return 2 matching documents (n).

Evaluate the effect of the second index on the query:

db.inventory.find( { quantity: { $gte: 100, $lte: 300 }, type: "food" } ).hint({ type: 1, quantity: 1 }).explain()

The explain() method returns the following output:

{
   "cursor" : "BtreeCursor type_1_quantity_1",
   "isMultiKey" : false,
   "n" : 2,
   "nscannedObjects" : 2,
   "nscanned" : 2,
   ...
}

MongoDB scanned 2 index keys (nscanned) to return 2 matching documents (n).

For this example query, the compound index { type: 1, quantity: 1 } is more efficient than the compound index { quantity: 1, type: 1 }.

See also

Query Optimization, Query Plans Optimize Query Performance, Indexing Strategies

[1]
Because explain() attempts multiple query plans, the explain() method does not reflect an accurate timing of query performance. For more information on its behavior, see explain().

Perform Two Phase Commits

Synopsis

This document provides a pattern for doing multi-document updates or “multi-document transactions” using a two-phase commit approach for writing data to multiple documents. Additionally, you can extend this process to provide a rollback-like functionality.

Background

Operations on a single document are always atomic with MongoDB databases; however, operations that involve multiple documents, which are often referred to as “multi-document transactions”, are not atomic. Since documents can be fairly complex and contain multiple “nested” documents, single-document atomicity provides the necessary support for many practical use cases.

Despite the power of single-document atomic operations, there are cases that require multi-document transactions. When executing a transaction composed of sequential operations, certain issues arise, such as:

Atomicity: if one operation fails, the previous operation within the transaction must “rollback” to the previous state (i.e. the “nothing,” in “all or nothing”).

Consistency: if a major failure (i.e. network, hardware) interrupts the transaction, the database must be able to recover a consistent state.

For situations that require multi-document transactions, you can implement two-phase commit in your application to provide support for these kinds of multi-document updates. Using two-phase commit ensures that data is consistent and, in case of an error, the state that preceded the transaction is recoverable. During the procedure, however, documents can represent pending data and states.

Note

Because only single-document operations are atomic with MongoDB, two-phase commits can only offer transaction-like semantics. It is possible for applications to return intermediate data at intermediate points during the two-phase commit or rollback.

Pattern

Overview

Consider a scenario where you want to transfer funds from account A to account B. In a relational database system, you can subtract the funds from A and add the funds to B in a single multi-statement transaction. In MongoDB, you can emulate a two-phase commit to achieve a comparable result.

The examples in this tutorial use the following two collections:

A collection named accounts to store account information.

A collection named transactions to store information on the fund transfer transactions.

Initialize Source and Destination Accounts

Insert into the accounts collection a document for account A and a document for account B.

db.accounts.insert(
   [
     { _id: "A", balance: 1000, pendingTransactions: [] },
     { _id: "B", balance: 1000, pendingTransactions: [] }
   ]
)

The operation returns a BulkWriteResult() object with the status of the operation. Upon successful insert, the BulkWriteResult() has nInserted set to 2 .

Initialize Transfer Record

For each fund transfer to perform, insert into the transactions collection a document with the transfer information. The document contains the following fields:

source and destination fields, which refer to the _id fields from the accounts collection,

value field, which specifies the amount of transfer affecting the balance of the source and destination accounts,

state field, which reflects the current state of the transfer. The state field can have the value of initial, pending, applied, done, canceling, and canceled.

lastModified field, which reflects last modification date.

To initialize the transfer of 100 from account A to account B, insert into the transactions collection a document with the transfer information, the transaction state of "initial", and the lastModified field set to the current date:

db.transactions.insert(
    { _id: 1, source: "A", destination: "B", value: 100, state: "initial", lastModified: new Date() }
)

The operation returns a WriteResult() object with the status of the operation. Upon successful insert, the WriteResult() object has nInserted set to 1.

Transfer Funds Between Accounts Using Two-Phase Commit

1

Retrieve the transaction to start.

From the transactions collection, find a transaction in the initial state. Currently the transactions collection has only one document, namely the one added in the Initialize Transfer Record step. If the collection contains additional documents, the query will return any transaction with an initial state unless you specify additional query conditions.

var t = db.transactions.findOne( { state: "initial" } )

Type the variable t in the mongo shell to print the contents of the variable. The operation should print a document similar to the following except the lastModified field should reflect date of your insert operation:

{ "_id" : 1, "source" : "A", "destination" : "B", "value" : 100, "state" : "initial", "lastModified" : ISODate("2014-07-11T20:39:26.345Z") }

Step 1: Retrieve the transaction to start.

From the transactions collection, find a transaction in the initial state. Currently the transactions collection has only one document, namely the one added in the Initialize Transfer Record step. If the collection contains additional documents, the query will return any transaction with an initial state unless you specify additional query conditions.

var t = db.transactions.findOne( { state: "initial" } )

Type the variable t in the mongo shell to print the contents of the variable. The operation should print a document similar to the following except the lastModified field should reflect date of your insert operation:

{ "_id" : 1, "source" : "A", "destination" : "B", "value" : 100, "state" : "initial", "lastModified" : ISODate("2014-07-11T20:39:26.345Z") }

2

Update transaction state to pending.

Set the transaction state from initial to pending and use the $currentDate operator to set the lastModified field to the current date.

db.transactions.update(
    { _id: t._id, state: "initial" },
    {
      $set: { state: "pending" },
      $currentDate: { lastModified: true }
    }
)

The operation returns a WriteResult() object with the status of the operation. Upon successful update, the nMatched and nModified displays 1.

In the update statement, the state: "initial" condition ensures that no other process has already updated this record. If nMatched and nModified is 0, go back to the first step to get a different transaction and restart the procedure.

Step 2: Update transaction state to pending.

Set the transaction state from initial to pending and use the $currentDate operator to set the lastModified field to the current date.

db.transactions.update(
    { _id: t._id, state: "initial" },
    {
      $set: { state: "pending" },
      $currentDate: { lastModified: true }
    }
)

The operation returns a WriteResult() object with the status of the operation. Upon successful update, the nMatched and nModified displays 1.

In the update statement, the state: "initial" condition ensures that no other process has already updated this record. If nMatched and nModified is 0, go back to the first step to get a different transaction and restart the procedure.

3

Apply the transaction to both accounts.

Apply the transaction t to both accounts using the update() method if the transaction has not been applied to the accounts. In the update condition, include the condition pendingTransactions: { $ne: t._id } in order to avoid re-applying the transaction if the step is run more than once.

To apply the transaction to the account, update both the balance field and the pendingTransactions field.

Update the source account, subtracting from its balance the transaction value and adding to its pendingTransactions array the transaction _id.

db.accounts.update(
   { _id: t.source, pendingTransactions: { $ne: t._id } },
   { $inc: { balance: -t.value }, $push: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Update the destination account, adding to its balance the transaction value and adding to its pendingTransactions array the transaction _id .

db.accounts.update(
   { _id: t.destination, pendingTransactions: { $ne: t._id } },
   { $inc: { balance: t.value }, $push: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 3: Apply the transaction to both accounts.

Apply the transaction t to both accounts using the update() method if the transaction has not been applied to the accounts. In the update condition, include the condition pendingTransactions: { $ne: t._id } in order to avoid re-applying the transaction if the step is run more than once.

To apply the transaction to the account, update both the balance field and the pendingTransactions field.

Update the source account, subtracting from its balance the transaction value and adding to its pendingTransactions array the transaction _id.

db.accounts.update(
   { _id: t.source, pendingTransactions: { $ne: t._id } },
   { $inc: { balance: -t.value }, $push: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Update the destination account, adding to its balance the transaction value and adding to its pendingTransactions array the transaction _id .

db.accounts.update(
   { _id: t.destination, pendingTransactions: { $ne: t._id } },
   { $inc: { balance: t.value }, $push: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

4

Update transaction state to applied.

Use the following update() operation to set the transaction’s state to applied and update the lastModified field:

db.transactions.update(
   { _id: t._id, state: "pending" },
   {
     $set: { state: "applied" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 4: Update transaction state to applied.

Use the following update() operation to set the transaction’s state to applied and update the lastModified field:

db.transactions.update(
   { _id: t._id, state: "pending" },
   {
     $set: { state: "applied" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

5

Update both accounts’ list of pending transactions.

Remove the applied transaction _id from the pendingTransactions array for both accounts.

Update the source account.

db.accounts.update(
   { _id: t.source, pendingTransactions: t._id },
   { $pull: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Update the destination account.

db.accounts.update(
   { _id: t.destination, pendingTransactions: t._id },
   { $pull: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 5: Update both accounts’ list of pending transactions.

Remove the applied transaction _id from the pendingTransactions array for both accounts.

Update the source account.

db.accounts.update(
   { _id: t.source, pendingTransactions: t._id },
   { $pull: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Update the destination account.

db.accounts.update(
   { _id: t.destination, pendingTransactions: t._id },
   { $pull: { pendingTransactions: t._id } }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

6

Update transaction state to done.

Complete the transaction by setting the state of the transaction to done and updating the lastModified field:

db.transactions.update(
   { _id: t._id, state: "applied" },
   {
     $set: { state: "done" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 6: Update transaction state to done.

Complete the transaction by setting the state of the transaction to done and updating the lastModified field:

db.transactions.update(
   { _id: t._id, state: "applied" },
   {
     $set: { state: "done" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Recovering from Failure Scenarios

The most important part of the transaction procedure is not the prototypical example above, but rather the possibility for recovering from the various failure scenarios when transactions do not complete successfully. This section presents an overview of possible failures and provides steps to recover from these kinds of events.

Recovery Operations

The two-phase commit pattern allows applications running the sequence to resume the transaction and arrive at a consistent state. Run the recovery operations at application startup, and possibly at regular intervals, to catch any unfinished transactions.

The time required to reach a consistent state depends on how long the application needs to recover each transaction.

The following recovery procedures uses the lastModified date as an indicator of whether the pending transaction requires recovery; specifically, if the pending or applied transaction has not been updated in the last 30 minutes, the procedures determine that these transactions require recovery. You can use different conditions to make this determination.

Transactions in Pending State

To recover from failures that occur after step “Update transaction state to pending.” but before “Update transaction state to applied.” step, retrieve from the transactions collection a pending transaction for recovery:

var dateThreshold = new Date();
dateThreshold.setMinutes(dateThreshold.getMinutes() - 30);

var t = db.transactions.findOne( { state: "pending", lastModified: { $lt: dateThreshold } } );

And resume from step “Apply the transaction to both accounts.“

Transactions in Applied State

To recover from failures that occur after step “Update transaction state to applied.” but before “Update transaction state to done.” step, retrieve from the transactions collection an applied transaction for recovery:

var dateThreshold = new Date();
dateThreshold.setMinutes(dateThreshold.getMinutes() - 30);

var t = db.transactions.findOne( { state: "applied", lastModified: { $lt: dateThreshold } } );

And resume from “Update both accounts’ list of pending transactions.“

Rollback Operations

In some cases, you may need to “roll back” or undo a transaction; e.g., if the application needs to “cancel” the transaction or if one of the accounts does not exist or stops existing during the transaction.

Transactions in Applied State

After the “Update transaction state to applied.” step, you should not roll back the transaction. Instead, complete that transaction and create a new transaction to reverse the transaction by switching the values in the source and the destination fields.

Transactions in Pending State

After the “Update transaction state to pending.” step, but before the “Update transaction state to applied.” step, you can rollback the transaction using the following procedure:

1

Update transaction state to canceling.

Update the transaction state from pending to canceling.

db.transactions.update(
   { _id: t._id, state: "pending" },
   {
     $set: { state: "canceling" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 1: Update transaction state to canceling.

Update the transaction state from pending to canceling.

db.transactions.update(
   { _id: t._id, state: "pending" },
   {
     $set: { state: "canceling" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

2

Undo the transaction on both accounts.

To undo the transaction on both accounts, reverse the transaction t if the transaction has been applied. In the update condition, include the condition pendingTransactions: t._id in order to update the account only if the pending transaction has been applied.

Update the destination account, subtracting from its balance the transaction value and removing the transaction _id from the pendingTransactions array.

db.accounts.update(
   { _id: t.destination, pendingTransactions: t._id },
   {
     $inc: { balance: -t.value },
     $pull: { pendingTransactions: t._id }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1. If the pending transaction has not been previously applied to this account, no document will match the update condition and nMatched and nModified will be 0.

Update the source account, adding to its balance the transaction value and removing the transaction _id from the pendingTransactions array.

db.accounts.update(
   { _id: t.source, pendingTransactions: t._id },
   {
     $inc: { balance: t.value},
     $pull: { pendingTransactions: t._id }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1. If the pending transaction has not been previously applied to this account, no document will match the update condition and nMatched and nModified will be 0.

Step 2: Undo the transaction on both accounts.

To undo the transaction on both accounts, reverse the transaction t if the transaction has been applied. In the update condition, include the condition pendingTransactions: t._id in order to update the account only if the pending transaction has been applied.

Update the destination account, subtracting from its balance the transaction value and removing the transaction _id from the pendingTransactions array.

db.accounts.update(
   { _id: t.destination, pendingTransactions: t._id },
   {
     $inc: { balance: -t.value },
     $pull: { pendingTransactions: t._id }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1. If the pending transaction has not been previously applied to this account, no document will match the update condition and nMatched and nModified will be 0.

Update the source account, adding to its balance the transaction value and removing the transaction _id from the pendingTransactions array.

db.accounts.update(
   { _id: t.source, pendingTransactions: t._id },
   {
     $inc: { balance: t.value},
     $pull: { pendingTransactions: t._id }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1. If the pending transaction has not been previously applied to this account, no document will match the update condition and nMatched and nModified will be 0.

3

Update transaction state to canceled.

To finish the rollback, update the transaction state from canceling to cancelled.

db.transactions.update(
   { _id: t._id, state: "canceling" },
   {
     $set: { state: "cancelled" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Step 3: Update transaction state to canceled.

To finish the rollback, update the transaction state from canceling to cancelled.

db.transactions.update(
   { _id: t._id, state: "canceling" },
   {
     $set: { state: "cancelled" },
     $currentDate: { lastModified: true }
   }
)

Upon successful update, the method returns a WriteResult() object with nMatched and nModified set to 1.

Multiple Applications

Transactions exist, in part, so that multiple applications can create and run operations concurrently without causing data inconsistency or conflicts. In our procedure, to update or retrieve the transaction document, the update conditions include a condition on the state field to prevent reapplication of the transaction by multiple applications.

For example, applications App1 and App2 both grab the same transaction, which is in the initial state. App1 applies the whole transaction before App2 starts. When App2 attempts to perform the “Update transaction state to pending.” step, the update condition, which includes the state: "initial" criterion, will not match any document, and the nMatched and nModified will be 0. This should signal to App2 to go back to the first step to restart the procedure with a different transaction.

When multiple applications are running, it is crucial that only one application can handle a given transaction at any point in time. As such, in addition including the expected state of the transaction in the update condition, you can also create a marker in the transaction document itself to identify the application that is handling the transaction. Use findAndModify() method to modify the transaction and get it back in one step:

t = db.transactions.findAndModify(
       {
         query: { state: "initial", application: { $exists: false } },
         update:
           {
             $set: { state: "pending", application: "App1" },
             $currentDate: { lastModified: true }
           },
         new: true
       }
    )

Amend the transaction operations to ensure that only applications that match the identifier in the application field apply the transaction.

If the application App1 fails during transaction execution, you can use the recovery procedures, but applications should ensure that they “own” the transaction before applying the transaction. For example to find and resume the pending job, use a query that resembles the following:

var dateThreshold = new Date();
dateThreshold.setMinutes(dateThreshold.getMinutes() - 30);

db.transactions.find(
   {
     application: "App1",
     state: "pending",
     lastModified: { $lt: dateThreshold }
   }
)

Using Two-Phase Commits in Production Applications

The example transaction above is intentionally simple. For example, it assumes that it is always possible to roll back operations to an account and that account balances can hold negative values.

Production implementations would likely be more complex. Typically, accounts need information about current balance, pending credits, and pending debits.

For all transactions, ensure that you use the appropriate level of write concern for your deployment.

Update Document if Current

Overview

The Update if Current pattern is an approach to concurrency control when multiple applications have access to the data.

Pattern

The pattern queries for the document to update. Then, for each field to modify, the pattern includes the field and its value in the returned document in the query predicate for the update operation. This way, the update only modifies the document fields if the fields have not changed since the query.

Example

Consider the following example in the mongo shell. The example updates the quantity and the reordered fields of a document only if the fields have not changed since the query.

Changed in version 2.6: The db.collection.update() method now returns a WriteResult() object that contains the status of the operation. Previous versions required an extra db.getLastErrorObj() method call.

var myDocument = db.products.findOne( { sku: "abc123" } );

if ( myDocument ) {
   var oldQuantity = myDocument.quantity;
   var oldReordered = myDocument.reordered;

   var results = db.products.update(
      {
        _id: myDocument._id,
        quantity: oldQuantity,
        reordered: oldReordered
      },
      {
        $inc: { quantity: 50 },
        $set: { reordered: true }
      }
   )

   if ( results.hasWriteError() ) {
      print( "unexpected error updating document: " + tojson(results) );
   }
   else if ( results.nMatched === 0 ) {
      print( "No matching document for " +
             "{ _id: "+ myDocument._id.toString() +
             ", quantity: " + oldQuantity +
             ", reordered: " + oldReordered
             + " } "
      );
   }
}

Modifications to the Pattern

Another approach is to add a version field to the documents. Applications increment this field upon each update operation to the documents. You must be able to ensure that all clients that connect to your database include the version field in the query predicate. To associate increasing numbers with documents in a collection, you can use one of the methods described in Create an Auto-Incrementing Sequence Field.

For more approaches, see Concurrency Control.

Create Tailable Cursor

Overview

By default, MongoDB will automatically close a cursor when the client has exhausted all results in the cursor. However, for capped collections you may use a Tailable Cursor that remains open after the client exhausts the results in the initial cursor. Tailable cursors are conceptually equivalent to the tail Unix command with the -f option (i.e. with “follow” mode). After clients insert new additional documents into a capped collection, the tailable cursor will continue to retrieve documents.

Use tailable cursors on capped collections that have high write volumes where indexes aren’t practical. For instance, MongoDB replication uses tailable cursors to tail the primary’s oplog.

Note

If your query is on an indexed field, do not use tailable cursors, but instead, use a regular cursor. Keep track of the last value of the indexed field returned by the query. To retrieve the newly added documents, query the collection again using the last value of the indexed field in the query criteria, as in the following example:

db.<collection>.find( { indexedField: { $gt: <lastvalue> } } )

Consider the following behaviors related to tailable cursors:

Tailable cursors do not use indexes and return documents in natural order.

Because tailable cursors do not use indexes, the initial scan for the query may be expensive; but, after initially exhausting the cursor, subsequent retrievals of the newly added documents are inexpensive.

Tailable cursors may become dead, or invalid, if either:

the query returns no match.

the cursor returns the document at the “end” of the collection and then the application deletes that document.

A dead cursor has an id of 0.

See your driver documentation for the driver-specific method to specify the tailable cursor. For more information on the details of specifying a tailable cursor, see MongoDB wire protocol [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol] documentation.

C++ Example

The tail function uses a tailable cursor to output the results from a query to a capped collection:

The function handles the case of the dead cursor by having the query be inside a loop.

To periodically check for new data, the cursor->more() statement is also inside a loop.

#include "client/dbclient.h"

using namespace mongo;

/*
 * Example of a tailable cursor.
 * The function "tails" the capped collection (ns) and output elements as they are added.
 * The function also handles the possibility of a dead cursor by tracking the field 'insertDate'.
 * New documents are added with increasing values of 'insertDate'.
 */

void tail(DBClientBase& conn, const char *ns) {

    BSONElement lastValue = minKey.firstElement();

    Query query = Query().hint( BSON( "$natural" << 1 ) );

    while ( 1 ) {
        auto_ptr<DBClientCursor> c =
            conn.query(ns, query, 0, 0, 0,
                       QueryOption_CursorTailable | QueryOption_AwaitData );

        while ( 1 ) {
            if ( !c->more() ) {

                if ( c->isDead() ) {
                    break;
                }

                continue;
            }

            BSONObj o = c->next();
            lastValue = o["insertDate"];
            cout << o.toString() << endl;
        }

        query = QUERY( "insertDate" << GT << lastValue ).hint( BSON( "$natural" << 1 ) );
    }
}

The tail function performs the following actions:

Initialize the lastValue variable, which tracks the last accessed value. The function will use the lastValue if the cursor becomes invalid and tail needs to restart the query. Use hint() to ensure that the query uses the $natural order.

In an outer while(1) loop,

Query the capped collection and return a tailable cursor that blocks for several seconds waiting for new documents

auto_ptr<DBClientCursor> c =
     conn.query(ns, query, 0, 0, 0,
                QueryOption_CursorTailable | QueryOption_AwaitData );

Specify the capped collection using ns as an argument to the function.

Set the QueryOption_CursorTailable option to create a tailable cursor.

Set the QueryOption_AwaitData option so that the returned cursor blocks for a few seconds to wait for data.

In an inner while (1) loop, read the documents from the cursor:

If the cursor has no more documents and is not invalid, loop the inner while loop to recheck for more documents.

If the cursor has no more documents and is dead, break the inner while loop.

If the cursor has documents:

output the document,

update the lastValue value,

and loop the inner while (1) loop to recheck for more documents.

If the logic breaks out of the inner while (1) loop and the cursor is invalid:

Use the lastValue value to create a new query condition that matches documents added after the lastValue. Explicitly ensure $natural order with the hint() method:

query = QUERY( "insertDate" << GT << lastValue ).hint( BSON( "$natural" << 1 ) );

Loop through the outer while (1) loop to re-query with the new query condition and repeat.

See also

Detailed blog post on tailable cursor [http://shtylman.com/post/the-tail-of-mongodb]

Create an Auto-Incrementing Sequence Field

Synopsis

MongoDB reserves the _id field in the top level of all documents as a primary key. _id must be unique, and always has an index with a unique constraint. However, except for the unique constraint you can use any value for the _id field in your collections. This tutorial describes two methods for creating an incrementing sequence number for the _id field using the following:

Use Counters Collection

Optimistic Loop

Considerations

Generally in MongoDB, you would not use an auto-increment pattern for the _id field, or any field, because it does not scale for databases with large numbers of documents. Typically the default value ObjectId is more ideal for the _id.

Procedures

Use Counters Collection

Counter Collection Implementation

Use a separate counters collection to track the last number sequence used. The _id field contains the sequence name and the seq field contains the last value of the sequence.

Insert into the counters collection, the initial value for the userid:

db.counters.insert(
   {
      _id: "userid",
      seq: 0
   }
)

Create a getNextSequence function that accepts a name of the sequence. The function uses the findAndModify() method to atomically increment the seq value and return this new value:

function getNextSequence(name) {
   var ret = db.counters.findAndModify(
          {
            query: { _id: name },
            update: { $inc: { seq: 1 } },
            new: true
          }
   );

   return ret.seq;
}

Use this getNextSequence() function during insert().

db.users.insert(
   {
     _id: getNextSequence("userid"),
     name: "Sarah C."
   }
)

db.users.insert(
   {
     _id: getNextSequence("userid"),
     name: "Bob D."
   }
)

You can verify the results with find():

db.users.find()

The _id fields contain incrementing sequence values:

{
  _id : 1,
  name : "Sarah C."
}
{
  _id : 2,
  name : "Bob D."
}

findAndModify Behavior

When findAndModify() includes the upsert: true option and the query field(s) is not uniquely indexed, the method could insert a document multiple times in certain circumstances. For instance, if multiple clients each invoke the method with the same query condition and these methods complete the find phase before any of methods perform the modify phase, these methods could insert the same document.

In the counters collection example, the query field is the _id field, which always has a unique index. Consider that the findAndModify() includes the upsert: true option, as in the following modified example:

function getNextSequence(name) {
   var ret = db.counters.findAndModify(
          {
            query: { _id: name },
            update: { $inc: { seq: 1 } },
            new: true,
            upsert: true
          }
   );

   return ret.seq;
}

If multiple clients were to invoke the getNextSequence() method with the same name parameter, then the methods would observe one of the following behaviors:

Exactly one findAndModify() would successfully insert a new document.

Zero or more findAndModify() methods would update the newly inserted document.

Zero or more findAndModify() methods would fail when they attempted to insert a duplicate.

If the method fails due to a unique index constraint violation, retry the method. Absent a delete of the document, the retry should not fail.

Optimistic Loop

In this pattern, an Optimistic Loop calculates the incremented _id value and attempts to insert a document with the calculated _id value. If the insert is successful, the loop ends. Otherwise, the loop will iterate through possible _id values until the insert is successful.

Create a function named insertDocument that performs the “insert if not present” loop. The function wraps the insert() method and takes a doc and a targetCollection arguments.

Changed in version 2.6: The db.collection.insert() method now returns a WriteResult object that contains the status of the operation. Previous versions required an extra db.getLastErrorObj() method call.

function insertDocument(doc, targetCollection) {

    while (1) {

        var cursor = targetCollection.find( {}, { _id: 1 } ).sort( { _id: -1 } ).limit(1);

        var seq = cursor.hasNext() ? cursor.next()._id + 1 : 1;

        doc._id = seq;

        var results = targetCollection.insert(doc);

        if( results.hasWriteError() ) {
            if( results.writeError.code == 11000 /* dup key */ )
                continue;
            else
                print( "unexpected error inserting data: " + tojson( results ) );
        }

        break;
    }
}

The while (1) loop performs the following actions:

Queries the targetCollection for the document with the maximum _id value.

Determines the next sequence value for _id by:

adding 1 to the returned _id value if the returned cursor points to a document.

otherwise: it sets the next sequence value to 1 if the returned cursor points to no document.

For the doc to insert, set its _id field to the calculated sequence value seq.

Insert the doc into the targetCollection.

If the insert operation errors with duplicate key, repeat the loop. Otherwise, if the insert operation encounters some other error or if the operation succeeds, break out of the loop.

Use the insertDocument() function to perform an insert:

var myCollection = db.users2;

insertDocument(
   {
     name: "Grace H."
   },
   myCollection
);

insertDocument(
   {
     name: "Ted R."
   },
   myCollection
)

You can verify the results with find():

db.users2.find()

The _id fields contain incrementing sequence values:

{
  _id: 1,
  name: "Grace H."
}
{
  _id : 2,
  "name" : "Ted R."
}

The while loop may iterate many times in collections with larger insert volumes.

MongoDB CRUD Reference

Query Cursor Methods

Name | Description
cursor.count() | Returns a count of the documents in a cursor.
cursor.explain() | Reports on the query execution plan, including index use, for a cursor.
cursor.hint() | Forces MongoDB to use a specific index for a query.
cursor.limit() | Constrains the size of a cursor’s result set.
cursor.next() | Returns the next document in a cursor.
cursor.skip() | Returns a cursor that begins returning results only after passing or skipping a number of documents.
cursor.sort() | Returns results ordered according to a sort specification.
cursor.toArray() | Returns an array that contains all documents returned by the cursor.

Query and Data Manipulation Collection Methods

Name | Description
db.collection.count() | Wraps count to return a count of the number of documents in a collection or matching a query.
db.collection.distinct() | Returns an array of documents that have distinct values for the specified field.
db.collection.find() | Performs a query on a collection and returns a cursor object.
db.collection.findOne() | Performs a query and returns a single document.
db.collection.insert() | Creates a new document in a collection.
db.collection.remove() | Deletes documents from a collection.
db.collection.save() | Provides a wrapper around an insert() and update() to insert new documents.
db.collection.update() | Modifies a document in a collection.

MongoDB CRUD Reference Documentation

Write Concern Reference

Configuration options associated with the guarantee MongoDB provides when reporting on the success of a write operation.

SQL to MongoDB Mapping Chart

An overview of common database operations showing both the MongoDB operations and SQL statements.

The bios Example Collection

Sample data for experimenting with MongoDB. insert(), update() and find() pages use the data for some of their examples.

Write Concern Reference

SQL to MongoDB Mapping Chart

The bios Example Collection

Write Concern Reference

Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation.

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations and eliminates the need to call the getLastError command. Previous versions required a getLastError command immediately after a write operation to specify the write concern.

Read Isolation Behavior

MongoDB allows clients to read documents inserted or modified before it commits these modifications to disk, regardless of write concern level or journaling configuration. As a result, applications may observe two classes of behaviors:

For systems with multiple concurrent readers and writers, MongoDB will allow clients to read the results of a write operation before the write operation returns.

If the mongod terminates before the journal commits, even if a write returns successfully, queries may have read data that will not exist after the mongod restarts.

Other database systems refer to these isolation semantics as read uncommitted. For all inserts and updates, MongoDB modifies each document in isolation: clients never see documents in intermediate states. For multi-document operations, MongoDB does not provide any multi-document transactions or isolation.

When mongod returns a successful journaled write concern, the data is fully committed to disk and will be available after mongod restarts.

For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of the voting members of the set. [1] MongoDB regularly commits data to the journal regardless of journaled write concern: use the commitIntervalMs to control how often a mongod commits the journal.

[1]
For the purposes of write concern, w:majority refers to a majority of all the members in the set. As a result, arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

Available Write Concern

Write concern can include the w option to specify the required number of acknowledgments before returning, the j option to require writes to the journal before returning, and wtimeout option to specify a time limit to prevent write operations from blocking indefinitely.

In sharded clusters, mongos instances will pass the write concern on to the shard.

w Option

The w option provides the ability to disable write concern entirely as well as specify the write concern for replica sets.

MongoDB uses w: 1 as the default write concern. w: 1 provides basic receipt acknowledgment.

The w option accepts the following values:

Value
Description

1

Provides acknowledgment of write operations on a standalone mongod or the primary in a replica set.

This is the default write concern for MongoDB.

0

Disables basic acknowledgment of write operations, but returns information about socket exceptions and networking errors to the application.

If you disable basic write operation acknowledgment but require journal commit acknowledgment, the journal commit prevails, and the server will require that mongod acknowledge the write operation.

<Number greater than 1>

Guarantees that write operations have propagated successfully to the specified number of replica set members including the primary.

For example, w: 2 indicates acknowledgements from the primary and at least one secondary.

If you set w to a number that is greater than the number of set members that hold data, MongoDB waits for the non-existent members to become available, which means MongoDB blocks indefinitely.

"majority"

Confirms that write operations have propagated to the majority of configured replica set: a majority of the set’s configured members must acknowledge the write operation before it succeeds. This allows you to avoid hard coding assumptions about the size of your replica set into your application.

Changed in version 2.6: In Master/Slave deployments, MongoDB treats w: "majority" as equivalent to w: 1. In earlier versions of MongoDB, w: "majority" produces an error in master/slave deployments.

<tag set>
By specifying a tag set, you can have fine-grained control over which replica set members must acknowledge a write operation to satisfy the required level of write concern.

j Option

The j option confirms that the mongod instance has written the data to the on-disk journal. This ensures that data is not lost if the mongod instance shuts down unexpectedly. Set to true to enable.

Changed in version 2.6: Specifying a write concern that includes j: true to a mongod or mongos running with --nojournal option now errors. Previous versions would ignore the j: true.

Note

Requiring journaled write concern in a replica set only requires a journal commit of the write operation to the primary of the set regardless of the level of replica acknowledged write concern.

wtimeout

This option specifies a time limit, in milliseconds, for the write concern. wtimeout is only applicable for w values greater than 1.

wtimeout causes write operations to return with an error after the specified limit, even if the required write concern will eventually succeed. When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the wtimeout time limit.

If you do not specify the wtimeout option and the level of write concern is unachievable, the write operation will block indefinitely. Specifying a wtimeout value of 0 is equivalent to a write concern without the wtimeout option.

See also

Write Concern Introduction and Write Concern for Replica Sets.

SQL to MongoDB Mapping Chart

In addition to the charts that follow, you might want to consider the Frequently Asked Questions section for a selection of common questions about MongoDB.

Terminology and Concepts

The following table presents the various SQL terminology and concepts and the corresponding MongoDB terminology and concepts.

SQL Terms/Concepts
MongoDB Terms/Concepts

database
database

table
collection

row
document or BSON document

column
field

index
index

table joins
embedded documents and linking

primary key

Specify any unique column or column combination as primary key.

primary key

In MongoDB, the primary key is automatically set to the _id field.

aggregation (e.g. group by)

aggregation pipeline

See the SQL to Aggregation Mapping Chart.

Executables

The following table presents some database executables and the corresponding MongoDB executables. This table is not meant to be exhaustive.

| MongoDB | MySQL | Oracle | Informix | DB2
Database Server | mongod | mysqld | oracle | IDS | DB2 Server
Database Client | mongo | mysql | sqlplus | DB-Access | DB2 Client

Examples

The following table presents the various SQL statements and the corresponding MongoDB statements. The examples in the table assume the following conditions:

The SQL examples assume a table named users.

The MongoDB examples assume a collection named users that contain documents of the following prototype:

{
  _id: ObjectId("509a8fb2f3f4948bd2f983a0"),
  user_id: "abc123",
  age: 55,
  status: 'A'
}

Create and Alter

The following table presents the various SQL statements related to table-level actions and the corresponding MongoDB statements.

SQL Schema Statements
MongoDB Schema Statements

CREATE TABLE users (
    id MEDIUMINT NOT NULL
        AUTO_INCREMENT,
    user_id Varchar(30),
    age Number,
    status char(1),
    PRIMARY KEY (id)
)

Implicitly created on first insert() operation. The primary key _id is automatically added if _id field is not specified.

db.users.insert( {
    user_id: "abc123",
    age: 55,
    status: "A"
 } )

However, you can also explicitly create a collection:

db.createCollection("users")

ALTER TABLE users
ADD join_date DATETIME

Collections do not describe or enforce the structure of its documents; i.e. there is no structural alteration at the collection level.

However, at the document level, update() operations can add fields to existing documents using the $set operator.

db.users.update(
    { },
    { $set: { join_date: new Date() } },
    { multi: true }
)

ALTER TABLE users
DROP COLUMN join_date

Collections do not describe or enforce the structure of its documents; i.e. there is no structural alteration at the collection level.

However, at the document level, update() operations can remove fields from documents using the $unset operator.

db.users.update(
    { },
    { $unset: { join_date: "" } },
    { multi: true }
)

CREATE INDEX idx_user_id_asc
ON users(user_id)

db.users.ensureIndex( { user_id: 1 } )

CREATE INDEX
       idx_user_id_asc_age_desc
ON users(user_id, age DESC)

db.users.ensureIndex( { user_id: 1, age: -1 } )

DROP TABLE users

db.users.drop()

For more information, see db.collection.insert(), db.createCollection(), db.collection.update(), $set, $unset, db.collection.ensureIndex(), indexes, db.collection.drop(), and Data Modeling Concepts.

Insert

The following table presents the various SQL statements related to inserting records into tables and the corresponding MongoDB statements.

SQL INSERT Statements
MongoDB insert() Statements

INSERT INTO users(user_id,
                  age,
                  status)
VALUES ("bcd001",
        45,
        "A")

db.users.insert(
   { user_id: "bcd001", age: 45, status: "A" }
)

For more information, see db.collection.insert().

Select

The following table presents the various SQL statements related to reading records from tables and the corresponding MongoDB statements.

SQL SELECT Statements
MongoDB find() Statements

SELECT *
FROM users

db.users.find()

SELECT id,
       user_id,
       status
FROM users

db.users.find(
    { },
    { user_id: 1, status: 1 }
)

SELECT user_id, status
FROM users

db.users.find(
    { },
    { user_id: 1, status: 1, _id: 0 }
)

SELECT *
FROM users
WHERE status = "A"

db.users.find(
    { status: "A" }
)

SELECT user_id, status
FROM users
WHERE status = "A"

db.users.find(
    { status: "A" },
    { user_id: 1, status: 1, _id: 0 }
)

SELECT *
FROM users
WHERE status != "A"

db.users.find(
    { status: { $ne: "A" } }
)

SELECT *
FROM users
WHERE status = "A"
AND age = 50

db.users.find(
    { status: "A",
      age: 50 }
)

SELECT *
FROM users
WHERE status = "A"
OR age = 50

db.users.find(
    { $or: [ { status: "A" } ,
             { age: 50 } ] }
)

SELECT *
FROM users
WHERE age > 25

db.users.find(
    { age: { $gt: 25 } }
)

SELECT *
FROM users
WHERE age < 25

db.users.find(
   { age: { $lt: 25 } }
)

SELECT *
FROM users
WHERE age > 25
AND   age <= 50

db.users.find(
   { age: { $gt: 25, $lte: 50 } }
)

SELECT *
FROM users
WHERE user_id like "%bc%"

db.users.find( { user_id: /bc/ } )

SELECT *
FROM users
WHERE user_id like "bc%"

db.users.find( { user_id: /^bc/ } )

SELECT *
FROM users
WHERE status = "A"
ORDER BY user_id ASC

db.users.find( { status: "A" } ).sort( { user_id: 1 } )

SELECT *
FROM users
WHERE status = "A"
ORDER BY user_id DESC

db.users.find( { status: "A" } ).sort( { user_id: -1 } )

SELECT COUNT(*)
FROM users

db.users.count()

or

db.users.find().count()

SELECT COUNT(user_id)
FROM users

db.users.count( { user_id: { $exists: true } } )

or

db.users.find( { user_id: { $exists: true } } ).count()

SELECT COUNT(*)
FROM users
WHERE age > 30

db.users.count( { age: { $gt: 30 } } )

or

db.users.find( { age: { $gt: 30 } } ).count()

SELECT DISTINCT(status)
FROM users

db.users.distinct( "status" )

SELECT *
FROM users
LIMIT 1

db.users.findOne()

or

db.users.find().limit(1)

SELECT *
FROM users
LIMIT 5
SKIP 10

db.users.find().limit(5).skip(10)

EXPLAIN SELECT *
FROM users
WHERE status = "A"

db.users.find( { status: "A" } ).explain()

For more information, see db.collection.find(), db.collection.distinct(), db.collection.findOne(), $ne $and, $or, $gt, $lt, $exists, $lte, $regex, limit(), skip(), explain(), sort(), and count().

Update Records

The following table presents the various SQL statements related to updating existing records in tables and the corresponding MongoDB statements.

SQL Update Statements
MongoDB update() Statements

UPDATE users
SET status = "C"
WHERE age > 25

db.users.update(
   { age: { $gt: 25 } },
   { $set: { status: "C" } },
   { multi: true }
)

UPDATE users
SET age = age + 3
WHERE status = "A"

db.users.update(
   { status: "A" } ,
   { $inc: { age: 3 } },
   { multi: true }
)

For more information, see db.collection.update(), $set, $inc, and $gt.

Delete Records

The following table presents the various SQL statements related to deleting records from tables and the corresponding MongoDB statements.

SQL Delete Statements
MongoDB remove() Statements

DELETE FROM users
WHERE status = "D"

db.users.remove( { status: "D" } )

DELETE FROM users

db.users.remove({})

For more information, see db.collection.remove().

Additional Resources

Transitioning from SQL to MongoDB (Presentation) [http://www.mongodb.com/presentations/webinar-transitioning-sql-mongodb]

Best Practices for Migrating from RDBMS to MongoDB (Webinar) [http://www.mongodb.com/webinar/best-practices-migration]

RDBMS to MongoDB Migration Guide [http://www.mongodb.com/lp/white-paper/migration-rdbms-nosql-mongodb]

SQL vs. MongoDB Day 1-2 [http://www.mongodb.com/blog/post/mongodb-vs-sql-day-1-2]

SQL vs. MongoDB Day 3-5 [http://www.mongodb.com/blog/post/mongodb-vs-sql-day-3-5]

MongoDB vs. SQL Day 18 [http://www.mongodb.com/blog/post/mongodb-vs-sql-day-14]

MongoDB and MySQL Compared [http://www.mongodb.com/mongodb-and-mysql-compared]

The bios Example Collection

The bios collection provides example data for experimenting with MongoDB. Many of this guide’s examples on insert, update and read operations create or query data from the bios collection.

The following documents comprise the bios collection. In the examples, the data might be different, as the examples themselves make changes to the data.

{
    "_id" : 1,
    "name" : {
        "first" : "John",
        "last" : "Backus"
    },
    "birth" : ISODate("1924-12-03T05:00:00Z"),
    "death" : ISODate("2007-03-17T04:00:00Z"),
    "contribs" : [
        "Fortran",
        "ALGOL",
        "Backus-Naur Form",
        "FP"
    ],
    "awards" : [
        {
            "award" : "W.W. McDowell Award",
            "year" : 1967,
            "by" : "IEEE Computer Society"
        },
        {
            "award" : "National Medal of Science",
            "year" : 1975,
            "by" : "National Science Foundation"
        },
        {
            "award" : "Turing Award",
            "year" : 1977,
            "by" : "ACM"
        },
        {
            "award" : "Draper Prize",
            "year" : 1993,
            "by" : "National Academy of Engineering"
        }
    ]
}

{
    "_id" : ObjectId("51df07b094c6acd67e492f41"),
    "name" : {
        "first" : "John",
        "last" : "McCarthy"
    },
    "birth" : ISODate("1927-09-04T04:00:00Z"),
    "death" : ISODate("2011-12-24T05:00:00Z"),
    "contribs" : [
        "Lisp",
        "Artificial Intelligence",
        "ALGOL"
    ],
    "awards" : [
        {
            "award" : "Turing Award",
            "year" : 1971,
            "by" : "ACM"
        },
        {
            "award" : "Kyoto Prize",
            "year" : 1988,
            "by" : "Inamori Foundation"
        },
        {
            "award" : "National Medal of Science",
            "year" : 1990,
            "by" : "National Science Foundation"
        }
    ]
}

{
    "_id" : 3,
    "name" : {
        "first" : "Grace",
        "last" : "Hopper"
    },
    "title" : "Rear Admiral",
    "birth" : ISODate("1906-12-09T05:00:00Z"),
    "death" : ISODate("1992-01-01T05:00:00Z"),
    "contribs" : [
        "UNIVAC",
        "compiler",
        "FLOW-MATIC",
        "COBOL"
    ],
    "awards" : [
        {
            "award" : "Computer Sciences Man of the Year",
            "year" : 1969,
            "by" : "Data Processing Management Association"
        },
        {
            "award" : "Distinguished Fellow",
            "year" : 1973,
            "by" : " British Computer Society"
        },
        {
            "award" : "W. W. McDowell Award",
            "year" : 1976,
            "by" : "IEEE Computer Society"
        },
        {
            "award" : "National Medal of Technology",
            "year" : 1991,
            "by" : "United States"
        }
    ]
}

{
    "_id" : 4,
    "name" : {
        "first" : "Kristen",
        "last" : "Nygaard"
    },
    "birth" : ISODate("1926-08-27T04:00:00Z"),
    "death" : ISODate("2002-08-10T04:00:00Z"),
    "contribs" : [
        "OOP",
        "Simula"
    ],
    "awards" : [
        {
            "award" : "Rosing Prize",
            "year" : 1999,
            "by" : "Norwegian Data Association"
        },
        {
            "award" : "Turing Award",
            "year" : 2001,
            "by" : "ACM"
        },
        {
            "award" : "IEEE John von Neumann Medal",
            "year" : 2001,
            "by" : "IEEE"
        }
    ]
}

{
    "_id" : 5,
    "name" : {
        "first" : "Ole-Johan",
        "last" : "Dahl"
    },
    "birth" : ISODate("1931-10-12T04:00:00Z"),
    "death" : ISODate("2002-06-29T04:00:00Z"),
    "contribs" : [
        "OOP",
        "Simula"
    ],
    "awards" : [
        {
            "award" : "Rosing Prize",
            "year" : 1999,
            "by" : "Norwegian Data Association"
        },
        {
            "award" : "Turing Award",
            "year" : 2001,
            "by" : "ACM"
        },
        {
            "award" : "IEEE John von Neumann Medal",
            "year" : 2001,
            "by" : "IEEE"
        }
    ]
}

{
    "_id" : 6,
    "name" : {
        "first" : "Guido",
        "last" : "van Rossum"
    },
    "birth" : ISODate("1956-01-31T05:00:00Z"),
    "contribs" : [
        "Python"
    ],
    "awards" : [
        {
            "award" : "Award for the Advancement of Free Software",
            "year" : 2001,
            "by" : "Free Software Foundation"
        },
        {
            "award" : "NLUUG Award",
            "year" : 2003,
            "by" : "NLUUG"
        }
    ]
}

{
    "_id" : ObjectId("51e062189c6ae665454e301d"),
    "name" : {
        "first" : "Dennis",
        "last" : "Ritchie"
    },
    "birth" : ISODate("1941-09-09T04:00:00Z"),
    "death" : ISODate("2011-10-12T04:00:00Z"),
    "contribs" : [
        "UNIX",
        "C"
    ],
    "awards" : [
        {
            "award" : "Turing Award",
            "year" : 1983,
            "by" : "ACM"
        },
        {
            "award" : "National Medal of Technology",
            "year" : 1998,
            "by" : "United States"
        },
        {
            "award" : "Japan Prize",
            "year" : 2011,
            "by" : "The Japan Prize Foundation"
        }
    ]
}

{
    "_id" : 8,
    "name" : {
        "first" : "Yukihiro",
        "aka" : "Matz",
        "last" : "Matsumoto"
    },
    "birth" : ISODate("1965-04-14T04:00:00Z"),
    "contribs" : [
        "Ruby"
    ],
    "awards" : [
        {
            "award" : "Award for the Advancement of Free Software",
            "year" : "2011",
            "by" : "Free Software Foundation"
        }
    ]
}

{
    "_id" : 9,
    "name" : {
        "first" : "James",
        "last" : "Gosling"
    },
    "birth" : ISODate("1955-05-19T04:00:00Z"),
    "contribs" : [
        "Java"
    ],
    "awards" : [
        {
            "award" : "The Economist Innovation Award",
            "year" : 2002,
            "by" : "The Economist"
        },
        {
            "award" : "Officer of the Order of Canada",
            "year" : 2007,
            "by" : "Canada"
        }
    ]
}

{
    "_id" : 10,
    "name" : {
        "first" : "Martin",
        "last" : "Odersky"
    },
    "contribs" : [
        "Scala"
    ]
}

Data Models

Data in MongoDB has a flexible schema. Collections do not enforce document structure. This flexibility gives you data-modeling choices to match your application and its performance requirements.

Data Modeling Introduction

An introduction to data modeling in MongoDB.

Data Modeling Concepts

The core documentation detailing the decisions you must make when determining a data model, and discussing considerations that should be taken into account.

Data Model Examples and Patterns

Examples of possible data models that you can use to structure your MongoDB documents.

Data Model Reference

Reference material for data modeling for developers of MongoDB applications.

Data Modeling Introduction

Data Modeling Concepts

Data Model Design

Operational Factors and Data Models

GridFS

Data Model Examples and Patterns

Model Relationships Between Documents

Model One-to-One Relationships with Embedded Documents

Model One-to-Many Relationships with Embedded Documents

Model One-to-Many Relationships with Document References

Model Tree Structures

Model Tree Structures with Parent References

Model Tree Structures with Child References

Model Tree Structures with an Array of Ancestors

Model Tree Structures with Materialized Paths

Model Tree Structures with Nested Sets

Model Specific Application Contexts

Model Data for Atomic Operations

Model Data to Support Keyword Search

Model Monetary Data

Model Time Data

Data Model Reference

Documents

Database References

GridFS Reference

ObjectId

BSON Types

Data Modeling Introduction

Data in MongoDB has a flexible schema. Unlike SQL databases, where you must determine and declare a table’s schema before inserting data, MongoDB’s collections do not enforce document structure. This flexibility facilitates the mapping of documents to an entity or an object. Each document can match the data fields of the represented entity, even if the data has substantial variation. In practice, however, the documents in a collection share a similar structure.

The key challenge in data modeling is balancing the needs of the application, the performance characteristics of the database engine, and the data retrieval patterns. When designing data models, always consider the application usage of the data (i.e. queries, updates, and processing of the data) as well as the inherent structure of the data itself.

Document Structure

The key decision in designing data models for MongoDB applications revolves around the structure of documents and how the application represents relationships between data. There are two tools that allow applications to represent these relationships: references and embedded documents.

References

References store the relationships between data by including links or references from one document to another. Applications can resolve these references to access the related data. Broadly, these are normalized data models.

See Normalized Data Models for the strengths and weaknesses of using references.

Embedded Data

Embedded documents capture relationships between data by storing related data in a single document structure. MongoDB documents make it possible to embed document structures in a field or array within a document. These denormalized data models allow applications to retrieve and manipulate related data in a single database operation.

See Embedded Data Models for the strengths and weaknesses of embedding documents.

Atomicity of Write Operations

In MongoDB, write operations are atomic at the document level, and no single write operation can atomically affect more than one document or more than one collection. A denormalized data model with embedded data combines all related data for a represented entity in a single document. This facilitates atomic write operations since a single write operation can insert or update the data for an entity. Normalizing the data would split the data across multiple collections and would require multiple write operations that are not atomic collectively.

However, schemas that facilitate atomic writes may limit ways that applications can use the data or may limit ways to modify applications. The Atomicity Considerations documentation describes the challenge of designing a schema that balances flexibility and atomicity.

Document Growth

Some updates, such as pushing elements to an array or adding new fields, increase a document’s size. If the document size exceeds the allocated space for that document, MongoDB relocates the document on disk. The growth consideration can affect the decision to normalize or denormalize data. See Document Growth Considerations for more about planning for and managing document growth in MongoDB.

Data Use and Performance

When designing a data model, consider how applications will use your database. For instance, if your application only uses recently inserted documents, consider using Capped Collections. Or if your application needs are mainly read operations to a collection, adding indexes to support common queries can improve performance.

See Operational Factors and Data Models for more information on these and other operational considerations that affect data model designs.

Data Modeling Concepts

Consider the following aspects of data modeling in MongoDB:

Data Model Design

Presents the different strategies that you can choose from when determining your data model, their strengths and their weaknesses.

Operational Factors and Data Models

Details features you should keep in mind when designing your data model, such as lifecycle management, indexing, horizontal scalability, and document growth.

GridFS

GridFS is a specification for storing documents that exceeds the BSON-document size limit of 16MB.

For a general introduction to data modeling in MongoDB, see the Data Modeling Introduction. For example data models, see Data Modeling Examples and Patterns.

Data Model Design

Operational Factors and Data Models

GridFS

Data Model Design

Effective data models support your application needs. The key consideration for the structure of your documents is the decision to embed or to use references.

Embedded Data Models

With MongoDB, you may embed related data in a single structure or document. These schema are generally known as “denormalized” models, and take advantage of MongoDB’s rich documents. Consider the following diagram:

Embedded data models allow applications to store related pieces of information in the same database record. As a result, applications may need to issue fewer queries and updates to complete common operations.

In general, use embedded data models when:

you have “contains” relationships between entities. See Model One-to-One Relationships with Embedded Documents.

you have one-to-many relationships between entities. In these relationships the “many” or child documents always appear with or are viewed in the context of the “one” or parent documents. See Model One-to-Many Relationships with Embedded Documents.

In general, embedding provides better performance for read operations, as well as the ability to request and retrieve related data in a single database operation. Embedded data models make it possible to update related data in a single atomic write operation.

However, embedding related data in documents may lead to situations where documents grow after creation. Document growth can impact write performance and lead to data fragmentation. See Document Growth for details. Furthermore, documents in MongoDB must be smaller than the maximum BSON document size. For bulk binary data, consider GridFS.

To interact with embedded documents, use dot notation to “reach into” embedded documents. See query for data in arrays and query data in embedded documents for more examples on accessing data in arrays and embedded documents.

Normalized Data Models

Normalized data models describe relationships using references between documents.

In general, use normalized data models:

when embedding would result in duplication of data but would not provide sufficient read performance advantages to outweigh the implications of the duplication.

to represent more complex many-to-many relationships.

to model large hierarchical data sets.

References provides more flexibility than embedding. However, client-side applications must issue follow-up queries to resolve the references. In other words, normalized data models can require more round trips to the server.

See Model One-to-Many Relationships with Document References for an example of referencing. For examples of various tree models using references, see Model Tree Structures.

Additional Resources

Thinking in Documents (Presentation) [http://www.mongodb.com/presentations/webinar-back-basics-1-thinking-documents]

Schema Design for Time Series Data (Presentation) [http://www.mongodb.com/presentations/webinar-time-series-data-mongodb]

Socialite, the Open Source Status Feed - Storing a Social Graph (Presentation) [http://www.mongodb.com/presentations/socialite-open-source-status-feed-part-2-managing-social-graph]

MongoDB Schema Design Consultation Services [https://www.mongodb.com/products/consulting#schema_design]

Operational Factors and Data Models

Modeling application data for MongoDB depends on both the data itself, as well as the characteristics of MongoDB itself. For example, different data models may allow applications to use more efficient queries, increase the throughput of insert and update operations, or distribute activity to a sharded cluster more effectively.

These factors are operational or address requirements that arise outside of the application but impact the performance of MongoDB based applications. When developing a data model, analyze all of your application’s read operations and write operations in conjunction with the following considerations.

Document Growth

Some updates to documents can increase the size of documents. These updates include pushing elements to an array (i.e. $push) and adding new fields to a document. If the document size exceeds the allocated space for that document, MongoDB will relocate the document on disk. Relocating documents takes longer than in place updates and can lead to fragmented storage. Although MongoDB automatically adds padding to document allocations to minimize the likelihood of relocation, data models should avoid document growth when possible.

For instance, if your applications require updates that will cause document growth, you may want to refactor your data model to use references between data in distinct documents rather than a denormalized data model.

MongoDB adaptively adjusts the amount of automatic padding to reduce occurrences of relocation. You may also use a pre-allocation strategy to explicitly avoid document growth. Refer to the Pre-Aggregated Reports Use Case [http://docs.mongodb.org/ecosystem/use-cases/pre-aggregated-reports] for an example of the pre-allocation approach to handling document growth.

See Storage for more information on MongoDB’s storage model and record allocation strategies.

Atomicity

In MongoDB, operations are atomic at the document level. No single write operation can change more than one document. Operations that modify more than a single document in a collection still operate on one document at a time. [1] Ensure that your application stores all fields with atomic dependency requirements in the same document. If the application can tolerate non-atomic updates for two pieces of data, you can store these data in separate documents.

A data model that embeds related data in a single document facilitates these kinds of atomic operations. For data models that store references between related pieces of data, the application must issue separate read and write operations to retrieve and modify these related pieces of data.

See Model Data for Atomic Operations for an example data model that provides atomic updates for a single document.

[1]
Document-level atomic operations include all operations within a single MongoDB document record: operations that affect multiple embedded documents within that single record are still atomic.

Sharding

MongoDB uses sharding to provide horizontal scaling. These clusters support deployments with large data sets and high-throughput operations. Sharding allows users to partition a collection within a database to distribute the collection’s documents across a number of mongod instances or shards.

To distribute data and application traffic in a sharded collection, MongoDB uses the shard key. Selecting the proper shard key has significant implications for performance, and can enable or prevent query isolation and increased write capacity. It is important to consider carefully the field or fields to use as the shard key.

See Sharding Introduction and Shard Keys for more information.

Indexes

Use indexes to improve performance for common queries. Build indexes on fields that appear often in queries and for all operations that return sorted results. MongoDB automatically creates a unique index on the _id field.

As you create indexes, consider the following behaviors of indexes:

Each index requires at least 8KB of data space.

Adding an index has some negative performance impact for write operations. For collections with high write-to-read ratio, indexes are expensive since each insert must also update any indexes.

Collections with high read-to-write ratio often benefit from additional indexes. Indexes do not affect un-indexed read operations.

When active, each index consumes disk space and memory. This usage can be significant and should be tracked for capacity planning, especially for concerns over working set size.

See Indexing Strategies for more information on indexes as well as Analyze Query Performance. Additionally, the MongoDB database profiler may help identify inefficient queries.

Large Number of Collections

In certain situations, you might choose to store related information in several collections rather than in a single collection.

Consider a sample collection logs that stores log documents for various environment and applications. The logs collection contains documents of the following form:

{ log: "dev", ts: ..., info: ... }
{ log: "debug", ts: ..., info: ...}

If the total number of documents is low, you may group documents into collection by type. For logs, consider maintaining distinct log collections, such as logs_dev and logs_debug. The logs_dev collection would contain only the documents related to the dev environment.

Generally, having a large number of collections has no significant performance penalty and results in very good performance. Distinct collections are very important for high-throughput batch processing.

When using models that have a large number of collections, consider the following behaviors:

Each collection has a certain minimum overhead of a few kilobytes.

Each index, including the index on _id, requires at least 8KB of data space.

For each database, a single namespace file (i.e. <database>.ns) stores all meta-data for that database, and each index and collection has its own entry in the namespace file. MongoDB places limits on the size of namespace files.

MongoDB has limits on the number of namespaces. You may wish to know the current number of namespaces in order to determine how many additional namespaces the database can support. To get the current number of namespaces, run the following in the mongo shell:

db.system.namespaces.count()

The limit on the number of namespaces depend on the <database>.ns size. The namespace file defaults to 16 MB.

To change the size of the new namespace file, start the server with the option --nssize <new size MB>. For existing databases, after starting up the server with --nssize, run the db.repairDatabase() command from the mongo shell. For impacts and considerations on running db.repairDatabase(), see repairDatabase.

Data Lifecycle Management

Data modeling decisions should take data lifecycle management into consideration.

The Time to Live or TTL feature of collections expires documents after a period of time. Consider using the TTL feature if your application requires some data to persist in the database for a limited period of time.

Additionally, if your application only uses recently inserted documents, consider Capped Collections. Capped collections provide first-in-first-out (FIFO) management of inserted documents and efficiently support operations that insert and read documents based on insertion order.

GridFS

GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16MB.

Instead of storing a file in a single document, GridFS divides a file into parts, or chunks, [1] and stores each of those chunks as a separate document. By default GridFS limits chunk size to 255k. GridFS uses two collections to store files. One collection stores the file chunks, and the other stores file metadata.

When you query a GridFS store for a file, the driver or client will reassemble the chunks as needed. You can perform range queries on files stored through GridFS. You also can access information from arbitrary sections of files, which allows you to “skip” into the middle of a video or audio file.

GridFS is useful not only for storing files that exceed 16MB but also for storing any files for which you want access without having to load the entire file into memory. For more information on the indications of GridFS, see When should I use GridFS?.

[1]
The use of the term chunks in the context of GridFS is not related to the use of the term chunks in the context of sharding.

Changed in version 2.4.10: The default chunk size changed from 256k to 255k.

Implement GridFS

To store and retrieve files using GridFS, use either of the following:

A MongoDB driver. See the drivers documentation for information on using GridFS with your driver.

The mongofiles command-line tool in the mongo shell. See the mongofiles reference for complete documentation.

GridFS Collections

GridFS stores files in two collections:

chunks stores the binary chunks. For details, see The chunks Collection.

files stores the file’s metadata. For details, see The files Collection.

GridFS places the collections in a common bucket by prefixing each with the bucket name. By default, GridFS uses two collections with names prefixed by fs bucket:

fs.files

fs.chunks

You can choose a different bucket name than fs, and create multiple buckets in a single database.

Each document in the chunks collection represents a distinct chunk of a file as represented in the GridFS store. Each chunk is identified by its unique ObjectId stored in its _id field.

For descriptions of all fields in the chunks and files collections, see GridFS Reference.

GridFS Index

GridFS uses a unique, compound index on the chunks collection for the files_id and n fields. The files_id field contains the _id of the chunk’s “parent” document. The n field contains the sequence number of the chunk. GridFS numbers all chunks, starting with 0. For descriptions of the documents and fields in the chunks collection, see GridFS Reference.

The GridFS index allows efficient retrieval of chunks using the files_id and n values, as shown in the following example:

cursor = db.fs.chunks.find({files_id: myFileID}).sort({n:1});

See the relevant driver documentation for the specific behavior of your GridFS application. If your driver does not create this index, issue the following operation using the mongo shell:

db.fs.chunks.ensureIndex( { files_id: 1, n: 1 }, { unique: true } );

Additional Resources

Building MongoDB Applications with Binary Files Using GridFS: Part 1 [http://www.mongodb.com/blog/post/building-mongodb-applications-binary-files-using-gridfs-part-1]

Building MongoDB Applications with Binary Files Using GridFS: Part 2 [http://www.mongodb.com/blog/post/building-mongodb-applications-binary-files-using-gridfs-part-2]

Data Model Examples and Patterns

The following documents provide overviews of various data modeling patterns and common schema design considerations:

Model Relationships Between Documents

Examples for modeling relationships between documents.

Model One-to-One Relationships with Embedded Documents

Presents a data model that uses embedded documents to describe one-to-one relationships between connected data.

Model One-to-Many Relationships with Embedded Documents

Presents a data model that uses embedded documents to describe one-to-many relationships between connected data.

Model One-to-Many Relationships with Document References

Presents a data model that uses references to describe one-to-many relationships between documents.

Model Tree Structures

Examples for modeling tree structures.

Model Tree Structures with Parent References

Presents a data model that organizes documents in a tree-like structure by storing references to “parent” nodes in “child” nodes.

Model Tree Structures with Child References

Presents a data model that organizes documents in a tree-like structure by storing references to “child” nodes in “parent” nodes.

See Model Tree Structures for additional examples of data models for tree structures.

Model Specific Application Contexts

Examples for models for specific application contexts.

Model Data for Atomic Operations

Illustrates how embedding fields related to an atomic update within the same document ensures that the fields are in sync.

Model Data to Support Keyword Search

Describes one method for supporting keyword search by storing keywords in an array in the same document as the text field. Combined with a multi-key index, this pattern can support application’s keyword search operations.

Model Relationships Between Documents

Model One-to-One Relationships with Embedded Documents

Model One-to-Many Relationships with Embedded Documents

Model One-to-Many Relationships with Document References

Model Tree Structures

Model Tree Structures with Parent References

Model Tree Structures with Child References

Model Tree Structures with an Array of Ancestors

Model Tree Structures with Materialized Paths

Model Tree Structures with Nested Sets

Model Specific Application Contexts

Model Data for Atomic Operations

Model Data to Support Keyword Search

Model Monetary Data

Model Time Data

Model Relationships Between Documents

Model One-to-One Relationships with Embedded Documents

Presents a data model that uses embedded documents to describe one-to-one relationships between connected data.

Model One-to-Many Relationships with Embedded Documents

Presents a data model that uses embedded documents to describe one-to-many relationships between connected data.

Model One-to-Many Relationships with Document References

Presents a data model that uses references to describe one-to-many relationships between documents.

Model One-to-One Relationships with Embedded Documents

Model One-to-Many Relationships with Embedded Documents

Model One-to-Many Relationships with Document References

Model One-to-One Relationships with Embedded Documents

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that uses embedded documents to describe relationships between connected data.

Pattern

Consider the following example that maps patron and address relationships. The example illustrates the advantage of embedding over referencing if you need to view one data entity in context of the other. In this one-to-one relationship between patron and address data, the address belongs to the patron.

In the normalized data model, the address document contains a reference to the patron document.

{
   _id: "joe",
   name: "Joe Bookreader"
}

{
   patron_id: "joe",
   street: "123 Fake Street",
   city: "Faketon",
   state: "MA",
   zip: "12345"
}

If the address data is frequently retrieved with the name information, then with referencing, your application needs to issue multiple queries to resolve the reference. The better data model would be to embed the address data in the patron data, as in the following document:

{
   _id: "joe",
   name: "Joe Bookreader",
   address: {
              street: "123 Fake Street",
              city: "Faketon",
              state: "MA",
              zip: "12345"
            }
}

With the embedded data model, your application can retrieve the complete patron information with one query.

Model One-to-Many Relationships with Embedded Documents

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that uses embedded documents to describe relationships between connected data.

Pattern

Consider the following example that maps patron and multiple address relationships. The example illustrates the advantage of embedding over referencing if you need to view many data entities in context of another. In this one-to-many relationship between patron and address data, the patron has multiple address entities.

In the normalized data model, the address documents contain a reference to the patron document.

{
   _id: "joe",
   name: "Joe Bookreader"
}

{
   patron_id: "joe",
   street: "123 Fake Street",
   city: "Faketon",
   state: "MA",
   zip: "12345"
}

{
   patron_id: "joe",
   street: "1 Some Other Street",
   city: "Boston",
   state: "MA",
   zip: "12345"
}

If your application frequently retrieves the address data with the name information, then your application needs to issue multiple queries to resolve the references. A more optimal schema would be to embed the address data entities in the patron data, as in the following document:

{
   _id: "joe",
   name: "Joe Bookreader",
   addresses: [
                {
                  street: "123 Fake Street",
                  city: "Faketon",
                  state: "MA",
                  zip: "12345"
                },
                {
                  street: "1 Some Other Street",
                  city: "Boston",
                  state: "MA",
                  zip: "12345"
                }
              ]
 }

With the embedded data model, your application can retrieve the complete patron information with one query.

Model One-to-Many Relationships with Document References

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that uses references between documents to describe relationships between connected data.

Pattern

Consider the following example that maps publisher and book relationships. The example illustrates the advantage of referencing over embedding to avoid repetition of the publisher information.

Embedding the publisher document inside the book document would lead to repetition of the publisher data, as the following documents show:

{
   title: "MongoDB: The Definitive Guide",
   author: [ "Kristina Chodorow", "Mike Dirolf" ],
   published_date: ISODate("2010-09-24"),
   pages: 216,
   language: "English",
   publisher: {
              name: "O'Reilly Media",
              founded: 1980,
              location: "CA"
            }
}

{
   title: "50 Tips and Tricks for MongoDB Developer",
   author: "Kristina Chodorow",
   published_date: ISODate("2011-05-06"),
   pages: 68,
   language: "English",
   publisher: {
              name: "O'Reilly Media",
              founded: 1980,
              location: "CA"
            }
}

To avoid repetition of the publisher data, use references and keep the publisher information in a separate collection from the book collection.

When using references, the growth of the relationships determine where to store the reference. If the number of books per publisher is small with limited growth, storing the book reference inside the publisher document may sometimes be useful. Otherwise, if the number of books per publisher is unbounded, this data model would lead to mutable, growing arrays, as in the following example:

{
   name: "O'Reilly Media",
   founded: 1980,
   location: "CA",
   books: [12346789, 234567890, ...]
}

{
    _id: 123456789,
    title: "MongoDB: The Definitive Guide",
    author: [ "Kristina Chodorow", "Mike Dirolf" ],
    published_date: ISODate("2010-09-24"),
    pages: 216,
    language: "English"
}

{
   _id: 234567890,
   title: "50 Tips and Tricks for MongoDB Developer",
   author: "Kristina Chodorow",
   published_date: ISODate("2011-05-06"),
   pages: 68,
   language: "English"
}

To avoid mutable, growing arrays, store the publisher reference inside the book document:

{
   _id: "oreilly",
   name: "O'Reilly Media",
   founded: 1980,
   location: "CA"
}

{
   _id: 123456789,
   title: "MongoDB: The Definitive Guide",
   author: [ "Kristina Chodorow", "Mike Dirolf" ],
   published_date: ISODate("2010-09-24"),
   pages: 216,
   language: "English",
   publisher_id: "oreilly"
}

{
   _id: 234567890,
   title: "50 Tips and Tricks for MongoDB Developer",
   author: "Kristina Chodorow",
   published_date: ISODate("2011-05-06"),
   pages: 68,
   language: "English",
   publisher_id: "oreilly"
}

Model Tree Structures

MongoDB allows various ways to use tree data structures to model large hierarchical or nested data relationships.

Model Tree Structures with Parent References

Presents a data model that organizes documents in a tree-like structure by storing references to “parent” nodes in “child” nodes.

Model Tree Structures with Child References

Presents a data model that organizes documents in a tree-like structure by storing references to “child” nodes in “parent” nodes.

Model Tree Structures with an Array of Ancestors

Presents a data model that organizes documents in a tree-like structure by storing references to “parent” nodes and an array that stores all ancestors.

Model Tree Structures with Materialized Paths

Presents a data model that organizes documents in a tree-like structure by storing full relationship paths between documents. In addition to the tree node, each document stores the _id of the nodes ancestors or path as a string.

Model Tree Structures with Nested Sets

Presents a data model that organizes documents in a tree-like structure using the Nested Sets pattern. This optimizes discovering subtrees at the expense of tree mutability.

Model Tree Structures with Parent References

Model Tree Structures with Child References

Model Tree Structures with an Array of Ancestors

Model Tree Structures with Materialized Paths

Model Tree Structures with Nested Sets

Model Tree Structures with Parent References

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that describes a tree-like structure in MongoDB documents by storing references to “parent” nodes in children nodes.

Pattern

The Parent References pattern stores each tree node in a document; in addition to the tree node, the document stores the id of the node’s parent.

Consider the following hierarchy of categories:

The following example models the tree using Parent References, storing the reference to the parent category in the field parent:

db.categories.insert( { _id: "MongoDB", parent: "Databases" } )
db.categories.insert( { _id: "dbm", parent: "Databases" } )
db.categories.insert( { _id: "Databases", parent: "Programming" } )
db.categories.insert( { _id: "Languages", parent: "Programming" } )
db.categories.insert( { _id: "Programming", parent: "Books" } )
db.categories.insert( { _id: "Books", parent: null } )

The query to retrieve the parent of a node is fast and straightforward:

db.categories.findOne( { _id: "MongoDB" } ).parent

You can create an index on the field parent to enable fast search by the parent node:

db.categories.ensureIndex( { parent: 1 } )

You can query by the parent field to find its immediate children nodes:

db.categories.find( { parent: "Databases" } )

The Parent Links pattern provides a simple solution to tree storage but requires multiple queries to retrieve subtrees.

Model Tree Structures with Child References

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that describes a tree-like structure in MongoDB documents by storing references in the parent-nodes to children nodes.

Pattern

The Child References pattern stores each tree node in a document; in addition to the tree node, document stores in an array the id(s) of the node’s children.

Consider the following hierarchy of categories:

The following example models the tree using Child References, storing the reference to the node’s children in the field children:

db.categories.insert( { _id: "MongoDB", children: [] } )
db.categories.insert( { _id: "dbm", children: [] } )
db.categories.insert( { _id: "Databases", children: [ "MongoDB", "dbm" ] } )
db.categories.insert( { _id: "Languages", children: [] } )
db.categories.insert( { _id: "Programming", children: [ "Databases", "Languages" ] } )
db.categories.insert( { _id: "Books", children: [ "Programming" ] } )

The query to retrieve the immediate children of a node is fast and straightforward:

db.categories.findOne( { _id: "Databases" } ).children

You can create an index on the field children to enable fast search by the child nodes:

db.categories.ensureIndex( { children: 1 } )

You can query for a node in the children field to find its parent node as well as its siblings:

db.categories.find( { children: "MongoDB" } )

The Child References pattern provides a suitable solution to tree storage as long as no operations on subtrees are necessary. This pattern may also provide a suitable solution for storing graphs where a node may have multiple parents.

Model Tree Structures with an Array of Ancestors

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that describes a tree-like structure in MongoDB documents using references to parent nodes and an array that stores all ancestors.

Pattern

The Array of Ancestors pattern stores each tree node in a document; in addition to the tree node, document stores in an array the id(s) of the node’s ancestors or path.

Consider the following hierarchy of categories:

The following example models the tree using Array of Ancestors. In addition to the ancestors field, these documents also store the reference to the immediate parent category in the parent field:

db.categories.insert( { _id: "MongoDB", ancestors: [ "Books", "Programming", "Databases" ], parent: "Databases" } )
db.categories.insert( { _id: "dbm", ancestors: [ "Books", "Programming", "Databases" ], parent: "Databases" } )
db.categories.insert( { _id: "Databases", ancestors: [ "Books", "Programming" ], parent: "Programming" } )
db.categories.insert( { _id: "Languages", ancestors: [ "Books", "Programming" ], parent: "Programming" } )
db.categories.insert( { _id: "Programming", ancestors: [ "Books" ], parent: "Books" } )
db.categories.insert( { _id: "Books", ancestors: [ ], parent: null } )

The query to retrieve the ancestors or path of a node is fast and straightforward:

db.categories.findOne( { _id: "MongoDB" } ).ancestors

You can create an index on the field ancestors to enable fast search by the ancestors nodes:

db.categories.ensureIndex( { ancestors: 1 } )

You can query by the field ancestors to find all its descendants:

db.categories.find( { ancestors: "Programming" } )

The Array of Ancestors pattern provides a fast and efficient solution to find the descendants and the ancestors of a node by creating an index on the elements of the ancestors field. This makes Array of Ancestors a good choice for working with subtrees.

The Array of Ancestors pattern is slightly slower than the Materialized Paths pattern but is more straightforward to use.

Model Tree Structures with Materialized Paths

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that describes a tree-like structure in MongoDB documents by storing full relationship paths between documents.

Pattern

The Materialized Paths pattern stores each tree node in a document; in addition to the tree node, document stores as a string the id(s) of the node’s ancestors or path. Although the Materialized Paths pattern requires additional steps of working with strings and regular expressions, the pattern also provides more flexibility in working with the path, such as finding nodes by partial paths.

Consider the following hierarchy of categories:

The following example models the tree using Materialized Paths, storing the path in the field path; the path string uses the comma , as a delimiter:

db.categories.insert( { _id: "Books", path: null } )
db.categories.insert( { _id: "Programming", path: ",Books," } )
db.categories.insert( { _id: "Databases", path: ",Books,Programming," } )
db.categories.insert( { _id: "Languages", path: ",Books,Programming," } )
db.categories.insert( { _id: "MongoDB", path: ",Books,Programming,Databases," } )
db.categories.insert( { _id: "dbm", path: ",Books,Programming,Databases," } )

You can query to retrieve the whole tree, sorting by the field path:

db.categories.find().sort( { path: 1 } )

You can use regular expressions on the path field to find the descendants of Programming:

db.categories.find( { path: /,Programming,/ } )

You can also retrieve the descendants of Books where the Books is also at the topmost level of the hierarchy:

db.categories.find( { path: /^,Books,/ } )

To create an index on the field path use the following invocation:

db.categories.ensureIndex( { path: 1 } )

This index may improve performance depending on the query:

For queries of the Books sub-tree (e.g. /^,Books,/) an index on the path field improves the query performance significantly.

For queries of the Programming sub-tree (e.g. /,Programming,/), or similar queries of sub-tress, where the node might be in the middle of the indexed string, the query must inspect the entire index.

For these queries an index may provide some performance improvement if the index is significantly smaller than the entire collection.

Model Tree Structures with Nested Sets

Overview

Data in MongoDB has a flexible schema. Collections do not enforce document structure. Decisions that affect how you model data can affect application performance and database capacity. See Data Modeling Concepts for a full high level overview of data modeling in MongoDB.

This document describes a data model that describes a tree like structure that optimizes discovering subtrees at the expense of tree mutability.

Pattern

The Nested Sets pattern identifies each node in the tree as stops in a round-trip traversal of the tree. The application visits each node in the tree twice; first during the initial trip, and second during the return trip. The Nested Sets pattern stores each tree node in a document; in addition to the tree node, document stores the id of node’s parent, the node’s initial stop in the left field, and its return stop in the right field.

Consider the following hierarchy of categories:

The following example models the tree using Nested Sets:

db.categories.insert( { _id: "Books", parent: 0, left: 1, right: 12 } )
db.categories.insert( { _id: "Programming", parent: "Books", left: 2, right: 11 } )
db.categories.insert( { _id: "Languages", parent: "Programming", left: 3, right: 4 } )
db.categories.insert( { _id: "Databases", parent: "Programming", left: 5, right: 10 } )
db.categories.insert( { _id: "MongoDB", parent: "Databases", left: 6, right: 7 } )
db.categories.insert( { _id: "dbm", parent: "Databases", left: 8, right: 9 } )

You can query to retrieve the descendants of a node:

var databaseCategory = db.categories.findOne( { _id: "Databases" } );
db.categories.find( { left: { $gt: databaseCategory.left }, right: { $lt: databaseCategory.right } } );

The Nested Sets pattern provides a fast and efficient solution for finding subtrees but is inefficient for modifying the tree structure. As such, this pattern is best for static trees that do not change.

Model Specific Application Contexts

Model Data for Atomic Operations

Illustrates how embedding fields related to an atomic update within the same document ensures that the fields are in sync.

Model Data to Support Keyword Search

Describes one method for supporting keyword search by storing keywords in an array in the same document as the text field. Combined with a multi-key index, this pattern can support application’s keyword search operations.

Model Monetary Data

Describes two methods to model monetary data in MongoDB.

Model Time Data

Describes how to deal with local time in MongoDB.

Model Data for Atomic Operations

Model Data to Support Keyword Search

Model Monetary Data

Model Time Data

Model Data for Atomic Operations

Pattern

In MongoDB, write operations, e.g. db.collection.update(), db.collection.findAndModify(), db.collection.remove(), are atomic on the level of a single document. For fields that must be updated together, embedding the fields within the same document ensures that the fields can be updated atomically.

For example, consider a situation where you need to maintain information on books, including the number of copies available for checkout as well as the current checkout information.

The available copies of the book and the checkout information should be in sync. As such, embedding the available field and the checkout field within the same document ensures that you can update the two fields atomically.

{
    _id: 123456789,
    title: "MongoDB: The Definitive Guide",
    author: [ "Kristina Chodorow", "Mike Dirolf" ],
    published_date: ISODate("2010-09-24"),
    pages: 216,
    language: "English",
    publisher_id: "oreilly",
    available: 3,
    checkout: [ { by: "joe", date: ISODate("2012-10-15") } ]
}

Then to update with new checkout information, you can use the db.collection.update() method to atomically update both the available field and the checkout field:

db.books.update (
   { _id: 123456789, available: { $gt: 0 } },
   {
     $inc: { available: -1 },
     $push: { checkout: { by: "abc", date: new Date() } }
   }
)

The operation returns a WriteResult() object that contains information on the status of the operation:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

The nMatched field shows that 1 document matched the update condition, and nModified shows that the operation updated 1 document.

If no document matched the update condition, then nMatched and nModified would be 0 and would indicate that you could not check out the book.

Model Data to Support Keyword Search

Note

Keyword search is not the same as text search or full text search, and does not provide stemming or other text-processing features. See the Limitations of Keyword Indexes section for more information.

In 2.4, MongoDB provides a text search feature. See Text Indexes for more information.

If your application needs to perform queries on the content of a field that holds text you can perform exact matches on the text or use $regex to use regular expression pattern matches. However, for many operations on text, these methods do not satisfy application requirements.

This pattern describes one method for supporting keyword search using MongoDB to support application search functionality, that uses keywords stored in an array in the same document as the text field. Combined with a multi-key index, this pattern can support application’s keyword search operations.

Pattern

To add structures to your document to support keyword-based queries, create an array field in your documents and add the keywords as strings in the array. You can then create a multi-key index on the array and create queries that select values from the array.

Example

Given a collection of library volumes that you want to provide topic-based search. For each volume, you add the array topics, and you add as many keywords as needed for a given volume.

For the Moby-Dick volume you might have the following document:

{ title : "Moby-Dick" ,
  author : "Herman Melville" ,
  published : 1851 ,
  ISBN : 0451526996 ,
  topics : [ "whaling" , "allegory" , "revenge" , "American" ,
    "novel" , "nautical" , "voyage" , "Cape Cod" ]
}

You then create a multi-key index on the topics array:

db.volumes.ensureIndex( { topics: 1 } )

The multi-key index creates separate index entries for each keyword in the topics array. For example the index contains one entry for whaling and another for allegory.

You then query based on the keywords. For example:

db.volumes.findOne( { topics : "voyage" }, { title: 1 } )

Note

An array with a large number of elements, such as one with several hundreds or thousands of keywords will incur greater indexing costs on insertion.

Limitations of Keyword Indexes

MongoDB can support keyword searches using specific data models and multi-key indexes; however, these keyword indexes are not sufficient or comparable to full-text products in the following respects:

Stemming. Keyword queries in MongoDB can not parse keywords for root or related words.

Synonyms. Keyword-based search features must provide support for synonym or related queries in the application layer.

Ranking. The keyword look ups described in this document do not provide a way to weight results.

Asynchronous Indexing. MongoDB builds indexes synchronously, which means that the indexes used for keyword indexes are always current and can operate in real-time. However, asynchronous bulk indexes may be more efficient for some kinds of content and workloads.

Model Monetary Data

Overview

MongoDB stores numeric data as either IEEE 754 standard 64-bit floating point numbers or as 32-bit or 64-bit signed integers. Applications that handle monetary data often require capturing fractional units of currency. However, arithmetic on floating point numbers, as implemented in modern hardware, often does not conform to requirements for monetary arithmetic. In addition, some fractional numeric quantities, such as one third and one tenth, have no exact representation in binary floating point numbers.

Note

Arithmetic mentioned on this page refers to server-side arithmetic performed by mongod or mongos, and not to client-side arithmetic.

This document describes two ways to model monetary data in MongoDB:

Exact Precision which multiplies the monetary value by a power of 10.

Arbitrary Precision which uses two fields for the value: one field to store the exact monetary value as a non-numeric and another field to store a floating point approximation of the value.

Use Cases for Exact Precision Model

If you regularly need to perform server-side arithmetic on monetary data, the exact precision model may be appropriate. For instance:

If you need to query the database for exact, mathematically valid matches, use Exact Precision.

If you need to be able to do server-side arithmetic, e.g., $inc, $mul, and aggregation framework arithmetic, use Exact Precision.

Use Cases for Arbitrary Precision Model

If there is no need to perform server-side arithmetic on monetary data, modeling monetary data using the arbitrary precision model may be suitable. For instance:

If you need to handle arbitrary or unforeseen number of precision, see Arbitrary Precision.

If server-side approximations are sufficient, possibly with client-side post-processing, see Arbitrary Precision.

Exact Precision

To model monetary data using the exact precision model:

Determine the maximum precision needed for the monetary value. For example, your application may require precision down to the tenth of one cent for monetary values in USD currency.

Convert the monetary value into an integer by multiplying the value by a power of 10 that ensures the maximum precision needed becomes the least significant digit of the integer. For example, if the required maximum precision is the tenth of one cent, multiply the monetary value by 1000.

Store the converted monetary value.

For example, the following scales 9.99 USD by 1000 to preserve precision up to one tenth of a cent.

{ price: 9990, currency: "USD" }

The model assumes that for a given currency value:

The scale factor is consistent for a currency; i.e. same scaling factor for a given currency.

The scale factor is a constant and known property of the currency; i.e applications can determine the scale factor from the currency.

When using this model, applications must be consistent in performing the appropriate scaling of the values.

For use cases of this model, see Use Cases for Exact Precision Model.

Arbitrary Precision

To model monetary data using the arbitrary precision model, store the value in two fields:

In one field, encode the exact monetary value as a non-numeric data type; e.g., BinData or a string.

In the second field, store a double-precision floating point approximation of the exact value.

The following example uses the arbitrary precision model to store 9.99 USD for the price and 0.25 USD for the fee:

{
  price: { display: "9.99", approx: 9.9900000000000002, currency: "USD" },
  fee: { display: "0.25", approx: 0.2499999999999999, currency: "USD" }
}

With some care, applications can perform range and sort queries on the field with the numeric approximation. However, the use of the approximation field for the query and sort operations requires that applications perform client-side post-processing to decode the non-numeric representation of the exact value and then filter out the returned documents based on the exact monetary value.

For use cases of this model, see Use Cases for Arbitrary Precision Model.

Model Time Data

Overview

MongoDB stores times in UTC by default, and will convert any local time representations into this form. Applications that must operate or report on some unmodified local time value may store the time zone alongside the UTC timestamp, and compute the original local time in their application logic.

Example

In the MongoDB shell, you can store both the current date and the current client’s offset from UTC.

var now = new Date();
db.data.save( { date: now,
                offset: now.getTimezoneOffset() } );

You can reconstruct the original local time by applying the saved offset:

var record = db.data.findOne();
var localNow = new Date( record.date.getTime() -  ( record.offset * 60000 ) );

Data Model Reference

Documents

MongoDB stores all data in documents, which are JSON-style data structures composed of field-and-value pairs.

Database References

Discusses manual references and DBRefs, which MongoDB can use to represent relationships between documents.

GridFS Reference

Convention for storing large files in a MongoDB Database.

ObjectId

A 12-byte BSON type that MongoDB uses as the default value for its documents’ _id field if the _id field is not specified.

BSON Types

Outlines the unique BSON types used by MongoDB. See BSONspec.org [http://bsonspec.org/] for the complete BSON specification.

Documents

Database References

GridFS Reference

ObjectId

BSON Types

Documents

MongoDB stores all data in documents, which are JSON-style data structures composed of field-and-value pairs:

{ "item": "pencil", "qty": 500, "type": "no.2" }

Most user-accessible data structures in MongoDB are documents, including:

All database records.

Query selectors, which define what records to select for read, update, and delete operations.

Update definitions, which define what fields to modify during an update.

Index specifications, which define what fields to index.

Data output by MongoDB for reporting and configuration, such as the output of the serverStatus and the replica set configuration document.

Document Format

MongoDB stores documents on disk in the BSON serialization format. BSON is a binary representation of JSON documents, though it contains more data types than JSON. For the BSON spec, see bsonspec.org [http://bsonspec.org/]. See also BSON Types.

The mongo JavaScript shell and the MongoDB language drivers translate between BSON and the language-specific document representation.

Document Structure

MongoDB documents are composed of field-and-value pairs and have the following structure:

{
   field1: value1,
   field2: value2,
   field3: value3,
   ...
   fieldN: valueN
}

The value of a field can be any of the BSON data types, including other documents, arrays, and arrays of documents. The following document contains values of varying types:

var mydoc = {
               _id: ObjectId("5099803df3f4948bd2f98391"),
               name: { first: "Alan", last: "Turing" },
               birth: new Date('Jun 23, 1912'),
               death: new Date('Jun 07, 1954'),
               contribs: [ "Turing machine", "Turing test", "Turingery" ],
               views : NumberLong(1250000)
            }

The above fields have the following data types:

_id holds an ObjectId.

name holds an embedded document that contains the fields first and last.

birth and death hold values of the Date type.

contribs holds an array of strings.

views holds a value of the NumberLong type.

Field Names

Field names are strings.

Documents have the following restrictions on field names:

The field name _id is reserved for use as a primary key; its value must be unique in the collection, is immutable, and may be of any type other than an array.

The field names cannot start with the dollar sign ($) character.

The field names cannot contain the dot (.) character.

The field names cannot contain the null character.

BSON documents may have more than one field with the same name. Most MongoDB interfaces, however, represent MongoDB with a structure (e.g. a hash table) that does not support duplicate field names. If you need to manipulate documents that have more than one field with the same name, see the driver documentation for your driver.

Some documents created by internal MongoDB processes may have duplicate fields, but no MongoDB process will ever add duplicate fields to an existing user document.

Field Value Limit

For indexed collections, the values for the indexed fields have a Maximum Index Key Length limit. See Maximum Index Key Length for details.

Document Limitations

Documents have the following attributes:

Document Size Limit

The maximum BSON document size is 16 megabytes.

The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See mongofiles and the documentation for your driver for more information about GridFS.

Document Field Order

MongoDB preserves the order of the document fields following write operations except for the following cases:

The _id field is always the first field in the document.

Updates that include renaming of field names may result in the reordering of fields in the document.

Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.

The _id Field

The _id field has the following behavior and constraints:

By default, MongoDB creates a unique index on the _id field during the creation of a collection.

The _id field is always the first field in the documents. If the server receives a document that does not have the _id field first, then the server will move the field to the beginning.

The _id field may contain values of any BSON data type, other than an array.

Warning

To ensure functioning replication, do not store values that are of the BSON regular expression type in the _id field.

The following are common options for storing values for _id:

Use an ObjectId.

Use a natural unique identifier, if available. This saves space and avoids an additional index.

Generate an auto-incrementing number. See Create an Auto-Incrementing Sequence Field.

Generate a UUID in your application code. For a more efficient storage of the UUID values in the collection and in the _id index, store the UUID as a value of the BSON BinData type.

Index keys that are of the BinData type are more efficiently stored in the index if:

the binary subtype value is in the range of 0-7 or 128-135, and

the length of the byte array is: 0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, or 32.

Use your driver’s BSON UUID facility to generate UUIDs. Be aware that driver implementations may implement UUID serialization and deserialization logic differently, which may not be fully compatible with other drivers. See your driver documentation [http://api.mongodb.org/] for information concerning UUID interoperability.

Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.

Dot Notation

MongoDB uses the dot notation to access the elements of an array and to access the fields of an embedded document.

To access an element of an array by the zero-based index position, concatenate the array name with the dot (.) and zero-based index position, and enclose in quotes:

'<array>.<index>'

See also $ positional operator for update operations and $ projection operator when array index position is unknown.

To access a field of an embedded document with dot-notation, concatenate the embedded document name with the dot (.) and the field name, and enclose in quotes:

'<embedded document>.<field>'

See also

Embedded Documents for dot notation examples with embedded documents.

Arrays for dot notation examples with arrays.

Database References

MongoDB does not support joins. In MongoDB some data is denormalized, or stored with related data in documents to remove the need for joins. However, in some cases it makes sense to store related information in separate documents, typically in different collections or databases.

MongoDB applications use one of two methods for relating documents:

Manual references where you save the _id field of one document in another document as a reference. Then your application can run a second query to return the related data. These references are simple and sufficient for most use cases.

DBRefs are references from one document to another using the value of the first document’s _id field, collection name, and, optionally, its database name. By including these names, DBRefs allow documents located in multiple collections to be more easily linked with documents from a single collection.

To resolve DBRefs, your application must perform additional queries to return the referenced documents. Many drivers have helper methods that form the query for the DBRef automatically. The drivers [1] do not automatically resolve DBRefs into documents.

DBRefs provide a common format and type to represent relationships among documents. The DBRef format also provides common semantics for representing links between documents if your database must interact with multiple frameworks and tools.

Unless you have a compelling reason to use DBRefs, use manual references instead.

[1]
Some community supported drivers may have alternate behavior and may resolve a DBRef into a document automatically.

Manual References

Background

Using manual references is the practice of including one document’s _id field in another document. The application can then issue a second query to resolve the referenced fields as needed.

Process

Consider the following operation to insert two documents, using the _id field of the first document as a reference in the second document:

original_id = ObjectId()

db.places.insert({
    "_id": original_id,
    "name": "Broadway Center",
    "url": "bc.example.net"
})

db.people.insert({
    "name": "Erin",
    "places_id": original_id,
    "url":  "bc.example.net/Erin"
})

Then, when a query returns the document from the people collection you can, if needed, make a second query for the document referenced by the places_id field in the places collection.

Use

For nearly every case where you want to store a relationship between two documents, use manual references. The references are simple to create and your application can resolve references as needed.

The only limitation of manual linking is that these references do not convey the database and collection names. If you have documents in a single collection that relate to documents in more than one collection, you may need to consider using DBRefs.

DBRefs

Background

DBRefs are a convention for representing a document, rather than a specific reference type. They include the name of the collection, and in some cases the database name, in addition to the value from the _id field.

Format

DBRefs have the following fields:

$ref

The $ref field holds the name of the collection where the referenced document resides.

$id

The $id field contains the value of the _id field in the referenced document.

$db

Optional.

Contains the name of the database where the referenced document resides.

Only some drivers support $db references.

Example

DBRef documents resemble the following document:

{ "$ref" : <value>, "$id" : <value>, "$db" : <value> }

Consider a document from a collection that stored a DBRef in a creator field:

{
  "_id" : ObjectId("5126bbf64aed4daf9e2ab771"),
  // .. application fields
  "creator" : {
                  "$ref" : "creators",
                  "$id" : ObjectId("5126bc054aed4daf9e2ab772"),
                  "$db" : "users"
               }
}

The DBRef in this example points to a document in the creators collection of the users database that has ObjectId("5126bc054aed4daf9e2ab772") in its _id field.

Note

The order of fields in the DBRef matters, and you must use the above sequence when using a DBRef.

Driver Support for DBRefs

C

The C driver contains no support for DBRefs. You can traverse references manually.

C++

The C++ driver contains no support for DBRefs. You can traverse references manually.

C#

The C# driver supports DBRefs using the MongoDBRef [http://api.mongodb.org/csharp/current/html/46c356d3-ed06-a6f8-42fa-e0909ab64ce2.htm] class and the FetchDBRef [http://api.mongodb.org/csharp/current/html/1b0b8f48-ba98-1367-0a7d-6e01c8df436f.htm] method.

Haskell

The Haskell driver contains no support for DBRefs. You can traverse references manually.

Java

The DBRef [http://api.mongodb.org/java/current/com/mongodb/DBRef.html] class provides support for DBRefs from Java.

JavaScript

The mongo shell’s JavaScript interface provides a DBRef.

Node.js

The Node.js driver supports DBRefs using the DBRef [http://mongodb.github.io/node-mongodb-native/api-bson-generated/db_ref.html] class and the dereference [http://mongodb.github.io/node-mongodb-native/api-generated/db.html#dereference] method.

Perl

The Perl driver contains no support for DBRefs. You can traverse references manually or use the MongoDBx::AutoDeref [http://search.cpan.org/dist/MongoDBx-AutoDeref/] CPAN module.

PHP

The PHP driver supports DBRefs, including the optional $db reference, using the MongoDBRef [http://www.php.net/manual/en/class.mongodbref.php/] class.

Python

The Python driver supports DBRefs using the DBRef [http://api.mongodb.org/python/current/api/bson/dbref.html] class and the dereference [http://api.mongodb.org//python/current/api/pymongo/database.html#pymongo.database.Database.dereference] method.

Ruby

The Ruby driver supports DBRefs using the DBRef [http://api.mongodb.org//ruby/current/BSON/DBRef.html] class and the dereference [http://api.mongodb.org//ruby/current/Mongo/DB.html#dereference-instance_method] method.

Scala

The Scala driver contains no support for DBRefs. You can traverse references manually.

Use

In most cases you should use the manual reference method for connecting two or more related documents. However, if you need to reference documents from multiple collections, consider using DBRefs.

GridFS Reference

GridFS stores files in two collections:

chunks stores the binary chunks. For details, see The chunks Collection.

files stores the file’s metadata. For details, see The files Collection.

GridFS places the collections in a common bucket by prefixing each with the bucket name. By default, GridFS uses two collections with names prefixed by fs bucket:

fs.files

fs.chunks

You can choose a different bucket name than fs, and create multiple buckets in a single database.

See also

GridFS for more information about GridFS.

The chunks Collection

Each document in the chunks collection represents a distinct chunk of a file as represented in the GridFS store. The following is a prototype document from the chunks collection.:

{
  "_id" : <ObjectId>,
  "files_id" : <ObjectId>,
  "n" : <num>,
  "data" : <binary>
}

A document from the chunks collection contains the following fields:

chunks._id

The unique ObjectId of the chunk.

chunks.files_id

The _id of the “parent” document, as specified in the files collection.

chunks.n

The sequence number of the chunk. GridFS numbers all chunks, starting with 0.

chunks.data

The chunk’s payload as a BSON binary type.

The chunks collection uses a compound index on files_id and n, as described in GridFS Index.

The files Collection

Each document in the files collection represents a file in the GridFS store. Consider the following prototype of a document in the files collection:

{
  "_id" : <ObjectId>,
  "length" : <num>,
  "chunkSize" : <num>,
  "uploadDate" : <timestamp>,
  "md5" : <hash>,

  "filename" : <string>,
  "contentType" : <string>,
  "aliases" : <string array>,
  "metadata" : <dataObject>,
}

Documents in the files collection contain some or all of the following fields. Applications may create additional arbitrary fields:

files._id

The unique ID for this document. The _id is of the data type you chose for the original document. The default type for MongoDB documents is BSON ObjectId.

files.length

The size of the document in bytes.

files.chunkSize

The size of each chunk. GridFS divides the document into chunks of the size specified here. The default size is 255 kilobytes.

Changed in version 2.4.10: The default chunk size changed from 256k to 255k.

files.uploadDate

The date the document was first stored by GridFS. This value has the Date type.

files.md5

An MD5 hash returned by the filemd5 command. This value has the String type.

files.filename

Optional. A human-readable name for the document.

files.contentType

Optional. A valid MIME type for the document.

files.aliases

Optional. An array of alias strings.

files.metadata

Optional. Any additional information you want to store.

ObjectId

Overview

ObjectId is a 12-byte BSON type, constructed using:

a 4-byte value representing the seconds since the Unix epoch,

a 3-byte machine identifier,

a 2-byte process id, and

a 3-byte counter, starting with a random value.

In MongoDB, documents stored in a collection require a unique _id field that acts as a primary key. Because ObjectIds are small, most likely unique, and fast to generate, MongoDB uses ObjectIds as the default value for the _id field if the _id field is not specified. MongoDB clients should add an _id field with a unique ObjectId. However, if a client does not add an _id field, mongod will add an _id field that holds an ObjectId.

Using ObjectIds for the _id field provides the following additional benefits:

in the mongo shell, you can access the creation time of the ObjectId, using the getTimestamp() method.

sorting on an _id field that stores ObjectId values is roughly equivalent to sorting by creation time.

Important

The relationship between the order of ObjectId values and generation time is not strict within a single second. If multiple systems, or multiple processes or threads on a single system generate values, within a single second; ObjectId values do not represent a strict insertion order. Clock skew between clients can also result in non-strict ordering even for values, because client drivers generate ObjectId values, not the mongod process.

Also consider the Documents section for related information on MongoDB’s document orientation.

ObjectId()

The mongo shell provides the ObjectId() wrapper class to generate a new ObjectId, and to provide the following helper attribute and methods:

str

The hexadecimal string representation of the object.

getTimestamp()

Returns the timestamp portion of the object as a Date.

toString()

Returns the JavaScript representation in the form of a string literal “ObjectId(...)”.

Changed in version 2.2: In previous versions toString() returns the hexadecimal string representation, which as of version 2.2 can be retrieved by the str property.

valueOf()

Returns the representation of the object as a hexadecimal string. The returned string is the str attribute.

Changed in version 2.2: In previous versions, valueOf() returns the object.

Examples

Consider the following uses ObjectId() class in the mongo shell:

Generate a new ObjectId

To generate a new ObjectId, use the ObjectId() constructor with no argument:

x = ObjectId()

In this example, the value of x would be:

ObjectId("507f1f77bcf86cd799439011")

To generate a new ObjectId using the ObjectId() constructor with a unique hexadecimal string:

y = ObjectId("507f191e810c19729de860ea")

In this example, the value of y would be:

ObjectId("507f191e810c19729de860ea")

To return the timestamp of an ObjectId() object, use the getTimestamp() method as follows:

Convert an ObjectId into a Timestamp

To return the timestamp of an ObjectId() object, use the getTimestamp() method as follows:

ObjectId("507f191e810c19729de860ea").getTimestamp()

This operation will return the following Date object:

ISODate("2012-10-17T20:46:22Z")

Convert ObjectIds into Strings

Access the str attribute of an ObjectId() object, as follows:

ObjectId("507f191e810c19729de860ea").str

This operation will return the following hexadecimal string:

507f191e810c19729de860ea

To return the hexadecimal string representation of an ObjectId(), use the valueOf() method as follows:

ObjectId("507f191e810c19729de860ea").valueOf()

This operation returns the following output:

507f191e810c19729de860ea

To return the string representation of an ObjectId() object, use the toString() method as follows:

ObjectId("507f191e810c19729de860ea").toString()

This operation will return the following output:

ObjectId("507f191e810c19729de860ea")

BSON Types

BSON is a binary serialization format used to store documents and make remote procedure calls in MongoDB. The BSON specification is located at bsonspec.org [http://bsonspec.org/].

BSON supports the following data types as values in documents. Each data type has a corresponding number that can be used with the $type operator to query documents by BSON type.

Type | Number | Notes
Double | 1 |
String | 2 |
Object | 3 |
Array | 4 |
Binary data | 5 |
Undefined | 6 | Deprecated.
Object id | 7 |
Boolean | 8 |
Date | 9 |
Null | 10 |
Regular Expression | 11 |
JavaScript | 13 |
Symbol | 14 |
JavaScript (with scope) | 15 |
32-bit integer | 16 |
Timestamp | 17 |
64-bit integer | 18 |
Min key | 255 | Query with -1.
Max key | 127 |

To determine a field’s type, see Check Types in the mongo Shell.

If you convert BSON to JSON, see the Extended JSON reference.

Comparison/Sort Order

When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:

MinKey (internal type)

Null

Numbers (ints, longs, doubles)

Symbol, String

Object

Array

BinData

ObjectId

Boolean

Date, Timestamp

Regular Expression

MaxKey (internal type)

MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.

The comparison treats a non-existent field as it would an empty BSON Object. As such, a sort on the a field in documents { } and { a: null } would treat the documents as equivalent in sort order.

With arrays, a less-than comparison or an ascending sort compares the smallest element of arrays, and a greater-than comparison or a descending sort compares the largest element of the arrays. As such, when comparing a field whose value is a single-element array (e.g. [ 1 ]) with non-array fields (e.g. 2), the comparison is between 1 and 2. A comparison of an empty array (e.g. [ ]) treats the empty array as less than null or a missing field.

MongoDB sorts BinData in the following order:

First, the length or size of the data.

Then, by the BSON one-byte subtype.

Finally, by the data, performing a byte-by-byte comparison.

The following sections describe special considerations for particular BSON types.

ObjectId

ObjectIds are: small, likely unique, fast to generate, and ordered. These values consists of 12-bytes, where the first four bytes are a timestamp that reflect the ObjectId’s creation. Refer to the ObjectId documentation for more information.

String

BSON strings are UTF-8. In general, drivers for each programming language convert from the language’s string format to UTF-8 when serializing and deserializing BSON. This makes it possible to store most international characters in BSON strings with ease. [1] In addition, MongoDB $regex queries support UTF-8 in the regex string.

[1]
Given strings using UTF-8 character sets, using sort() on strings will be reasonably correct. However, because internally sort() uses the C++ strcmp api, the sort order may handle some characters incorrectly.

Timestamps

BSON has a special timestamp type for internal MongoDB use and is not associated with the regular Date type. Timestamp values are a 64 bit value where:

the first 32 bits are a time_t value (seconds since the Unix epoch)

the second 32 bits are an incrementing ordinal for operations within a given second.

Within a single mongod instance, timestamp values are always unique.

In replication, the oplog has a ts field. The values in this field reflect the operation time, which uses a BSON timestamp value.

Note

The BSON timestamp type is for internal MongoDB use. For most cases, in application development, you will want to use the BSON date type. See Date for more information.

If you insert a document containing an empty BSON timestamp in a top-level field, the MongoDB server will replace that empty timestamp with the current timestamp value. For example, if you create an insert a document with a timestamp value, as in the following operation:

var a = new Timestamp();

db.test.insert( { ts: a } );

Then, the db.test.find() operation will return a document that resembles the following:

{ "_id" : ObjectId("542c2b97bac0595474108b48"), "ts" : Timestamp(1412180887, 1) }

If ts were a field in an embedded document, the server would have left it as an empty timestamp value.

Changed in version 2.6: Previously, the server would only replace empty timestamp values in the first two fields, including _id, of an inserted document. Now MongoDB will replace any top-level field.

Date

BSON Date is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). This results in a representable date range of about 290 million years into the past and future.

The official BSON specification [http://bsonspec.org/#/specification] refers to the BSON Date type as the UTC datetime.

Changed in version 2.0: BSON Date type is signed. [2] Negative values represent dates before 1970.

Example

Construct a Date using the new Date() constructor in the mongo shell:

var mydate1 = new Date()

Example

Construct a Date using the ISODate() constructor in the mongo shell:

var mydate2 = ISODate()

Example

Return the Date value as string:

mydate1.toString()

Example

Return the month portion of the Date value; months are zero-indexed, so that January is month 0:

mydate1.getMonth()

[2]
Prior to version 2.0, Date values were incorrectly interpreted as unsigned integers, which affected sorts, range queries, and indexes on Date fields. Because indexes are not recreated when upgrading, please re-index if you created an index on Date values with an earlier version, and dates before 1970 are relevant to your application.

Administration

The administration documentation addresses the ongoing operation and maintenance of MongoDB instances and deployments. This documentation includes both high level overviews of these concerns as well as tutorials that cover specific procedures and processes for operating MongoDB.

Administration Concepts

Core conceptual documentation of operational practices for managing MongoDB deployments and systems.

MongoDB Backup Methods

Describes approaches and considerations for backing up a MongoDB database.

Monitoring for MongoDB

An overview of monitoring tools, diagnostic strategies, and approaches to monitoring replica sets and sharded clusters.

Production Notes

A collection of notes that describe best practices and considerations for the operations of MongoDB instances and deployments.

Continue reading from Administration Concepts for additional documentation of MongoDB administration.

Administration Tutorials

Tutorials that describe common administrative procedures and practices for operations for MongoDB instances and deployments.

Configuration, Maintenance, and Analysis

Describes routine management operations, including configuration and performance analysis.

Backup and Recovery

Outlines procedures for data backup and restoration with mongod instances and deployments.

Continue reading from Administration Tutorials for more tutorials of common MongoDB maintenance operations.

Administration Reference

Reference and documentation of internal mechanics of administrative features, systems and functions and operations.

See also

The MongoDB Manual contains administrative documentation and tutorials though out several sections. See Replica Set Tutorials and Sharded Cluster Tutorials for additional tutorials and information.

Administration Concepts

Operational Strategies

MongoDB Backup Methods

Monitoring for MongoDB

Run-time Database Configuration

Import and Export MongoDB Data

Production Notes

Data Management

Data Center Awareness

Operational Segregation in MongoDB Deployments

Capped Collections

Expire Data from Collections by Setting TTL

Optimization Strategies for MongoDB

Evaluate Performance of Current Operations

Use Capped Collections for Fast Writes and Reads

Optimize Query Performance

Design Notes

Administration Tutorials

Configuration, Maintenance, and Analysis

Use Database Commands

Manage mongod Processes

Terminate Running Operations

Analyze Performance of Database Operations

Rotate Log Files

Manage Journaling

Store a JavaScript Function on the Server

Upgrade to the Latest Revision of MongoDB

Monitor MongoDB With SNMP on Linux

Monitor MongoDB Windows with SNMP

Troubleshoot SNMP

Backup and Recovery

Backup and Restore with Filesystem Snapshots

Restore a Replica Set from MongoDB Backups

Back Up and Restore with MongoDB Tools

Backup and Restore Sharded Clusters

Backup a Small Sharded Cluster with mongodump

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Schedule Backup Window for Sharded Clusters

Restore a Single Shard

Restore a Sharded Cluster

Recover Data after an Unexpected Shutdown

MongoDB Scripting

Server-side JavaScript

Data Types in the mongo Shell

Write Scripts for the mongo Shell

Getting Started with the mongo Shell

Access the mongo Shell Help Information

mongo Shell Quick Reference

MongoDB Tutorials

Administration Reference

UNIX ulimit Settings

System Collections

Database Profiler Output

Journaling Mechanics

Exit Codes and Statuses

Administration Concepts

The core administration documents address strategies and practices used in the operation of MongoDB systems and deployments.

Operational Strategies

Higher level documentation of key concepts for the operation and maintenance of MongoDB deployments, including backup, maintenance, and configuration.

MongoDB Backup Methods

Describes approaches and considerations for backing up a MongoDB database.

Monitoring for MongoDB

An overview of monitoring tools, diagnostic strategies, and approaches to monitoring replica sets and sharded clusters.

Run-time Database Configuration

Outlines common MongoDB configurations and examples of best-practice configurations for common use cases.

Data Management

Core documentation that addresses issues in data management, organization, maintenance, and lifestyle management.

Data Center Awareness

Presents the MongoDB features that allow application developers and database administrators to configure their deployments to be more data center aware or allow operational and location-based separation.

Expire Data from Collections by Setting TTL

TTL collections make it possible to automatically remove data from a collection based on the value of a timestamp and are useful for managing data like machine generated event data that are only useful for a limited period of time.

Capped Collections

Capped collections provide a special type of size-constrained collections that preserve insertion order and can support high volume inserts.

Optimization Strategies for MongoDB

Techniques for optimizing application performance with MongoDB.

Operational Strategies

MongoDB Backup Methods

Monitoring for MongoDB

Run-time Database Configuration

Import and Export MongoDB Data

Production Notes

Data Management

Data Center Awareness

Operational Segregation in MongoDB Deployments

Capped Collections

Expire Data from Collections by Setting TTL

Optimization Strategies for MongoDB

Evaluate Performance of Current Operations

Use Capped Collections for Fast Writes and Reads

Optimize Query Performance

Design Notes

Operational Strategies

These documents address higher level strategies for common administrative tasks and requirements with respect to MongoDB deployments.

MongoDB Backup Methods

Describes approaches and considerations for backing up a MongoDB database.

Monitoring for MongoDB

An overview of monitoring tools, diagnostic strategies, and approaches to monitoring replica sets and sharded clusters.

Run-time Database Configuration

Outlines common MongoDB configurations and examples of best-practice configurations for common use cases.

Import and Export MongoDB Data

Provides an overview of mongoimport and mongoexport, the tools MongoDB includes for importing and exporting data.

Production Notes

A collection of notes that describe best practices and considerations for the operations of MongoDB instances and deployments.

MongoDB Backup Methods

Monitoring for MongoDB

Run-time Database Configuration

Import and Export MongoDB Data

Production Notes

MongoDB Backup Methods

When deploying MongoDB in production, you should have a strategy for capturing and restoring backups in the case of data loss events. There are several ways to back up MongoDB clusters:

Backup by Copying Underlying Data Files

Backup with mongodump

MongoDB Management Service (MMS) Cloud Backup

MongoDB Management Service (MMS) On Prem Backup Software

Backup by Copying Underlying Data Files

You can create a backup by copying MongoDB’s underlying data files.

If the volume where MongoDB stores data files supports point in time snapshots, you can use these snapshots to create backups of a MongoDB system at an exact moment in time.

File systems snapshots are an operating system volume manager feature, and are not specific to MongoDB. The mechanics of snapshots depend on the underlying storage system. For example, if you use Amazon’s EBS storage system for EC2 supports snapshots. On Linux the LVM manager can create a snapshot.

To get a correct snapshot of a running mongod process, you must have journaling enabled and the journal must reside on the same logical volume as the other MongoDB data files. Without journaling enabled, there is no guarantee that the snapshot will be consistent or valid.

To get a consistent snapshot of a sharded system, you must disable the balancer and capture a snapshot from every shard and a config server at approximately the same moment in time.

If your storage system does not support snapshots, you can copy the files directly using cp, rsync, or a similar tool. Since copying multiple files is not an atomic operation, you must stop all writes to the mongod before copying the files. Otherwise, you will copy the files in an invalid state.

Backups produced by copying the underlying data do not support point in time recovery for replica sets and are difficult to manage for larger sharded clusters. Additionally, these backups are larger because they include the indexes and duplicate underlying storage padding and fragmentation. mongodump, by contrast, creates smaller backups.

For more information, see the Backup and Restore with Filesystem Snapshots and Backup a Sharded Cluster with Filesystem Snapshots for complete instructions on using LVM to create snapshots. Also see Back up and Restore Processes for MongoDB on Amazon EC2 [http://docs.mongodb.org/ecosystem/tutorial/backup-and-restore-mongodb-on-amazon-ec2].

Backup with mongodump

The mongodump tool reads data from a MongoDB database and creates high fidelity BSON files. The mongorestore tool can populate a MongoDB database with the data from these BSON files. These tools are simple and efficient for backing up small MongoDB deployments, but are not ideal for capturing backups of larger systems.

mongodump and mongorestore can operate against a running mongod process, and can manipulate the underlying data files directly. By default, mongodump does not capture the contents of the local database.

mongodump only captures the documents in the database. The resulting backup is space efficient, but mongorestore or mongod must rebuild the indexes after restoring data.

When connected to a MongoDB instance, mongodump can adversely affect mongod performance. If your data is larger than system memory, the queries will push the working set out of memory.

To mitigate the impact of mongodump on the performance of the replica set, use mongodump to capture backups from a secondary member of a replica set. Alternatively, you can shut down a secondary and use mongodump with the data files directly. If you shut down a secondary to capture data with mongodump ensure that the operation can complete before its oplog becomes too stale to continue replicating.

For replica sets, mongodump also supports a point in time feature with the --oplog option. Applications may continue modifying data while mongodump captures the output. To restore a point in time backup created with --oplog, use mongorestore with the --oplogReplay option.

If applications modify data while mongodump is creating a backup, mongodump will compete for resources with those applications.

See Back Up and Restore with MongoDB Tools, Backup a Small Sharded Cluster with mongodump, and Backup a Sharded Cluster with Database Dumps for more information.

MongoDB Management Service (MMS) Cloud Backup

The MongoDB Management Service [https://mms.mongodb.com/] supports the backing up and restoring of MongoDB deployments.

MMS continually backs up MongoDB replica sets and sharded clusters by reading the oplog data from your MongoDB deployment.

MMS Backup offers point in time recovery of MongoDB replica sets and a consistent snapshot of sharded clusters.

MMS achieves point in time recovery by storing oplog data so that it can create a restore for any moment in time in the last 24 hours for a particular replica set or sharded cluster. Sharded cluster snapshots are difficult to achieve with other MongoDB backup methods.

To restore a MongoDB deployment from an MMS Backup snapshot, you download a compressed archive of your MongoDB data files and distribute those files before restarting the mongod processes.

To get started with MMS Backup sign up for MMS [https://mms.mongodb.com/], and consider the complete documentation of MMS see the MMS Manual [https://docs.mms.mongodb.com/].

MongoDB Management Service (MMS) On Prem Backup Software

MongoDB Subscribers can install and run the same core software that powers MongoDB Management Service (MMS) Cloud Backup on their own infrastructure. The On Prem version of MMS, has similar functionality as the cloud version and is available with Standard and Enterprise subscriptions.

For more information about On Prem MMS see the MongoDB subscription [https://www.mongodb.com/products/subscriptions] page and the MMS On Prem Manual [https://mms.mongodb.com/help-hosted/current/].

Further Reading

Backup and Restore with Filesystem Snapshots

An outline of procedures for creating MongoDB data set backups using system-level file snapshot tool, such as LVM or native storage appliance tools.

Restore a Replica Set from MongoDB Backups

Describes procedure for restoring a replica set from an archived backup such as a mongodump or MMS [https://mms.mongodb.com/] Backup file.

Back Up and Restore with MongoDB Tools

The procedure for writing the contents of a database to a BSON (i.e. binary) dump file for backing up MongoDB databases.

Backup and Restore Sharded Clusters

Detailed procedures and considerations for backing up sharded clusters and single shards.

Recover Data after an Unexpected Shutdown

Recover data from MongoDB data files that were not properly closed or have an invalid state.

Additional Resources

Backup and it’s Role in Disaster Recovery White Paper [https://www.mongodb.com/lp/white-paper/backup-disaster-recovery]

Backup vs. Replication: Why Do You Need Both? [http://www.mongodb.com/blog/post/backup-vs-replication-why-do-you-need-both]

Monitoring for MongoDB

Monitoring is a critical component of all database administration. A firm grasp of MongoDB’s reporting will allow you to assess the state of your database and maintain your deployment without crisis. Additionally, a sense of MongoDB’s normal operational parameters will allow you to diagnose before they escalate to failures.

This document presents an overview of the available monitoring utilities and the reporting statistics available in MongoDB. It also introduces diagnostic strategies and suggestions for monitoring replica sets and sharded clusters.

Note

MongoDB Management Service (MMS) [https://mms.mongodb.com/] is a hosted service that provides monitoring, backup, and automated deployment of MongoDB instances. See the MMS Website [https://mms.mongodb.com/] and the MMS documentation [https://docs.mms.mongodb.com/] for more information.

Monitoring Strategies

There are three methods for collecting data about the state of a running MongoDB instance:

First, there is a set of utilities distributed with MongoDB that provides real-time reporting of database activities.

Second, database commands return statistics regarding the current database state with greater fidelity.

Third, MMS Monitoring [https://mms.mongodb.com/] collects data from running MongoDB deployments and provides visualization and alerts based on that data.

Each strategy can help answer different questions and is useful in different contexts. These methods are complementary.

MongoDB Reporting Tools

This section provides an overview of the reporting methods distributed with MongoDB. It also offers examples of the kinds of questions that each method is best suited to help you address.

Utilities

The MongoDB distribution includes a number of utilities that quickly return statistics about instances’ performance and activity. Typically, these are most useful for diagnosing issues and assessing normal operation.

mongostat

mongostat captures and returns the counts of database operations by type (e.g. insert, query, update, delete, etc.). These counts report on the load distribution on the server.

Use mongostat to understand the distribution of operation types and to inform capacity planning. See the mongostat manual for details.

mongotop

mongotop tracks and reports the current read and write activity of a MongoDB instance, and reports these statistics on a per collection basis.

Use mongotop to check if your database activity and use match your expectations. See the mongotop manual for details.

HTTP Console

MongoDB provides a web interface that exposes diagnostic and monitoring information in a simple web page. The web interface is accessible at localhost:<port>, where the <port> number is 1000 more than the mongod port .

For example, if a locally running mongod is using the default port 27017, access the HTTP console at http://localhost:28017.

Commands

MongoDB includes a number of commands that report on the state of the database.

These data may provide a finer level of granularity than the utilities discussed above. Consider using their output in scripts and programs to develop custom alerts, or to modify the behavior of your application in response to the activity of your instance. The db.currentOp method is another useful tool for identifying the database instance’s in-progress operations.

serverStatus

The serverStatus command, or db.serverStatus() from the shell, returns a general overview of the status of the database, detailing disk usage, memory use, connection, journaling, and index access. The command returns quickly and does not impact MongoDB performance.

serverStatus outputs an account of the state of a MongoDB instance. This command is rarely run directly. In most cases, the data is more meaningful when aggregated, as one would see with monitoring tools including MMS [https://mms.mongodb.com/]. Nevertheless, all administrators should be familiar with the data provided by serverStatus.

dbStats

The dbStats command, or db.stats() from the shell, returns a document that addresses storage use and data volumes. The dbStats reflect the amount of storage used, the quantity of data contained in the database, and object, collection, and index counters.

Use this data to monitor the state and storage capacity of a specific database. This output also allows you to compare use between databases and to determine the average document size in a database.

collStats

The collStats or db.collection.stats() from the shell that provides statistics that resemble dbStats on the collection level, including a count of the objects in the collection, the size of the collection, the amount of disk space used by the collection, and information about its indexes.

replSetGetStatus

The replSetGetStatus command (rs.status() from the shell) returns an overview of your replica set’s status. The replSetGetStatus document details the state and configuration of the replica set and statistics about its members.

Use this data to ensure that replication is properly configured, and to check the connections between the current host and the other members of the replica set.

Third Party Tools

A number of third party monitoring tools have support for MongoDB, either directly, or through their own plugins.

Self Hosted Monitoring Tools

These are monitoring tools that you must install, configure and maintain on your own servers. Most are open source.

Tool | Plugin | Description
Ganglia [http://sourceforge.net/apps/trac/ganglia/wiki] | mongodb-ganglia [https://github.com/quiiver/mongodb-ganglia] | Python script to report operations per second, memory usage, btree statistics, master/slave status and current connections.
Ganglia | gmond_python_modules [https://github.com/ganglia/gmond_python_modules] | Parses output from the serverStatus and replSetGetStatus commands.
Motop [https://github.com/tart/motop] | None | Realtime monitoring tool for MongoDB servers. Shows current operations ordered by durations every second.
mtop [https://github.com/beaufour/mtop] | None | A top like tool.
Munin [http://munin-monitoring.org/] | mongo-munin [https://github.com/erh/mongo-munin] | Retrieves server statistics.
Munin | mongomon [https://github.com/pcdummy/mongomon] | Retrieves collection statistics (sizes, index sizes, and each (configured) collection count for one DB).
Munin | munin-plugins Ubuntu PPA [https://launchpad.net/~chris-lea/+archive/munin-plugins] | Some additional munin plugins not in the main distribution.
Nagios [http://www.nagios.org/] | nagios-plugin-mongodb [https://github.com/mzupan/nagios-plugin-mongodb] | A simple Nagios check script, written in Python.
Zabbix [http://www.zabbix.com/] | mikoomi-mongodb [https://code.google.com/p/mikoomi/wiki/03] | Monitors availability, resource utilization, health, performance and other important metrics.

Also consider dex [https://github.com/mongolab/dex], an index and query analyzing tool for MongoDB that compares MongoDB log files and indexes to make indexing recommendations.

As part of MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise], you can run MMS On-Prem [https://mms.mongodb.com/], which offers the features of MMS in a package that runs within your own infrastructure.

Hosted (SaaS) Monitoring Tools

These are monitoring tools provided as a hosted service, usually through a paid subscription.

Name | Notes
MongoDB Management Service :mms-home:</> | MMS is a cloud-based suite of services for managing MongoDB deployments. MMS provides monitoring, backup, and automation functionality.
Scout [http://scoutapp.com] | Several plugins, including MongoDB Monitoring [https://scoutapp.com/plugin_urls/391-mongodb-monitoring], MongoDB Slow Queries [http://scoutapp.com/plugin_urls/291-mongodb-slow-queries], and MongoDB Replica Set Monitoring [http://scoutapp.com/plugin_urls/2251-mongodb-replica-set-monitoring].
Server Density [http://www.serverdensity.com] | Dashboard for MongoDB [http://www.serverdensity.com/mongodb-monitoring/], MongoDB specific alerts, replication failover timeline and iPhone, iPad and Android mobile apps.
Application Performance Management [http://ibmserviceengage.com] | IBM has an Application Performance Management SaaS offering that includes monitor for MongoDB and other applications and middleware.

Process Logging

During normal operation, mongod and mongos instances report a live account of all server activity and operations to either standard output or a log file. The following runtime settings control these options.

quiet. Limits the amount of information written to the log or output.

verbosity. Increases the amount of information written to the log or output. You can also modify the logging verbosity during runtime with the logLevel parameter or the db.setLogLevel() method in the shell.

path. Enables logging to a file, rather than the standard output. You must specify the full path to the log file when adjusting this setting.

logAppend. Adds information to a log file instead of overwriting the file.

Note

You can specify these configuration operations as the command line arguments to mongod or mongos

For example:

mongod -v --logpath /var/log/mongodb/server1.log --logappend

Starts a mongod instance in verbose mode, appending data to the log file at /var/log/mongodb/server1.log/.

The following database commands also affect logging:

getLog. Displays recent messages from the mongod process log.

logRotate. Rotates the log files for mongod processes only. See Rotate Log Files.

Diagnosing Performance Issues

Degraded performance in MongoDB is typically a function of the relationship between the quantity of data stored in the database, the amount of system RAM, the number of connections to the database, and the amount of time the database spends in a locked state.

In some cases performance issues may be transient and related to traffic load, data access patterns, or the availability of hardware on the host system for virtualized environments. Some users also experience performance limitations as a result of inadequate or inappropriate indexing strategies, or as a consequence of poor schema design patterns. In other situations, performance issues may indicate that the database may be operating at capacity and that it is time to add additional capacity to the database.

The following are some causes of degraded performance in MongoDB.

Locks

MongoDB uses a locking system to ensure data set consistency. However, if certain operations are long-running, or a queue forms, performance will slow as requests and operations wait for the lock. Lock-related slowdowns can be intermittent. To see if the lock has been affecting your performance, look to the data in the globalLock section of the serverStatus output. If globalLock.currentQueue.total is consistently high, then there is a chance that a large number of requests are waiting for a lock. This indicates a possible concurrency issue that may be affecting performance.

If globalLock.totalTime is high relative to uptime, the database has existed in a lock state for a significant amount of time. If globalLock.ratio is also high, MongoDB has likely been processing a large number of long running queries. Long queries are often the result of a number of factors: ineffective use of indexes, non-optimal schema design, poor query structure, system architecture issues, or insufficient RAM resulting in page faults and disk reads.

Memory Usage

MongoDB uses memory mapped files to store data. Given a data set of sufficient size, the MongoDB process will allocate all available memory on the system for its use. While this is part of the design, and affords MongoDB superior performance, the memory mapped files make it difficult to determine if the amount of RAM is sufficient for the data set.

The memory usage statuses metrics of the serverStatus output can provide insight into MongoDB’s memory use. Check the resident memory use (i.e. mem.resident): if this exceeds the amount of system memory and there is a significant amount of data on disk that isn’t in RAM, you may have exceeded the capacity of your system.

You should also check the amount of mapped memory (i.e. mem.mapped.) If this value is greater than the amount of system memory, some operations will require disk access page faults to read data from virtual memory and negatively affect performance.

Page Faults

Page faults can occur as MongoDB reads from or writes data to parts of its data files that are not currently located in physical memory. In contrast, operating system page faults happen when physical memory is exhausted and pages of physical memory are swapped to disk.

Page faults triggered by MongoDB are reported as the total number of page faults in one second. To check for page faults, see the extra_info.page_faults value in the serverStatus output.

MongoDB on Windows counts both hard and soft page faults.

The MongoDB page fault counter may increase dramatically in moments of poor performance and may correlate with limited physical memory environments. Page faults also can increase while accessing much larger data sets, for example, scanning an entire collection. Limited and sporadic MongoDB page faults do not necessarily indicate a problem or a need to tune the database.

A single page fault completes quickly and is not problematic. However, in aggregate, large volumes of page faults typically indicate that MongoDB is reading too much data from disk. In many situations, MongoDB’s read locks will “yield” after a page fault to allow other processes to read and avoid blocking while waiting for the next page to read into memory. This approach improves concurrency, and also improves overall throughput in high volume systems.

Increasing the amount of RAM accessible to MongoDB may help reduce the frequency of page faults. If this is not possible, you may want to consider deploying a sharded cluster or adding shards to your deployment to distribute load among mongod instances.

See What are page faults? for more information.

Number of Connections

In some cases, the number of connections between the application layer (i.e. clients) and the database can overwhelm the ability of the server to handle requests. This can produce performance irregularities. The following fields in the serverStatus document can provide insight:

globalLock.activeClients contains a counter of the total number of clients with active operations in progress or queued.

connections is a container for the following two fields:

current the total number of current clients that connect to the database instance.

available the total number of unused collections available for new clients.

If requests are high because there are numerous concurrent application requests, the database may have trouble keeping up with demand. If this is the case, then you will need to increase the capacity of your deployment. For read-heavy applications increase the size of your replica set and distribute read operations to secondary members. For write heavy applications, deploy sharding and add one or more shards to a sharded cluster to distribute load among mongod instances.

Spikes in the number of connections can also be the result of application or driver errors. All of the officially supported MongoDB drivers implement connection pooling, which allows clients to use and reuse connections more efficiently. Extremely high numbers of connections, particularly without corresponding workload is often indicative of a driver or other configuration error.

Unless constrained by system-wide limits MongoDB has no limit on incoming connections. You can modify system limits using the ulimit command, or by editing your system’s /etc/sysctl file. See UNIX ulimit Settings for more information.

Database Profiling

MongoDB’s “Profiler” is a database profiling system that can help identify inefficient queries and operations.

The following profiling levels are available:

Level | Setting
0 | Off. No profiling
1 | On. Only includes “slow” operations
2 | On. Includes all operations

Enable the profiler by setting the profile value using the following command in the mongo shell:

db.setProfilingLevel(1)

The slowOpThresholdMs setting defines what constitutes a “slow” operation. To set the threshold above which the profiler considers operations “slow” (and thus, included in the level 1 profiling data), you can configure slowOpThresholdMs at runtime as an argument to the db.setProfilingLevel() operation.

See

The documentation of db.setProfilingLevel() for more information about this command.

By default, mongod records all “slow” queries to its log, as defined by slowOpThresholdMs.

Note

Because the database profiler can negatively impact performance, only enable profiling for strategic intervals and as minimally as possible on production systems.

You may enable profiling on a per-mongod basis. This setting will not propagate across a replica set or sharded cluster.

You can view the output of the profiler in the system.profile collection of your database by issuing the show profile command in the mongo shell, or with the following operation:

db.system.profile.find( { millis : { $gt : 100 } } )

This returns all operations that lasted longer than 100 milliseconds. Ensure that the value specified here (100, in this example) is above the slowOpThresholdMs threshold.

See also

Optimization Strategies for MongoDB addresses strategies that may improve the performance of your database queries and operations.

Replication and Monitoring

Beyond the basic monitoring requirements for any MongoDB instance, for replica sets, administrators must monitor replication lag. “Replication lag” refers to the amount of time that it takes to copy (i.e. replicate) a write operation on the primary to a secondary. Some small delay period may be acceptable, but two significant problems emerge as replication lag grows:

First, operations that occurred during the period of lag are not replicated to one or more secondaries. If you’re using replication to ensure data persistence, exceptionally long delays may impact the integrity of your data set.

Second, if the replication lag exceeds the length of the operation log (oplog) then MongoDB will have to perform an initial sync on the secondary, copying all data from the primary and rebuilding all indexes. This is uncommon under normal circumstances, but if you configure the oplog to be smaller than the default, the issue can arise.

Note

The size of the oplog is only configurable during the first run using the --oplogSize argument to the mongod command, or preferably, the oplogSizeMB setting in the MongoDB configuration file. If you do not specify this on the command line before running with the --replSet option, mongod will create a default sized oplog.

By default, the oplog is 5 percent of total available disk space on 64-bit systems. For more information about changing the oplog size, see the Change the Size of the Oplog

For causes of replication lag, see Replication Lag.

Replication issues are most often the result of network connectivity issues between members, or the result of a primary that does not have the resources to support application and replication traffic. To check the status of a replica, use the replSetGetStatus or the following helper in the shell:

rs.status()

The replSetGetStatus reference provides a more in-depth overview view of this output. In general, watch the value of optimeDate, and pay particular attention to the time difference between the primary and the secondary members.

Sharding and Monitoring

In most cases, the components of sharded clusters benefit from the same monitoring and analysis as all other MongoDB instances. In addition, clusters require further monitoring to ensure that data is effectively distributed among nodes and that sharding operations are functioning appropriately.

See also

See the Sharding Concepts documentation for more information.

Config Servers

The config database maintains a map identifying which documents are on which shards. The cluster updates this map as chunks move between shards. When a configuration server becomes inaccessible, certain sharding operations become unavailable, such as moving chunks and starting mongos instances. However, clusters remain accessible from already-running mongos instances.

Because inaccessible configuration servers can seriously impact the availability of a sharded cluster, you should monitor your configuration servers to ensure that the cluster remains well balanced and that mongos instances can restart.

MMS [https://mms.mongodb.com/] monitors config servers and can create notifications if a config server becomes inaccessible.

Balancing and Chunk Distribution

The most effective sharded cluster deployments evenly balance chunks among the shards. To facilitate this, MongoDB has a background balancer process that distributes data to ensure that chunks are always optimally distributed among the shards.

Issue the db.printShardingStatus() or sh.status() command to the mongos by way of the mongo shell. This returns an overview of the entire cluster including the database name, and a list of the chunks.

Stale Locks

In nearly every case, all locks used by the balancer are automatically released when they become stale. However, because any long lasting lock can block future balancing, it’s important to ensure that all locks are legitimate. To check the lock status of the database, connect to a mongos instance using the mongo shell. Issue the following command sequence to switch to the config database and display all outstanding locks on the shard database:

use config
db.locks.find()

For active deployments, the above query can provide insights. The balancing process, which originates on a randomly selected mongos, takes a special “balancer” lock that prevents other balancing activity from transpiring. Use the following command, also to the config database, to check the status of the “balancer” lock.

db.locks.find( { _id : "balancer" } )

If this lock exists, make sure that the balancer process is actively using this lock.

Run-time Database Configuration

The command line and configuration file interfaces provide MongoDB administrators with a large number of options and settings for controlling the operation of the database system. This document provides an overview of common configurations and examples of best-practice configurations for common use cases.

While both interfaces provide access to the same collection of options and settings, this document primarily uses the configuration file interface. If you run MongoDB using a control script or installed from a package for your operating system, you likely already have a configuration file located at /etc/mongodb.conf. Confirm this by checking the contents of the /etc/init.d/mongod or /etc/rc.d/mongod script to ensure that the control scripts start the mongod with the appropriate configuration file (see below.)

To start a MongoDB instance using this configuration issue a command in the following form:

mongod --config /etc/mongodb.conf
mongod -f /etc/mongodb.conf

Modify the values in the /etc/mongodb.conf file on your system to control the configuration of your database instance.

Configure the Database

Consider the following basic configuration:

fork = true
bind_ip = 127.0.0.1
port = 27017
quiet = true
dbpath = /srv/mongodb
logpath = /var/log/mongodb/mongod.log
logappend = true
journal = true

For most standalone servers, this is a sufficient base configuration. It makes several assumptions, but consider the following explanation:

fork is true, which enables a daemon mode for mongod, which detaches (i.e. “forks”) the MongoDB from the current session and allows you to run the database as a conventional server.

bindIp is 127.0.0.1, which forces the server to only listen for requests on the localhost IP. Only bind to secure interfaces that the application-level systems can access with access control provided by system network filtering (i.e. “firewall”).

New in version 2.6: mongod installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

port is 27017, which is the default MongoDB port for database instances. MongoDB can bind to any port. You can also filter access based on port using network filtering tools.

Note

UNIX-like systems require superuser privileges to attach processes to ports lower than 1024.

quiet is true. This disables all but the most critical entries in output/log file, and is not recommended for production systems. If you do set this option, you can use setParameter to modify this setting during run time.

dbPath is /srv/mongodb, which specifies where MongoDB will store its data files. /srv/mongodb and /var/lib/mongodb are popular locations. The user account that mongod runs under will need read and write access to this directory.

systemLog.path is /var/log/mongodb/mongod.log which is where mongod will write its output. If you do not set this value, mongod writes all output to standard output (e.g. stdout.)

logAppend is true, which ensures that mongod does not overwrite an existing log file following the server start operation.

storage.journal.enabled is true, which enables journaling. Journaling ensures single instance write-durability. 64-bit builds of mongod enable journaling by default. Thus, this setting may be redundant.

Given the default configuration, some of these values may be redundant. However, in many situations explicitly stating the configuration increases overall system intelligibility.

Security Considerations

The following collection of configuration options are useful for limiting access to a mongod instance. Consider the following:

bind_ip = 127.0.0.1,10.8.0.10,192.168.4.24
auth = true

Consider the following explanation for these configuration decisions:

“bindIp” has three values: 127.0.0.1, the localhost interface; 10.8.0.10, a private IP address typically used for local networks and VPN interfaces; and 192.168.4.24, a private network interface typically used for local networks.

Because production MongoDB instances need to be accessible from multiple database servers, it is important to bind MongoDB to multiple interfaces that are accessible from your application servers. At the same time it’s important to limit these interfaces to interfaces controlled and protected at the network layer.

“authorization” is true enables the authentication system within MongoDB. If enabled you will need to log in by connecting over the localhost interface for the first time to create user credentials.

“net.unixDomainSocket.enabled” to false disables the UNIX Socket, which is otherwise enabled by default. This limits access on the local system. This is desirable when running MongoDB on systems with shared access, but in most situations has minimal impact.

See also

Security Concepts

Replication and Sharding Configuration

Replication Configuration

Replica set configuration is straightforward, and only requires that the replSetName have a value that is consistent among all members of the set. Consider the following:

replSet = set0

Use descriptive names for sets. Once configured use the mongo shell to add hosts to the replica set.

See also

Replica set reconfiguration.

To enable authentication for the replica set, add the following option:

keyFile = /srv/mongodb/keyfile

New in version 1.8: for replica sets, and 1.9.1 for sharded replica sets.

Setting keyFile enables authentication and specifies a key file for the replica set member use to when authenticating to each other. The content of the key file is arbitrary, but must be the same on all members of the replica set and mongos instances that connect to the set. The keyfile must be less than one kilobyte in size and may only contain characters in the base64 set and the file must not have group or “world” permissions on UNIX systems.

See also

The Replica set Reconfiguration section for information regarding the process for changing replica set during operation.

Additionally, consider the Replica Set Security section for information on configuring authentication with replica sets.

Finally, see the Replication document for more information on replication in MongoDB and replica set configuration in general.

Sharding Configuration

Sharding requires a number of mongod instances with different configurations. The config servers store the cluster’s metadata, while the cluster distributes data among one or more shard servers.

Note

Config servers are not replica sets.

To set up one or three “config server” instances as normal mongod instances, and then add the following configuration option:

configsvr = true

bind_ip = 10.8.0.12
port = 27001

This creates a config server running on the private IP address 10.8.0.12 on port 27001. Make sure that there are no port conflicts, and that your config server is accessible from all of your mongos and mongod instances.

To set up shards, configure two or more mongod instance using your base configuration, with the shardsvr value for the clusterRole setting:

shardsvr = true

Finally, to establish the cluster, configure at least one mongos process with the following settings:

configdb = 10.8.0.12:27001
chunkSize = 64

You can specify multiple configDB instances by specifying hostnames and ports in the form of a comma separated list. In general, avoid modifying the chunkSize from the default value of 64, [1] and should ensure this setting is consistent among all mongos instances.

[1]
Chunk size is 64 megabytes by default, which provides the ideal balance between the most even distribution of data, for which smaller chunk sizes are best, and minimizing chunk migration, for which larger chunk sizes are optimal.

See also

The Sharding section of the manual for more information on sharding and cluster configuration.

Run Multiple Database Instances on the Same System

In many cases running multiple instances of mongod on a single system is not recommended. On some types of deployments [2] and for testing purposes you may need to run more than one mongod on a single system.

In these cases, use a base configuration for each instance, but consider the following configuration values:

dbpath = /srv/mongodb/db0/
pidfilepath = /srv/mongodb/db0.pid

The dbPath value controls the location of the mongod instance’s data directory. Ensure that each database has a distinct and well labeled data directory. The pidFilePath controls where mongod process places it’s process id file. As this tracks the specific mongod file, it is crucial that file be unique and well labeled to make it easy to start and stop these processes.

Create additional control scripts and/or adjust your existing MongoDB configuration and control script as needed to control these processes.

[2]
Single-tenant systems with SSD or other high performance disks may provide acceptable performance levels for multiple mongod instances. Additionally, you may find that multiple databases with small working sets may function acceptably on a single system.

Diagnostic Configurations

The following configuration options control various mongod behaviors for diagnostic purposes. The following settings have default values that tuned for general production purposes:

slowms = 50
profile = 3
verbose = true
objcheck = true

Use the base configuration and add these options if you are experiencing some unknown issue or performance problem as needed:

slowOpThresholdMs configures the threshold for to consider a query “slow,” for the purpose of the logging system and the database profiler. The default value is 100 milliseconds. Set a lower value if the database profiler does not return useful results, or a higher value to only log the longest running queries. See Optimization Strategies for MongoDB for more information on optimizing operations in MongoDB.

mode sets the database profiler level. The profiler is not active by default because of the possible impact on the profiler itself on performance. Unless this setting has a value, queries are not profiled.

verbosity controls the amount of logging output that mongod write to the log. Only use this option if you are experiencing an issue that is not reflected in the normal logging level.

wireObjectCheck forces mongod to validate all requests from clients upon receipt. Use this option to ensure that invalid requests are not causing errors, particularly when running a database with untrusted clients. This option may affect database performance.

Import and Export MongoDB Data

This document provides an overview of the import and export programs included in the MongoDB distribution. These tools are useful when you want to backup or export a portion of your data without capturing the state of the entire database, or for simple data ingestion cases. For more complex data migration tasks, you may want to write your own import and export scripts using a client driver to interact with the database itself. For disaster recovery protection and routine database backup operation, use full database instance backups.

Warning

Because these tools primarily operate by interacting with a running mongod instance, they can impact the performance of your running database.

Not only do these processes create traffic for a running database instance, they also force the database to read all data through memory. When MongoDB reads infrequently used data, it can supplant more frequently accessed data, causing a deterioration in performance for the database’s regular workload.

See also

MongoDB Backup Methods or MMS Backup Manual [https://docs.mms.mongodb.com/tutorial/nav/backup-use/] for more information on backing up MongoDB instances. Additionally, consider the following references for the MongoDB import/export tools:

mongoimport

mongoexport

mongorestore

mongodump

Data Import, Export, and Backup Operations

For resilient and non-disruptive backups, use a file system or block-level disk snapshot function, such as the methods described in the MongoDB Backup Methods document. The tools and operations discussed provide functionality that is useful in the context of providing some kinds of backups.

In contrast, use import and export tools to backup a small subset of your data or to move data to or from a third party system. These backups may capture a small crucial set of data or a frequently modified section of data for extra insurance, or for ease of access.

Warning

mongoimport and mongoexport do not reliably preserve all rich BSON data types because JSON can only represent a subset of the types supported by BSON. As a result, data exported or imported with these tools may lose some measure of fidelity. See the Extended JSON reference for more information.

No matter how you decide to import or export your data, consider the following guidelines:

Label files so that you can identify the contents of the export or backup as well as the point in time the export/backup reflect.

Do not create or apply exports if the backup process itself will have an adverse effect on a production system.

Make sure that they reflect a consistent data state. Export or backup processes can impact data integrity (i.e. type fidelity) and consistency if updates continue during the backup process.

Test backups and exports by restoring and importing to ensure that the backups are useful.

Human Intelligible Import/Export Formats

This section describes a process to import/export a collection to a file in a JSON or CSV format.

The examples in this section use the MongoDB tools mongoimport and mongoexport. These tools may also be useful for importing data into a MongoDB database from third party applications.

If you want to simply copy a database or collection from one instance to another, consider using the copydb, clone, or cloneCollection commands, which may be more suited to this task. The mongo shell provides the db.copyDatabase() method.

Collection Export with mongoexport

You can use the mongoexport utility you can create a backup file.

Warning

mongoimport and mongoexport do not reliably preserve all rich BSON data types because JSON can only represent a subset of the types supported by BSON. As a result, data exported or imported with these tools may lose some measure of fidelity. See the Extended JSON reference for more information.

In the most simple invocation, the command takes the following form:

mongoexport --collection collection --out collection.json

This will export all documents in the collection named collection into the file collection.json. Without the output specification (i.e. “--out collection.json”), mongoexport writes output to standard output (i.e. “stdout”). You can further narrow the results by supplying a query filter using the “--query” and limit results to a single database using the “--db” option. For instance:

mongoexport --db sales --collection contacts --query '{"field": 1}'

This command returns all documents in the sales database’s contacts collection, with a field named field with a value of 1. Enclose the query in single quotes (e.g. ') to ensure that it does not interact with your shell environment. The resulting documents will return on standard output.

By default, mongoexport returns one JSON document per MongoDB document. Specify the “--jsonArray” argument to return the export as a single JSON array. Use the “--csv” file to return the result in CSV (comma separated values) format.

If your mongod instance is not running, you can use the “--dbpath” option to specify the location to your MongoDB instance’s database files. See the following example:

mongoexport --db sales --collection contacts --dbpath /srv/MongoDB/

This reads the data files directly. This locks the data directory to prevent conflicting writes. The mongod process must not be running or attached to these data files when you run mongoexport in this configuration.

The “--host” and “--port” options allow you to specify a non-local host to connect to capture the export. Consider the following example:

mongoexport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --out mdb1-examplenet.json

On any mongoexport command you may, as above specify username and password credentials as above.

Collection Import with mongoimport

To restore a backup taken with mongoexport. Most of the arguments to mongoexport also exist for mongoimport.

Warning

mongoimport and mongoexport do not reliably preserve all rich BSON data types because JSON can only represent a subset of the types supported by BSON. As a result, data exported or imported with these tools may lose some measure of fidelity. See the Extended JSON reference for more information.

Consider the following command:

mongoimport --collection collection --file collection.json

This imports the contents of the file collection.json into the collection named collection. If you do not specify a file with the “--file” option, mongoimport accepts input over standard input (e.g. “stdin.”)

If you specify the “--upsert” option, all of mongoimport operations will attempt to update existing documents in the database and insert other documents. This option will cause some performance impact depending on your configuration.

You can specify the database option --db to import these documents to a particular database. If your MongoDB instance is not running, use the “--dbpath” option to specify the location of your MongoDB instance’s database files. Consider using the “--journal” option to ensure that mongoimport records its operations in the journal. The mongod process must not be running or attached to these data files when you run mongoimport in this configuration.

Use the “--ignoreBlanks” option to ignore blank fields. For CSV and TSV imports, this option provides the desired functionality in most cases: it avoids inserting blank fields in MongoDB documents.

Production Notes

This page details system configurations that affect MongoDB, especially in production.

Note

MongoDB Management Service (MMS) [https://mms.mongodb.com/] is a hosted service that provides monitoring, backup, and automated deployment of MongoDB instances. See the MMS Website [https://mms.mongodb.com/] and the MMS documentation [https://docs.mms.mongodb.com/] for more information.

Packages

MongoDB

Be sure you have the latest stable release. All releases are available on the Downloads [http://www.mongodb.org/downloads] page. This is a good place to verify what is current, even if you then choose to install via a package manager.

Always use 64-bit builds for production. The 32-bit build MongoDB offers for test and development environments is not suitable for production deployments as it can store no more than 2GB of data. See the 32-bit limitations page for more information.

32-bit builds exist to support use on development machines.

Operating Systems

MongoDB distributions are currently available for Mac OS X, Linux, Windows Server 2008 R2 64bit, Windows 7 (32 bit and 64 bit), Windows Vista, and Solaris platforms.

Note

MongoDB uses the GNU C Library [http://www.gnu.org/software/libc/] (glibc) if available on a system. MongoDB requires version at least glibc-2.12-1.2.el6 to avoid a known bug with earlier versions. For best results use at least version 2.13.

Concurrency

In earlier versions of MongoDB, all write operations contended for a single readers-writer lock on the MongoDB instance. As of version 2.2, each database has a readers-writer lock that allows concurrent reads access to a database, but gives exclusive access to a single write operation per database. See the Concurrency page for more information.

Journaling

MongoDB uses write ahead logging to an on-disk journal to guarantee that MongoDB is able to quickly recover the write operations following a crash or other serious failure.

In order to ensure that mongod will be able to recover its data files and keep the data files in a valid state following a crash, leave journaling enabled. See Journaling for more information.

Networking

Use Trusted Networking Environments

Always run MongoDB in a trusted environment, with network rules that prevent access from all unknown machines, systems, and networks. As with any sensitive system dependent on network access, your MongoDB deployment should only be accessible to specific systems that require access, such as application servers, monitoring services, and other MongoDB components.

Note

By default, authorization is not enabled and mongod assumes a trusted environment. You can enable security/auth mode if you need it.

See documents in the Security Section for additional information, specifically:

Configuration Options

Firewalls

Network Security Tutorials

For Windows users, consider the Windows Server Technet Article on TCP Configuration [http://technet.microsoft.com/en-us/library/dd349797.aspx] when deploying MongoDB on Windows.

Connection Pools

To avoid overloading the connection resources of a single mongod or mongos instance, ensure that clients maintain reasonable connection pool sizes.

The connPoolStats database command returns information regarding the number of open connections to the current database for mongos instances and mongod instances in sharded clusters.

Hardware Considerations

MongoDB is designed specifically with commodity hardware in mind and has few hardware requirements or limitations. MongoDB’s core components run on little-endian hardware, primarily x86/x86_64 processors. Client libraries (i.e. drivers) can run on big or little endian systems.

Hardware Requirements and Limitations

The hardware for the most effective MongoDB deployments have the following properties:

Allocate Sufficient RAM and CPU

As with all software, more RAM and a faster CPU clock speed are important for performance.

In general, databases are not CPU bound. As such, increasing the number of cores can help, but does not provide significant marginal return.

Use Solid State Disks (SSDs)

MongoDB has good results and a good price-performance ratio with SATA SSD (Solid State Disk).

Use SSD if available and economical. Spinning disks can be performant, but SSDs’ capacity for random I/O operations works well with the update model of mongod.

Commodity (SATA) spinning drives are often a good option, as the random I/O performance increase with more expensive spinning drives is not that dramatic (only on the order of 2x). Using SSDs or increasing RAM may be more effective in increasing I/O throughput.

Avoid Remote File Systems

Remote file storage can create performance problems in MongoDB. See Remote Filesystems for more information about storage and MongoDB.

MongoDB and NUMA Hardware

Running MongoDB on a system with Non-Uniform Access Memory (NUMA) can cause a number of operational problems, including slow performance for periods of time and high system process usage.

When running MongoDB servers and clients on NUMA hardware, you should configure a memory interleave policy so that the host behaves in a non-NUMA fashion. MongoDB checks NUMA settings on start up when deployed on Linux (since version 2.0) and Windows (since version 2.6) machines, and prints a warning if the NUMA configuration may degrade performance.

See The MySQL “swap insanity” problem and the effects of NUMA [http://jcole.us/blog/archives/2010/09/28/mysql-swap-insanity-and-the-numa-architecture/] post, which describes the effects of NUMA on databases. This blog post addresses the impact of NUMA for MySQL, but the issues for MongoDB are similar. The post introduces NUMA and its goals, and illustrates how these goals are not compatible with production databases.

Configuring NUMA on Windows

On Windows, memory interleaving must be enabled through the machine’s BIOS. Please consult your system documentation for details.

Configuring NUMA on Linux

When running MongoDB on Linux you may instead use the numactl command and start the MongoDB programs (mongod, mongos, or clients) in the following manner:

numactl --interleave=all <path>

where <path> is the path to the program you are starting. Then, disable zone reclaim in the proc settings using the following command:

echo 0 > /proc/sys/vm/zone_reclaim_mode

To fully disable NUMA behavior, you must perform both operations. For more information, see the Documentation for /proc/sys/vm/* [http://www.kernel.org/doc/Documentation/sysctl/vm.txt].

Disk and Storage Systems

Swap

Assign swap space for your systems. Allocating swap space can avoid issues with memory contention and can prevent the OOM Killer on Linux systems from killing mongod.

The method mongod uses to map memory files to memory ensures that the operating system will never store MongoDB data in swap space.

RAID

Most MongoDB deployments should use disks backed by RAID-10.

RAID-5 and RAID-6 do not typically provide sufficient performance to support a MongoDB deployment.

Avoid RAID-0 with MongoDB deployments. While RAID-0 provides good write performance, it also provides limited availability and can lead to reduced performance on read operations, particularly when using Amazon’s EBS volumes.

Remote Filesystems

The Network File System protocol (NFS) is not recommended for use with MongoDB as some versions perform poorly.

Performance problems arise when both the data files and the journal files are hosted on NFS. You may experience better performance if you place the journal on local or iscsi volumes. If you must use NFS, add the following NFS options to your /etc/fstab file: bg, nolock, and noatime.

Separate Components onto Different Storage Devices

For improved performance, consider separating your database’s data, journal, and logs onto different storage devices, based on your application’s access and write pattern.

Note

This will affect your ability to create snapshot-style backups of your data, since the files will be on different devices and volumes.

Scheduling for Virtual Devices

Local block devices attached to virtual machine instances via the hypervisor should use a noop scheduler for best performance. The noop scheduler allows the operating system to defer I/O scheduling to the underlying hypervisor.

Architecture

Write Concern

Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concerns determine the level of guarantee. When inserts, updates and deletes have a weak write concern, write operations return quickly. In some failure cases, write operations issued with weak write concerns may not persist. With stronger write concerns, clients wait after sending a write operation for MongoDB to confirm the write operations.

MongoDB provides different levels of write concern to better address the specific needs of applications. Clients may adjust write concern to ensure that the most important operations persist successfully to an entire MongoDB deployment. For other less critical operations, clients can adjust the write concern to ensure faster performance rather than ensure persistence to the entire deployment.

See the Write Concern document for more information about choosing an appropriate write concern level for your deployment.

Replica Sets

See the Replica Set Architectures document for an overview of architectural considerations for replica set deployments.

Sharded Clusters

See the Sharded Cluster Production Architecture document for an overview of recommended sharded cluster architectures for production deployments.

Platforms

MongoDB on Linux

Important

The following discussion only applies to Linux, and therefore does not affect deployments where mongod instances run other UNIX-like systems or on Windows.

Kernel and File Systems

When running MongoDB in production on Linux, it is recommended that you use Linux kernel version 2.6.36 or later.

MongoDB preallocates its database files before using them and often creates large files. As such, you should use the Ext4 and XFS file systems:

In general, if you use the Ext4 file system, use at least version 2.6.23 of the Linux Kernel.

In general, if you use the XFS file system, use at least version 2.6.25 of the Linux Kernel.

Some Linux distributions require different versions of the kernel to support using ext4 and/or xfs:

Linux Distribution | Filesystem | Kernel Version
CentOS 5.5 | ext4, xfs | 2.6.18-194.el5
CentOS 5.6 | ext4, xfs | 2.6.18-238.el5
CentOS 5.8 | ext4, xfs | 2.6.18-308.8.2.el5
CentOS 6.1 | ext4, xfs | 2.6.32-131.0.15.el6.x86_64
RHEL 5.6 | ext4 | 2.6.18-238
RHEL 6.0 | xfs | 2.6.32-71
Ubuntu 10.04.4 LTS | ext4, xfs | 2.6.32-38-server
Amazon Linux AMI release 2012.03 | ext4 | 3.2.12-3.2.4.amzn1.x86_64

Important

MongoDB requires a filesystem that supports fsync() on directories. For example, HGFS and Virtual Box’s shared folders do not support this operation.

Recommended Configuration

Turn off atime for the storage volume containing the database files.

Set the file descriptor limit, -n, and the user process limit (ulimit), -u, above 20,000, according to the suggestions in the ulimit document. A low ulimit will affect MongoDB when under heavy use and can produce errors and lead to failed connections to MongoDB processes and loss of service.

Disable transparent huge pages as MongoDB performs better with normal (4096 bytes) virtual memory pages.

Disable NUMA in your BIOS. If that is not possible see MongoDB on NUMA Hardware.

Ensure that readahead settings for the block devices that store the database files are appropriate. For random access use patterns, set low readahead values. A readahead of 32 (16kb) often works well.

For a standard block device, you can run sudo blockdev --report to get the readahead settings and sudo blockdev --setra <value> <device> to change the readahead settings. Refer to your specific operating system manual for more information.

Use the Network Time Protocol (NTP) to synchronize time among your hosts. This is especially important in sharded clusters.

MongoDB Enterprise and SSL Libraries

On Linux platforms, you may observe one of the following statements in the MongoDB log:

<path to SSL libs>/libssl.so.<version>: no version information available (required by /usr/bin/mongod)
<path to SSL libs>/libcrypto.so.<version>: no version information available (required by /usr/bin/mongod)

These warnings indicate that the system’s SSL libraries are different from the SSL libraries that the mongod was compiled against. Typically these messages do not require intervention; however, you can use the following operations to determine the symbol versions that mongod expects:

objdump -T <path to mongod>/mongod | grep " SSL_"
objdump -T <path to mongod>/mongod | grep " CRYPTO_"

These operations will return output that resembles one the of the following lines:

0000000000000000      DF *UND*       0000000000000000  libssl.so.10 SSL_write
0000000000000000      DF *UND*       0000000000000000  OPENSSL_1.0.0 SSL_write

The last two strings in this output are the symbol version and symbol name. Compare these values with the values returned by the following operations to detect symbol version mismatches:

objdump -T <path to SSL libs>/libssl.so.1*
objdump -T <path to SSL libs>/libcrypto.so.1*

This procedure is neither exact nor exhaustive: many symbols used by mongod from the libcrypto library do not begin with CRYPTO_.

MongoDB on Virtual Environments

The section describes considerations when running MongoDB in some of the more common virtual environments.

For all platforms, consider Scheduling for Virtual Devices.

EC2

MongoDB is compatible with EC2 and requires no configuration changes specific to the environment.

You may alternately choose to obtain a set of Amazon Machine Images (AMI) that bundle together MongoDB and Amazon’s Provisioned IOPS storage volumes. Provisioned IOPS can greatly increase MongoDB’s performance and ease of use. For more information, see this blog post [http://www.mongodb.com/blog/post/provisioned-iops-aws-marketplace-significantly-boosts-mongodb-performance-ease-use].

VMWare

MongoDB is compatible with VMWare. As some users have run into issues with VMWare’s memory overcommit feature, disabling the feature is recommended.

It is possible to clone a virtual machine running MongoDB. You might use this function to spin up a new virtual host to add as a member of a replica set. If you clone a VM with journaling enabled, the clone snapshot will be valid. If not using journaling, first stop mongod, then clone the VM, and finally, restart mongod.

OpenVZ

Some users have had issues when running MongoDB on some older version of OpenVZ due to its handling of virtual memory, as with VMWare.

This issue seems to have been resolved in the more recent versions of OpenVZ.

Performance Monitoring

iostat

On Linux, use the iostat command to check if disk I/O is a bottleneck for your database. Specify a number of seconds when running iostat to avoid displaying stats covering the time since server boot.

For example, the following command will display extended statistics and the time for each displayed report, with traffic in MB/s, at one second intervals:

iostat -xmt 1

Key fields from iostat:

%util: this is the most useful field for a quick check, it indicates what percent of the time the device/drive is in use.

avgrq-sz: average request size. Smaller number for this value reflect more random IO operations.

bwm-ng

bwm-ng [http://www.gropp.org/?id=projects&sub=bwm-ng] is a command-line tool for monitoring network use. If you suspect a network-based bottleneck, you may use bwm-ng to begin your diagnostic process.

Backups

To make backups of your MongoDB database, please refer to MongoDB Backup Methods Overview.

Additional Resources

Blog Post: Capacity Planning and Hardware Provisioning for MongoDB In Ten Minutes [https://www.mongodb.com/blog/post/capacity-planning-and-hardware-provisioning-mongodb-ten-minutes]

Whitepaper: MongoDB Multi-Data Center Deployments [http://www.mongodb.com/lp/white-paper/multi-dc]

Whitepaper: Security Architecture [https://www.mongodb.com/lp/white-paper/mongodb-security-architecture]

Whitepaper: MongoDB Architecture Guide [https://www.mongodb.com/lp/whitepaper/architecture-guide]

Presentation: MongoDB Administration 101 [http://www.mongodb.com/presentations/webinar-mongodb-administration-101]

Data Management

These document introduce data management practices and strategies for MongoDB deployments, including strategies for managing multi-data center deployments, managing larger file stores, and data lifecycle tools.

Data Center Awareness

Presents the MongoDB features that allow application developers and database administrators to configure their deployments to be more data center aware or allow operational and location-based separation.

Capped Collections

Capped collections provide a special type of size-constrained collections that preserve insertion order and can support high volume inserts.

Expire Data from Collections by Setting TTL

TTL collections make it possible to automatically remove data from a collection based on the value of a timestamp and are useful for managing data like machine generated event data that are only useful for a limited period of time.

Data Center Awareness

Operational Segregation in MongoDB Deployments

Capped Collections

Expire Data from Collections by Setting TTL

Data Center Awareness

MongoDB provides a number of features that allow application developers and database administrators to customize the behavior of a sharded cluster or replica set deployment so that MongoDB may be more “data center aware,” or allow operational and location-based separation.

MongoDB also supports segregation based on functional parameters, to ensure that certain mongod instances are only used for reporting workloads or that certain high-frequency portions of a sharded collection only exist on specific shards.

The following documents, found either in this section or other sections of this manual, provide information on customizing a deployment for operation- and location-based separation:

Operational Segregation in MongoDB Deployments

MongoDB lets you specify that certain application operations use certain mongod instances.

Tag Aware Sharding

Tags associate specific ranges of shard key values with specific shards for use in managing deployment patterns.

Manage Shard Tags

Use tags to associate specific ranges of shard key values with specific shards.

Operational Segregation in MongoDB Deployments

Further Reading

The Write Concern and Read Preference documents, which address capabilities related to data center awareness.

Deploy a Geographically Redundant Replica Set.

Additional Resource

MongoDB Multi-Data Center Deployments Whitepaper [http://www.mongodb.com/lp/white-paper/multi-dc]

Operational Segregation in MongoDB Deployments

Operational Overview

MongoDB includes a number of features that allow database administrators and developers to segregate application operations to MongoDB deployments by functional or geographical groupings.

This capability provides “data center awareness,” which allows applications to target MongoDB deployments with consideration of the physical location of the mongod instances. MongoDB supports segmentation of operations across different dimensions, which may include multiple data centers and geographical regions in multi-data center deployments, racks, networks, or power circuits in single data center deployments.

MongoDB also supports segregation of database operations based on functional or operational parameters, to ensure that certain mongod instances are only used for reporting workloads or that certain high-frequency portions of a sharded collection only exist on specific shards.

Specifically, with MongoDB, you can:

ensure write operations propagate to specific members of a replica set, or to specific members of replica sets.

ensure that specific members of a replica set respond to queries.

ensure that specific ranges of your shard key balance onto and reside on specific shards.

combine the above features in a single distributed deployment, on a per-operation (for read and write operations) and collection (for chunk distribution in sharded clusters distribution) basis.

For full documentation of these features, see the following documentation in the MongoDB Manual:

Read Preferences, which controls how drivers help applications target read operations to members of a replica set.

Write Concerns, which controls how MongoDB ensures that write operations propagate to members of a replica set.

Replica Set Tags, which control how applications create and interact with custom groupings of replica set members to create custom application-specific read preferences and write concerns.

Tag Aware Sharding, which allows MongoDB administrators to define an application-specific balancing policy, to control how documents belonging to specific ranges of a shard key distribute to shards in the sharded cluster.

See also

Before adding operational segregation features to your application and MongoDB deployment, become familiar with all documentation of replication, and sharding.

Additional Resource

MongoDB Multi-Data Center Deployments Whitepaper [http://www.mongodb.com/lp/white-paper/multi-dc]

Capped Collections

Capped collections are fixed-size collections that support high-throughput operations that insert and retrieve documents based on insertion order. Capped collections work in a way similar to circular buffers: once a collection fills its allocated space, it makes room for new documents by overwriting the oldest documents in the collection.

See createCollection() or create for more information on creating capped collections.

Capped collections have the following behaviors:

Capped collections guarantee preservation of the insertion order. As a result, queries do not need an index to return documents in insertion order. Without this indexing overhead, they can support higher insertion throughput.

Capped collections guarantee that insertion order is identical to the order on disk (natural order) and do so by prohibiting updates that increase document size. Capped collections only allow updates that fit the original document size, which ensures a document does not change its location on disk.

Capped collections automatically remove the oldest documents in the collection without requiring scripts or explicit remove operations.

For example, the oplog.rs collection that stores a log of the operations in a replica set uses a capped collection. Consider the following potential use cases for capped collections:

Store log information generated by high-volume systems. Inserting documents in a capped collection without an index is close to the speed of writing log information directly to a file system. Furthermore, the built-in first-in-first-out property maintains the order of events, while managing storage use.

Cache small amounts of data in a capped collections. Since caches are read rather than write heavy, you would either need to ensure that this collection always remains in the working set (i.e. in RAM) or accept some write penalty for the required index or indexes.

Recommendations and Restrictions

You can only make in-place updates of documents. If the update operation causes the document to grow beyond their original size, the update operation will fail.

If you plan to update documents in a capped collection, create an index so that these update operations do not require a table scan.

If you update a document in a capped collection to a size smaller than its original size, and then a secondary resyncs from the primary, the secondary will replicate and allocate space based on the current smaller document size. If the primary then receives an update which increases the document back to its original size, the primary will accept the update but the secondary will fail with a failing update: objects in a capped ns cannot grow error message.

To prevent this error, create your secondary from a snapshot of one of the other up-to-date members of the replica set. Follow our tutorial on filesystem snapshots to seed your new secondary.

Seeding the secondary with a filesystem snapshot is the only way to guarantee the primary and secondary binary files are compatible. MMS Backup snapshots are insufficient in this situation since you need more than the content of the secondary to match the primary.

You cannot delete documents from a capped collection. To remove all documents from a collection, use the drop() method to drop the collection.

You cannot shard a capped collection.

Capped collections created after 2.2 have an _id field and an index on the _id field by default. Capped collections created before 2.2 do not have an index on the _id field by default. If you are using capped collections with replication prior to 2.2, you should explicitly create an index on the _id field.

Warning

If you have a capped collection in a replica set outside of the local database, before 2.2, you should create a unique index on _id. Ensure uniqueness using the unique: true option to the ensureIndex() method or by using an ObjectId for the _id field. Alternately, you can use the autoIndexId option to create when creating the capped collection, as in the Query a Capped Collection procedure.

Use natural ordering to retrieve the most recently inserted elements from the collection efficiently. This is (somewhat) analogous to tail on a log file.

The aggregation pipeline operator $out cannot write results to a capped collection.

Procedures

Create a Capped Collection

You must create capped collections explicitly using the createCollection() method, which is a helper in the mongo shell for the create command. When creating a capped collection you must specify the maximum size of the collection in bytes, which MongoDB will pre-allocate for the collection. The size of the capped collection includes a small amount of space for internal overhead.

db.createCollection( "log", { capped: true, size: 100000 } )

If the size field is less than or equal to 4096, then the collection will have a cap of 4096 bytes. Otherwise, MongoDB will raise the provided size to make it an integer multiple of 256.

Additionally, you may also specify a maximum number of documents for the collection using the max field as in the following document:

db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

Important

The size argument is always required, even when you specify max number of documents. MongoDB will remove older documents if a collection reaches the maximum size limit before it reaches the maximum document count.

See

createCollection() and create.

Query a Capped Collection

If you perform a find() on a capped collection with no ordering specified, MongoDB guarantees that the ordering of results is the same as the insertion order.

To retrieve documents in reverse insertion order, issue find() along with the sort() method with the $natural parameter set to -1, as shown in the following example:

db.cappedCollection.find().sort( { $natural: -1 } )

Check if a Collection is Capped

Use the isCapped() method to determine if a collection is capped, as follows:

db.collection.isCapped()

Convert a Collection to Capped

You can convert a non-capped collection to a capped collection with the convertToCapped command:

db.runCommand({"convertToCapped": "mycoll", size: 100000});

The size parameter specifies the size of the capped collection in bytes.

Warning

This command obtains a global write lock and will block other operations until it has completed.

Changed in version 2.2: Before 2.2, capped collections did not have an index on _id unless you specified autoIndexId to the create, after 2.2 this became the default.

Automatically Remove Data After a Specified Period of Time

For additional flexibility when expiring data, consider MongoDB’s TTL indexes, as described in Expire Data from Collections by Setting TTL. These indexes allow you to expire and remove data from normal collections using a special type, based on the value of a date-typed field and a TTL value for the index.

TTL Collections are not compatible with capped collections.

Tailable Cursor

You can use a tailable cursor with capped collections. Similar to the Unix tail -f command, the tailable cursor “tails” the end of a capped collection. As new documents are inserted into the capped collection, you can use the tailable cursor to continue retrieving documents.

See Create Tailable Cursor for information on creating a tailable cursor.

Expire Data from Collections by Setting TTL

New in version 2.2.

This document provides an introduction to MongoDB’s “time to live” or TTL collection feature. TTL collections make it possible to store data in MongoDB and have the mongod automatically remove data after a specified number of seconds or at a specific clock time.

Data expiration is useful for some classes of information, including machine generated event data, logs, and session information that only need to persist for a limited period of time.

A special TTL index property supports the implementation of TTL collections. The TTL feature relies on a background thread in mongod that reads the date-typed values in the index and removes expired documents from the collection.

Procedures

To create a TTL index, use the db.collection.ensureIndex() method with the expireAfterSeconds option on a field whose value is either a date or an array that contains date values.

Note

The TTL index is a single field index. Compound indexes do not support the TTL property. For more information on TTL indexes, see TTL Indexes.

Expire Documents after a Specified Number of Seconds

To expire data after a specified number of seconds has passed since the indexed field, create a TTL index on a field that holds values of BSON date type or an array of BSON date-typed objects and specify a positive non-zero value in the expireAfterSeconds field. A document will expire when the number of seconds in the expireAfterSeconds field has passed since the time specified in its indexed field. [1]

For example, the following operation creates an index on the log_events collection’s createdAt field and specifies the expireAfterSeconds value of 3600 to set the expiration time to be one hour after the time specified by createdAt.

db.log_events.ensureIndex( { "createdAt": 1 }, { expireAfterSeconds: 3600 } )

When adding documents to the log_events collection, set the createdAt field to the current time:

db.log_events.insert( {
   "createdAt": new Date(),
   "logEvent": 2,
   "logMessage": "Success!"
} )

MongoDB will automatically delete documents from the log_events collection when the document’s createdAt value [1] is older than the number of seconds specified in expireAfterSeconds.

[1]
(1, 2) If the field contains an array of BSON date-typed objects, data expires if at least one of BSON date-typed object is older than the number of seconds specified in expireAfterSeconds.

See also

$currentDate operator

Expire Documents at a Specific Clock Time

To expire documents at a specific clock time, begin by creating a TTL index on a field that holds values of BSON date type or an array of BSON date-typed objects and specify an expireAfterSeconds value of 0. For each document in the collection, set the indexed date field to a value corresponding to the time the document should expire. If the indexed date field contains a date in the past, MongoDB considers the document expired.

For example, the following operation creates an index on the log_events collection’s expireAt field and specifies the expireAfterSeconds value of 0:

db.log_events.ensureIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )

For each document, set the value of expireAt to correspond to the time the document should expire. For instance, the following insert() operation adds a document that should expire at July 22, 2013 14:00:00.

db.log_events.insert( {
   "expireAt": new Date('July 22, 2013 14:00:00'),
   "logEvent": 2,
   "logMessage": "Success!"
} )

MongoDB will automatically delete documents from the log_events collection when the documents’ expireAt value is older than the number of seconds specified in expireAfterSeconds, i.e. 0 seconds older in this case. As such, the data expires at the specified expireAt value.

Optimization Strategies for MongoDB

There are many factors that can affect database performance and responsiveness including index use, query structure, data models and application design, as well as operational factors such as architecture and system configuration.

This section describes techniques for optimizing application performance with MongoDB.

Evaluate Performance of Current Operations

MongoDB provides introspection tools that describe the query execution process, to allow users to test queries and build more efficient queries.

Use Capped Collections for Fast Writes and Reads

Outlines a use case for Capped Collections to optimize certain data ingestion work flows.

Optimize Query Performance

Introduces the use of projections to reduce the amount of data MongoDB sends to clients.

Design Notes

A collection of notes related to the architecture, design, and administration of MongoDB-based applications.

Evaluate Performance of Current Operations

Use Capped Collections for Fast Writes and Reads

Optimize Query Performance

Design Notes

Evaluate Performance of Current Operations

The following sections describe techniques for evaluating operational performance.

Use the Database Profiler to Evaluate Operations Against the Database

MongoDB provides a database profiler that shows performance characteristics of each operation against the database. Use the profiler to locate any queries or write operations that are running slow. You can use this information, for example, to determine what indexes to create.

For more information, see Database Profiling.

Use db.currentOp() to Evaluate mongod Operations

The db.currentOp() method reports on current operations running on a mongod instance.

Use $explain to Evaluate Query Performance

The explain() method returns statistics on a query, and reports the index MongoDB selected to fulfill the query, as well as information about the internal operation of the query.

Example

To use explain() on a query for documents matching the expression { a: 1 }, in the collection named records, use an operation that resembles the following in the mongo shell:

db.records.find( { a: 1 } ).explain()

See Analyze Query Performance for more details.

Use Capped Collections for Fast Writes and Reads

Use Capped Collections for Fast Writes

Capped Collections are circular, fixed-size collections that keep documents well-ordered, even without the use of an index. This means that capped collections can receive very high-speed writes and sequential reads.

These collections are particularly useful for keeping log files but are not limited to that purpose. Use capped collections where appropriate.

Use Natural Order for Fast Reads

To return documents in the order they exist on disk, return sorted operations using the $natural operator. On a capped collection, this also returns the documents in the order in which they were written.

Natural order does not use indexes but can be fast for operations when you want to select the first or last items on disk.

See also

sort() and limit().

Optimize Query Performance

Create Indexes to Support Queries

For commonly issued queries, create indexes. If a query searches multiple fields, create a compound index. Scanning an index is much faster than scanning a collection. The indexes structures are smaller than the documents reference, and store references in order.

Example

If you have a posts collection containing blog posts, and if you regularly issue a query that sorts on the author_name field, then you can optimize the query by creating an index on the author_name field:

db.posts.ensureIndex( { author_name : 1 } )

Indexes also improve efficiency on queries that routinely sort on a given field.

Example

If you regularly issue a query that sorts on the timestamp field, then you can optimize the query by creating an index on the timestamp field:

Creating this index:

db.posts.ensureIndex( { timestamp : 1 } )

Optimizes this query:

db.posts.find().sort( { timestamp : -1 } )

Because MongoDB can read indexes in both ascending and descending order, the direction of a single-key index does not matter.

Indexes support queries, update operations, and some phases of the aggregation pipeline.

Index keys that are of the BinData type are more efficiently stored in the index if:

the binary subtype value is in the range of 0-7 or 128-135, and

the length of the byte array is: 0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, or 32.

Limit the Number of Query Results to Reduce Network Demand

MongoDB cursors return results in groups of multiple documents. If you know the number of results you want, you can reduce the demand on network resources by issuing the limit() method.

This is typically used in conjunction with sort operations. For example, if you need only 10 results from your query to the posts collection, you would issue the following command:

db.posts.find().sort( { timestamp : -1 } ).limit(10)

For more information on limiting results, see limit()

Use Projections to Return Only Necessary Data

When you need only a subset of fields from documents, you can achieve better performance by returning only the fields you need:

For example, if in your query to the posts collection, you need only the timestamp, title, author, and abstract fields, you would issue the following command:

db.posts.find( {}, { timestamp : 1 , title : 1 , author : 1 , abstract : 1} ).sort( { timestamp : -1 } )

For more information on using projections, see Limit Fields to Return from a Query.

Use $hint to Select a Particular Index

In most cases the query optimizer selects the optimal index for a specific operation; however, you can force MongoDB to use a specific index using the hint() method. Use hint() to support performance testing, or on some queries where you must select a field or field included in several indexes.

Use the Increment Operator to Perform Operations Server-Side

Use MongoDB’s $inc operator to increment or decrement values in documents. The operator increments the value of the field on the server side, as an alternative to selecting a document, making simple modifications in the client and then writing the entire document to the server. The $inc operator can also help avoid race conditions, which would result when two application instances queried for a document, manually incremented a field, and saved the entire document back at the same time.

Design Notes

This page details features of MongoDB that may be important to keep in mind when developing applications.

Schema Considerations

Dynamic Schema

Data in MongoDB has a dynamic schema. Collections do not enforce document structure. This facilitates iterative development and polymorphism. Nevertheless, collections often hold documents with highly homogeneous structures. See Data Modeling Concepts for more information.

Some operational considerations include:

the exact set of collections to be used;

the indexes to be used: with the exception of the _id index, all indexes must be created explicitly;

shard key declarations: choosing a good shard key is very important as the shard key cannot be changed once set.

Avoid importing unmodified data directly from a relational database. In general, you will want to “roll up” certain data into richer documents that take advantage of MongoDB’s support for embedded documents and nested arrays.

Case Sensitive Strings

MongoDB strings are case sensitive. So a search for "joe" will not find "Joe".

Consider:

storing data in a normalized case format, or

using regular expressions ending with the i option, and/or

using $toLower or $toUpper in the aggregation framework.

Type Sensitive Fields

MongoDB data is stored in the BSON [http://docs.mongodb.org/meta-driver/latest/legacy/bson/] format, a binary encoded serialization of JSON-like documents. BSON encodes additional type information. See bsonspec.org [http://bsonspec.org/#/specification] for more information.

Consider the following document which has a field x with the string value "123":

{ x : "123" }

Then the following query which looks for a number value 123 will not return that document:

db.mycollection.find( { x : 123 } )

General Considerations

By Default, Updates Affect one Document

To update multiple documents that meet your query criteria, set the update multi option to true or 1. See: Update Multiple Documents.

Prior to MongoDB 2.2, you would specify the upsert and multi options in the update method as positional boolean options. See: the update method reference documentation.

BSON Document Size Limit

The BSON Document Size limit is currently set at 16MB per document. If you require larger documents, use GridFS.

No Fully Generalized Transactions

MongoDB does not have fully generalized transactions. If you model your data using rich documents that closely resemble your application’s objects, each logical object will be in one MongoDB document. MongoDB allows you to modify a document in a single atomic operation. These kinds of data modification pattern covers most common uses of transactions in other systems.

Replica Set Considerations

Use an Odd Number of Replica Set Members

Replica sets perform consensus elections. To ensure that elections will proceed successfully, either use an odd number of members, typically three, or else use an arbiter to ensure an odd number of votes.

Keep Replica Set Members Up-to-Date

MongoDB replica sets support automatic failover. It is important for your secondaries to be up-to-date. There are various strategies for assessing consistency:

Use monitoring tools to alert you to lag events. See Monitoring for MongoDB for a detailed discussion of MongoDB’s monitoring options.

Specify appropriate write concern.

If your application requires manual fail over, you can configure your secondaries as priority 0. Priority 0 secondaries require manual action for a failover. This may be practical for a small replica set, but large deployments should fail over automatically.

See also

replica set rollbacks.

Sharding Considerations

Pick your shard keys carefully. You cannot choose a new shard key for a collection that is already sharded.

Shard key values are immutable.

When enabling sharding on an existing collection, MongoDB imposes a maximum size on those collections to ensure that it is possible to create chunks. For a detailed explanation of this limit, see: <sharding-existing-collection-data-size>.

To shard large amounts of data, create a new empty sharded collection, and ingest the data from the source collection using an application level import operation.

Unique indexes are not enforced across shards except for the shard key itself. See Enforce Unique Keys for Sharded Collections.

Consider pre-splitting a sharded collection before a massive bulk import.

Analyze Performance

As you develop and operate applications with MongoDB, you may want to analyze the performance of the database as the application. Consider the following as you begin to investigate the performance of MongoDB.

Overview

Degraded performance in MongoDB is typically a function of the relationship between the quantity of data stored in the database, the amount of system RAM, the number of connections to the database, and the amount of time the database spends in a locked state.

In some cases performance issues may be transient and related to traffic load, data access patterns, or the availability of hardware on the host system for virtualized environments. Some users also experience performance limitations as a result of inadequate or inappropriate indexing strategies, or as a consequence of poor schema design patterns. In other situations, performance issues may indicate that the database may be operating at capacity and that it is time to add additional capacity to the database.

The following are some causes of degraded performance in MongoDB.

Locks

MongoDB uses a locking system to ensure data set consistency. However, if certain operations are long-running, or a queue forms, performance will slow as requests and operations wait for the lock. Lock-related slowdowns can be intermittent. To see if the lock has been affecting your performance, look to the data in the globalLock section of the serverStatus output. If globalLock.currentQueue.total is consistently high, then there is a chance that a large number of requests are waiting for a lock. This indicates a possible concurrency issue that may be affecting performance.

If globalLock.totalTime is high relative to uptime, the database has existed in a lock state for a significant amount of time. If globalLock.ratio is also high, MongoDB has likely been processing a large number of long running queries. Long queries are often the result of a number of factors: ineffective use of indexes, non-optimal schema design, poor query structure, system architecture issues, or insufficient RAM resulting in page faults and disk reads.

Memory Use

MongoDB uses memory mapped files to store data. Given a data set of sufficient size, the MongoDB process will allocate all available memory on the system for its use. While this is part of the design, and affords MongoDB superior performance, the memory mapped files make it difficult to determine if the amount of RAM is sufficient for the data set.

The memory usage statuses metrics of the serverStatus output can provide insight into MongoDB’s memory use. Check the resident memory use (i.e. mem.resident): if this exceeds the amount of system memory and there is a significant amount of data on disk that isn’t in RAM, you may have exceeded the capacity of your system.

You should also check the amount of mapped memory (i.e. mem.mapped.) If this value is greater than the amount of system memory, some operations will require disk access page faults to read data from virtual memory and negatively affect performance.

Page Faults

Page faults can occur as MongoDB reads from or writes data to parts of its data files that are not currently located in physical memory. In contrast, operating system page faults happen when physical memory is exhausted and pages of physical memory are swapped to disk.

Page faults triggered by MongoDB are reported as the total number of page faults in one second. To check for page faults, see the extra_info.page_faults value in the serverStatus output.

MongoDB on Windows counts both hard and soft page faults.

The MongoDB page fault counter may increase dramatically in moments of poor performance and may correlate with limited physical memory environments. Page faults also can increase while accessing much larger data sets, for example, scanning an entire collection. Limited and sporadic MongoDB page faults do not necessarily indicate a problem or a need to tune the database.

A single page fault completes quickly and is not problematic. However, in aggregate, large volumes of page faults typically indicate that MongoDB is reading too much data from disk. In many situations, MongoDB’s read locks will “yield” after a page fault to allow other processes to read and avoid blocking while waiting for the next page to read into memory. This approach improves concurrency, and also improves overall throughput in high volume systems.

Increasing the amount of RAM accessible to MongoDB may help reduce the frequency of page faults. If this is not possible, you may want to consider deploying a sharded cluster or adding shards to your deployment to distribute load among mongod instances.

See What are page faults? for more information.

Number of Connections

In some cases, the number of connections between the application layer (i.e. clients) and the database can overwhelm the ability of the server to handle requests. This can produce performance irregularities. The following fields in the serverStatus document can provide insight:

globalLock.activeClients contains a counter of the total number of clients with active operations in progress or queued.

connections is a container for the following two fields:

current the total number of current clients that connect to the database instance.

available the total number of unused collections available for new clients.

If requests are high because there are numerous concurrent application requests, the database may have trouble keeping up with demand. If this is the case, then you will need to increase the capacity of your deployment. For read-heavy applications increase the size of your replica set and distribute read operations to secondary members. For write heavy applications, deploy sharding and add one or more shards to a sharded cluster to distribute load among mongod instances.

Spikes in the number of connections can also be the result of application or driver errors. All of the officially supported MongoDB drivers implement connection pooling, which allows clients to use and reuse connections more efficiently. Extremely high numbers of connections, particularly without corresponding workload is often indicative of a driver or other configuration error.

Unless constrained by system-wide limits MongoDB has no limit on incoming connections. You can modify system limits using the ulimit command, or by editing your system’s /etc/sysctl file. See UNIX ulimit Settings for more information.

Database Profiling

MongoDB’s “Profiler” is a database profiling system that can help identify inefficient queries and operations.

The following profiling levels are available:

Level | Setting
0 | Off. No profiling
1 | On. Only includes “slow” operations
2 | On. Includes all operations

Enable the profiler by setting the profile value using the following command in the mongo shell:

db.setProfilingLevel(1)

The slowOpThresholdMs setting defines what constitutes a “slow” operation. To set the threshold above which the profiler considers operations “slow” (and thus, included in the level 1 profiling data), you can configure slowOpThresholdMs at runtime as an argument to the db.setProfilingLevel() operation.

See

The documentation of db.setProfilingLevel() for more information about this command.

By default, mongod records all “slow” queries to its log, as defined by slowOpThresholdMs.

Note

Because the database profiler can negatively impact performance, only enable profiling for strategic intervals and as minimally as possible on production systems.

You may enable profiling on a per-mongod basis. This setting will not propagate across a replica set or sharded cluster.

You can view the output of the profiler in the system.profile collection of your database by issuing the show profile command in the mongo shell, or with the following operation:

db.system.profile.find( { millis : { $gt : 100 } } )

This returns all operations that lasted longer than 100 milliseconds. Ensure that the value specified here (100, in this example) is above the slowOpThresholdMs threshold.

See also

Optimization Strategies for MongoDB addresses strategies that may improve the performance of your database queries and operations.

Administration Tutorials

The administration tutorials provide specific step-by-step instructions for performing common MongoDB setup, maintenance, and configuration operations.

Configuration, Maintenance, and Analysis

Describes routine management operations, including configuration and performance analysis.

Manage mongod Processes

Start, configure, and manage running mongod process.

Rotate Log Files

Archive the current log files and start new ones.

Continue reading from Configuration, Maintenance, and Analysis for additional tutorials of fundamental MongoDB maintenance procedures.

Backup and Recovery

Outlines procedures for data backup and restoration with mongod instances and deployments.

Backup and Restore with Filesystem Snapshots

An outline of procedures for creating MongoDB data set backups using system-level file snapshot tool, such as LVM or native storage appliance tools.

Backup and Restore Sharded Clusters

Detailed procedures and considerations for backing up sharded clusters and single shards.

Recover Data after an Unexpected Shutdown

Recover data from MongoDB data files that were not properly closed or have an invalid state.

Continue reading from Backup and Recovery for additional tutorials of MongoDB backup and recovery procedures.

MongoDB Scripting

An introduction to the scripting capabilities of the mongo shell and the scripting capabilities embedded in MongoDB instances.

MongoDB Tutorials

A complete list of tutorials in the MongoDB Manual that address MongoDB operation and use.

Configuration, Maintenance, and Analysis

Use Database Commands

Manage mongod Processes

Terminate Running Operations

Analyze Performance of Database Operations

Rotate Log Files

Manage Journaling

Store a JavaScript Function on the Server

Upgrade to the Latest Revision of MongoDB

Monitor MongoDB With SNMP on Linux

Monitor MongoDB Windows with SNMP

Troubleshoot SNMP

Backup and Recovery

Backup and Restore with Filesystem Snapshots

Restore a Replica Set from MongoDB Backups

Back Up and Restore with MongoDB Tools

Backup and Restore Sharded Clusters

Backup a Small Sharded Cluster with mongodump

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Schedule Backup Window for Sharded Clusters

Restore a Single Shard

Restore a Sharded Cluster

Recover Data after an Unexpected Shutdown

MongoDB Scripting

Server-side JavaScript

Data Types in the mongo Shell

Write Scripts for the mongo Shell

Getting Started with the mongo Shell

Access the mongo Shell Help Information

mongo Shell Quick Reference

MongoDB Tutorials

See also

The MongoDB Manual contains administrative documentation and tutorials though out several sections. See Replica Set Tutorials and Sharded Cluster Tutorials for additional tutorials and information.

Configuration, Maintenance, and Analysis

The following tutorials describe routine management operations, including configuration and performance analysis:

Use Database Commands

The process for running database commands that provide basic database operations.

Manage mongod Processes

Start, configure, and manage running mongod process.

Terminate Running Operations

Stop in progress MongoDB client operations using db.killOp() and maxTimeMS().

Analyze Performance of Database Operations

Collect data that introspects the performance of query and update operations on a mongod instance.

Rotate Log Files

Archive the current log files and start new ones.

Manage Journaling

Describes the procedures for configuring and managing MongoDB’s journaling system which allows MongoDB to provide crash resiliency and durability.

Store a JavaScript Function on the Server

Describes how to store JavaScript functions on a MongoDB server.

Upgrade to the Latest Revision of MongoDB

Introduces the basic process for upgrading a MongoDB deployment between different minor release versions.

Monitor MongoDB With SNMP on Linux

The SNMP extension, available in MongoDB Enterprise, allows MongoDB to report data into SNMP traps.

Monitor MongoDB Windows with SNMP

The SNMP extension, available in the Windows build of MongoDB Enterprise, allows MongoDB to report data into SNMP traps.

Troubleshoot SNMP

Outlines common errors and diagnostic processes useful for deploying MongoDB Enterprise with SNMP support.

Use Database Commands

Manage mongod Processes

Terminate Running Operations

Analyze Performance of Database Operations

Rotate Log Files

Manage Journaling

Store a JavaScript Function on the Server

Upgrade to the Latest Revision of MongoDB

Monitor MongoDB With SNMP on Linux

Monitor MongoDB Windows with SNMP

Troubleshoot SNMP

Use Database Commands

The MongoDB command interface provides access to all non CRUD database operations. Fetching server stats, initializing a replica set, and running a map-reduce job are all accomplished with commands.

See Database Commands for list of all commands sorted by function.

Database Command Form

You specify a command first by constructing a standard BSON document whose first key is the name of the command. For example, specify the isMaster command using the following BSON document:

{ isMaster: 1 }

Issue Commands

The mongo shell provides a helper method for running commands called db.runCommand(). The following operation in mongo runs the above command:

db.runCommand( { isMaster: 1 } )

Many drivers provide an equivalent for the db.runCommand() method. Internally, running commands with db.runCommand() is equivalent to a special query against the $cmd collection.

Many common commands have their own shell helpers or wrappers in the mongo shell and drivers, such as the db.isMaster() method in the mongo JavaScript shell.

You can use the maxTimeMS option to specify a time limit for the execution of a command, see Terminate a Command for more information on operation termination.

admin Database Commands

You must run some commands on the admin database. Normally, these operations resemble the followings:

use admin
db.runCommand( {buildInfo: 1} )

However, there’s also a command helper that automatically runs the command in the context of the admin database:

db._adminCommand( {buildInfo: 1} )

Command Responses

All commands return, at minimum, a document with an ok field indicating whether the command has succeeded:

{ 'ok': 1 }

Failed commands return the ok field with a value of 0.

Manage mongod Processes

MongoDB runs as a standard program. You can start MongoDB from a command line by issuing the mongod command and specifying options. For a list of options, see the mongod reference. MongoDB can also run as a Windows service. For details, see Configure a Windows Service for MongoDB. To install MongoDB, see Install MongoDB.

The following examples assume the directory containing the mongod process is in your system paths. The mongod process is the primary database process that runs on an individual server. mongos provides a coherent MongoDB interface equivalent to a mongod from the perspective of a client. The mongo binary provides the administrative shell.

This document page discusses the mongod process; however, some portions of this document may be applicable to mongos instances.

Start mongod Processes

By default, MongoDB stores data in the /data/db directory. On Windows, MongoDB stores data in C:\data\db. On all platforms, MongoDB listens for connections from clients on port 27017.

To start MongoDB using all defaults, issue the following command at the system shell:

mongod

Specify a Data Directory

If you want mongod to store data files at a path other than /data/db you can specify a dbPath. The dbPath must exist before you start mongod. If it does not exist, create the directory and the permissions so that mongod can read and write data to this path. For more information on permissions, see the security operations documentation.

To specify a dbPath for mongod to use as a data directory, use the --dbpath option. The following invocation will start a mongod instance and store data in the /srv/mongodb path

mongod --dbpath /srv/mongodb/

Specify a TCP Port

Only a single process can listen for connections on a network interface at a time. If you run multiple mongod processes on a single machine, or have other processes that must use this port, you must assign each a different port to listen on for client connections.

To specify a port to mongod, use the --port option on the command line. The following command starts mongod listening on port 12345:

mongod --port 12345

Use the default port number when possible, to avoid confusion.

Start mongod as a Daemon

To run a mongod process as a daemon (i.e. fork), and write its output to a log file, use the --fork and --logpath options. You must create the log directory; however, mongod will create the log file if it does not exist.

The following command starts mongod as a daemon and records log output to /var/log/mongodb.log.

mongod --fork --logpath /var/log/mongodb.log

Additional Configuration Options

For an overview of common configurations and common configuration deployments. configurations for common use cases, see Run-time Database Configuration.

Stop mongod Processes

In a clean shutdown a mongod completes all pending operations, flushes all data to data files, and closes all data files. Other shutdowns are unclean and can compromise the validity the data files.

To ensure a clean shutdown, always shutdown mongod instances using one of the following methods:

Use shutdownServer()

Shut down the mongod from the mongo shell using the db.shutdownServer() method as follows:

use admin
db.shutdownServer()

Calling the same method from a control script accomplishes the same result.

For systems with authorization enabled, users may only issue db.shutdownServer() when authenticated to the admin database or via the localhost interface on systems without authentication enabled.

Use --shutdown

From the Linux command line, shut down the mongod using the --shutdown option in the following command:

mongod --shutdown

Use CTRL-C

When running the mongod instance in interactive mode (i.e. without --fork), issue Control-C to perform a clean shutdown.

Use kill

From the Linux command line, shut down a specific mongod instance using the following command:

kill <mongod process ID>

Warning

Never use kill -9 (i.e. SIGKILL) to terminate a mongod instance.

Stop a Replica Set

Procedure

If the mongod is the primary in a replica set, the shutdown process for these mongod instances has the following steps:

Check how up-to-date the secondaries are.

If no secondary is within 10 seconds of the primary, mongod will return a message that it will not shut down. You can pass the shutdown command a timeoutSecs argument to wait for a secondary to catch up.

If there is a secondary within 10 seconds of the primary, the primary will step down and wait for the secondary to catch up.

After 60 seconds or once the secondary has caught up, the primary will shut down.

Force Replica Set Shutdown

If there is no up-to-date secondary and you want the primary to shut down, issue the shutdown command with the force argument, as in the following mongo shell operation:

db.adminCommand({shutdown : 1, force : true})

To keep checking the secondaries for a specified number of seconds if none are immediately up-to-date, issue shutdown with the timeoutSecs argument. MongoDB will keep checking the secondaries for the specified number of seconds if none are immediately up-to-date. If any of the secondaries catch up within the allotted time, the primary will shut down. If no secondaries catch up, it will not shut down.

The following command issues shutdown with timeoutSecs set to 5:

db.adminCommand({shutdown : 1, timeoutSecs : 5})

Alternately you can use the timeoutSecs argument with the db.shutdownServer() method:

db.shutdownServer({timeoutSecs : 5})

Terminate Running Operations

Overview

MongoDB provides two facilitates to terminate running operations: maxTimeMS() and db.killOp(). Use these operations as needed to control the behavior of operations in a MongoDB deployment.

Available Procedures

maxTimeMS

New in version 2.6.

The maxTimeMS() method sets a time limit for an operation. When the operation reaches the specified time limit, MongoDB interrupts the operation at the next interrupt point.

Terminate a Query

From the mongo shell, use the following method to set a time limit of 30 milliseconds for this query:

db.location.find( { "town": { "$regex": "(Pine Lumber)",
                              "$options": 'i' } } ).maxTimeMS(30)

Terminate a Command

Consider a potentially long running operation using distinct to return each distinct``collection`` field that has a city key:

db.runCommand( { distinct: "collection",
                 key: "city" } )

You can add the maxTimeMS field to the command document to set a time limit of 45 milliseconds for the operation:

db.runCommand( { distinct: "collection",
                 key: "city",
                 maxTimeMS: 45 } )

db.getLastError() and db.getLastErrorObj() will return errors for interrupted options:

{ "n" : 0,
  "connectionId" : 1,
  "err" : "operation exceeded time limit",
  "ok" : 1 }

killOp

The db.killOp() method interrupts a running operation at the next interrupt point. db.killOp() identifies the target operation by operation ID.

db.killOp(<opId>)

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

Related

To return a list of running operations see db.currentOp().

Analyze Performance of Database Operations

The database profiler collects fine grained data about MongoDB write operations, cursors, database commands on a running mongod instance. You can enable profiling on a per-database or per-instance basis. The profiling level is also configurable when enabling profiling.

The database profiler writes all the data it collects to the system.profile collection, which is a capped collection. See Database Profiler Output for overview of the data in the system.profile documents created by the profiler.

This document outlines a number of key administration options for the database profiler. For additional related information, consider the following resources:

Database Profiler Output

Profile Command

db.currentOp()

Profiling Levels

The following profiling levels are available:

0 - the profiler is off, does not collect any data. mongod always writes operations longer than the slowOpThresholdMs threshold to its log.

1 - collects profiling data for slow operations only. By default slow operations are those slower than 100 milliseconds.

You can modify the threshold for “slow” operations with the slowOpThresholdMs runtime option or the setParameter command. See the Specify the Threshold for Slow Operations section for more information.

2 - collects profiling data for all database operations.

Enable Database Profiling and Set the Profiling Level

You can enable database profiling from the mongo shell or through a driver using the profile command. This section will describe how to do so from the mongo shell. See your driver documentation if you want to control the profiler from within your application.

When you enable profiling, you also set the profiling level. The profiler records data in the system.profile collection. MongoDB creates the system.profile collection in a database after you enable profiling for that database.

To enable profiling and set the profiling level, use the db.setProfilingLevel() helper in the mongo shell, passing the profiling level as a parameter. For example, to enable profiling for all database operations, consider the following operation in the mongo shell:

db.setProfilingLevel(2)

The shell returns a document showing the previous level of profiling. The "ok" : 1 key-value pair indicates the operation succeeded:

{ "was" : 0, "slowms" : 100, "ok" : 1 }

To verify the new setting, see the Check Profiling Level section.

Specify the Threshold for Slow Operations

The threshold for slow operations applies to the entire mongod instance. When you change the threshold, you change it for all databases on the instance.

Important

Changing the slow operation threshold for the database profiler also affects the profiling subsystem’s slow operation threshold for the entire mongod instance. Always set the threshold to the highest useful value.

By default the slow operation threshold is 100 milliseconds. Databases with a profiling level of 1 will log operations slower than 100 milliseconds.

To change the threshold, pass two parameters to the db.setProfilingLevel() helper in the mongo shell. The first parameter sets the profiling level for the current database, and the second sets the default slow operation threshold for the entire mongod instance.

For example, the following command sets the profiling level for the current database to 0, which disables profiling, and sets the slow-operation threshold for the mongod instance to 20 milliseconds. Any database on the instance with a profiling level of 1 will use this threshold:

db.setProfilingLevel(0,20)

Check Profiling Level

To view the profiling level, issue the following from the mongo shell:

db.getProfilingStatus()

The shell returns a document similar to the following:

{ "was" : 0, "slowms" : 100 }

The was field indicates the current level of profiling.

The slowms field indicates how long an operation must exist in milliseconds for an operation to pass the “slow” threshold. MongoDB will log operations that take longer than the threshold if the profiling level is 1. This document returns the profiling level in the was field. For an explanation of profiling levels, see Profiling Levels.

To return only the profiling level, use the db.getProfilingLevel() helper in the mongo as in the following:

db.getProfilingLevel()

Disable Profiling

To disable profiling, use the following helper in the mongo shell:

db.setProfilingLevel(0)

Enable Profiling for an Entire mongod Instance

For development purposes in testing environments, you can enable database profiling for an entire mongod instance. The profiling level applies to all databases provided by the mongod instance.

To enable profiling for a mongod instance, pass the following parameters to mongod at startup or within the configuration file:

mongod --profile=1 --slowms=15

This sets the profiling level to 1, which collects profiling data for slow operations only, and defines slow operations as those that last longer than 15 milliseconds.

See also

mode and slowOpThresholdMs.

Database Profiling and Sharding

You cannot enable profiling on a mongos instance. To enable profiling in a shard cluster, you must enable profiling for each mongod instance in the cluster.

View Profiler Data

The database profiler logs information about database operations in the system.profile collection.

To view profiling information, query the system.profile collection. You can use $comment to add data to the query document to make it easier to analyze data from the profiler. To view example queries, see Profiler Overhead.

For an explanation of the output data, see Database Profiler Output.

Example Profiler Data Queries

This section displays example queries to the system.profile collection. For an explanation of the query output, see Database Profiler Output.

To return the most recent 10 log entries in the system.profile collection, run a query similar to the following:

db.system.profile.find().limit(10).sort( { ts : -1 } ).pretty()

To return all operations except command operations ($cmd), run a query similar to the following:

db.system.profile.find( { op: { $ne : 'command' } } ).pretty()

To return operations for a particular collection, run a query similar to the following. This example returns operations in the mydb database’s test collection:

db.system.profile.find( { ns : 'mydb.test' } ).pretty()

To return operations slower than 5 milliseconds, run a query similar to the following:

db.system.profile.find( { millis : { $gt : 5 } } ).pretty()

To return information from a certain time range, run a query similar to the following:

db.system.profile.find(
                       {
                        ts : {
                              $gt : new ISODate("2012-12-09T03:00:00Z") ,
                              $lt : new ISODate("2012-12-09T03:40:00Z")
                             }
                       }
                      ).pretty()

The following example looks at the time range, suppresses the user field from the output to make it easier to read, and sorts the results by how long each operation took to run:

db.system.profile.find(
                       {
                         ts : {
                               $gt : new ISODate("2011-07-12T03:00:00Z") ,
                               $lt : new ISODate("2011-07-12T03:40:00Z")
                              }
                       },
                       { user : 0 }
                      ).sort( { millis : -1 } )

Show the Five Most Recent Events

On a database that has profiling enabled, the show profile helper in the mongo shell displays the 5 most recent operations that took at least 1 millisecond to execute. Issue show profile from the mongo shell, as follows:

show profile

Profiler Overhead

When enabled, profiling has a minor effect on performance. The system.profile collection is a capped collection with a default size of 1 megabyte. A collection of this size can typically store several thousand profile documents, but some application may use more or less profiling data per operation.

To change the size of the system.profile collection, you must:

Disable profiling.

Drop the system.profile collection.

Create a new system.profile collection.

Re-enable profiling.

For example, to create a new system.profile collections that’s 4000000 bytes, use the following sequence of operations in the mongo shell:

db.setProfilingLevel(0)

db.system.profile.drop()

db.createCollection( "system.profile", { capped: true, size:4000000 } )

db.setProfilingLevel(1)

Change Size of system.profile Collection

To change the size of the system.profile collection on a secondary, you must stop the secondary, run it as a standalone, and then perform the steps above. When done, restart the standalone as a member of the replica set. For more information, see Perform Maintenance on Replica Set Members.

Rotate Log Files

Overview

Log rotation using MongoDB’s standard approach archives the current log file and starts a new one. To do this, the mongod or mongos instance renames the current log file by appending a UTC (GMT) timestamp to the filename, in ISODate format. It then opens a new log file, closes the old log file, and sends all new log entries to the new log file.

MongoDB’s standard approach to log rotation only rotates logs in response to the logRotate command, or when the mongod or mongos process receives a SIGUSR1 signal from the operating system.

Alternately, you may configure mongod to send log data to syslog. In this case, you can take advantage of alternate logrotation tools.

See also

For information on logging, see the Process Logging section.

Log Rotation With MongoDB

The following steps create and rotate a log file:

Start a mongod with verbose logging, with appending enabled, and with the following log file:

mongod -v --logpath /var/log/mongodb/server1.log --logappend

In a separate terminal, list the matching files:

ls /var/log/mongodb/server1.log*

For results, you get:

server1.log

Rotate the log file using one of the following methods.

From the mongo shell, issue the logRotate command from the admin database:

use admin
db.runCommand( { logRotate : 1 } )

This is the only available method to rotate log files on Windows systems.

For Linux systems, rotate logs for a single process by issuing the following command:

kill -SIGUSR1 <mongod process id>

List the matching files again:

ls /var/log/mongodb/server1.log*

For results you get something similar to the following. The timestamps will be different.

server1.log  server1.log.2011-11-24T23-30-00

The example results indicate a log rotation performed at exactly 11:30 pm on November 24th, 2011 UTC, which is the local time offset by the local time zone. The original log file is the one with the timestamp. The new log is server1.log file.

If you issue a second logRotate command an hour later, then an additional file would appear when listing matching files, as in the following example:

server1.log  server1.log.2011-11-24T23-30-00  server1.log.2011-11-25T00-30-00

This operation does not modify the server1.log.2011-11-24T23-30-00 file created earlier, while server1.log.2011-11-25T00-30-00 is the previous server1.log file, renamed. server1.log is a new, empty file that receives all new log output.

Syslog Log Rotation

New in version 2.2.

To configure mongod to send log data to syslog rather than writing log data to a file, use the following procedure.

Start a mongod with the syslogFacility option.

Store and rotate the log output using your system’s default log rotation mechanism.

Important

You cannot use syslogFacility with systemLog.path.

Manage Journaling

MongoDB uses write ahead logging to an on-disk journal to guarantee write operation durability and to provide crash resiliency. Before applying a change to the data files, MongoDB writes the change operation to the journal. If MongoDB should terminate or encounter an error before it can write the changes from the journal to the data files, MongoDB can re-apply the write operation and maintain a consistent state.

Without a journal, if mongod exits unexpectedly, you must assume your data is in an inconsistent state, and you must run either repair or, preferably, resync from a clean member of the replica set.

With journaling enabled, if mongod stops unexpectedly, the program can recover everything written to the journal, and the data remains in a consistent state. By default, the greatest extent of lost writes, i.e., those not made to the journal, are those made in the last 100 milliseconds. See commitIntervalMs for more information on the default.

With journaling, if you want a data set to reside entirely in RAM, you need enough RAM to hold the data set plus the “write working set.” The “write working set” is the amount of unique data you expect to see written between re-mappings of the private view. For information on views, see Storage Views used in Journaling.

Important

Changed in version 2.0: For 64-bit builds of mongod, journaling is enabled by default. For other platforms, see storage.journal.enabled.

Procedures

Enable Journaling

Changed in version 2.0: For 64-bit builds of mongod, journaling is enabled by default.

To enable journaling, start mongod with the --journal command line option.

If no journal files exist, when mongod starts, it must preallocate new journal files. During this operation, the mongod is not listening for connections until preallocation completes: for some systems this may take a several minutes. During this period your applications and the mongo shell are not available.

Disable Journaling

Warning

Do not disable journaling on production systems. If your mongod instance stops without shutting down cleanly unexpectedly for any reason, (e.g. power failure) and you are not running with journaling, then you must recover from an unaffected replica set member or backup, as described in repair.

To disable journaling, start mongod with the --nojournal command line option.

Get Commit Acknowledgment

You can get commit acknowledgment with the Write Concern and the j option. For details, see Write Concern Reference.

Avoid Preallocation Lag

To avoid preallocation lag, you can preallocate files in the journal directory by copying them from another instance of mongod.

Preallocated files do not contain data. It is safe to later remove them. But if you restart mongod with journaling, mongod will create them again.

Example

The following sequence preallocates journal files for an instance of mongod running on port 27017 with a database path of /data/db.

For demonstration purposes, the sequence starts by creating a set of journal files in the usual way.

Create a temporary directory into which to create a set of journal files:

mkdir ~/tmpDbpath

Create a set of journal files by staring a mongod instance that uses the temporary directory:

mongod --port 10000 --dbpath ~/tmpDbpath --journal

When you see the following log output, indicating mongod has the files, press CONTROL+C to stop the mongod instance:

[initandlisten] waiting for connections on port 10000

Preallocate journal files for the new instance of mongod by moving the journal files from the data directory of the existing instance to the data directory of the new instance:

mv ~/tmpDbpath/journal /data/db/

Start the new mongod instance:

mongod --port 27017 --dbpath /data/db --journal

Monitor Journal Status

Use the following commands and methods to monitor journal status:

serverStatus

The serverStatus command returns database status information that is useful for assessing performance.

journalLatencyTest

Use journalLatencyTest to measure how long it takes on your volume to write to the disk in an append-only fashion. You can run this command on an idle system to get a baseline sync time for journaling. You can also run this command on a busy system to see the sync time on a busy system, which may be higher if the journal directory is on the same volume as the data files.

The journalLatencyTest command also provides a way to check if your disk drive is buffering writes in its local cache. If the number is very low (i.e., less than 2 milliseconds) and the drive is non-SSD, the drive is probably buffering writes. In that case, enable cache write-through for the device in your operating system, unless you have a disk controller card with battery backed RAM.

Change the Group Commit Interval

Changed in version 2.0.

You can set the group commit interval using the --journalCommitInterval command line option. The allowed range is 2 to 300 milliseconds.

Lower values increase the durability of the journal at the expense of disk performance.

Recover Data After Unexpected Shutdown

On a restart after a crash, MongoDB replays all journal files in the journal directory before the server becomes available. If MongoDB must replay journal files, mongod notes these events in the log output.

There is no reason to run repairDatabase in these situations.

Store a JavaScript Function on the Server

Note

Do not store application logic in the database. There are performance limitations to running JavaScript inside of MongoDB. Application code also is typically most effective when it shares version control with the application itself.

There is a special system collection named system.js that can store JavaScript functions for reuse.

To store a function, you can use the db.collection.save(), as in the following example:

db.system.js.save(
   {
     _id : "myAddFunction" ,
     value : function (x, y){ return x + y; }
   }
);

The _id field holds the name of the function and is unique per database.

The value field holds the function definition

Once you save a function in the system.js collection, you can use the function from any JavaScript context (e.g. eval command or the mongo shell method db.eval(), $where operator, mapReduce or mongo shell method db.collection.mapReduce()).

Consider the following example from the mongo shell that first saves a function named echoFunction to the system.js collection and calls the function using db.eval() method:

db.system.js.save(
                   { _id: "echoFunction",
                     value : function(x) { return x; }
                   }
                 )

db.eval( "echoFunction( 'test' )" )

See http://github.com/mongodb/mongo/tree/master/jstests/core/storefunc.js for a full example.

New in version 2.1: In the mongo shell, you can use db.loadServerScripts() to load all the scripts saved in the system.js collection for the current database. Once loaded, you can invoke the functions directly in the shell, as in the following example:

db.loadServerScripts();

echoFunction(3);

myAddFunction(3, 5);

Upgrade to the Latest Revision of MongoDB

Revisions provide security patches, bug fixes, and new or changed features that do not contain any backward breaking changes. Always upgrade to the latest revision in your release series. The third number in the MongoDB version number indicates the revision.

Before Upgrading

Ensure you have an up-to-date backup of your data set. See MongoDB Backup Methods.

Consult the following documents for any special considerations or compatibility issues specific to your MongoDB release:

The release notes, located at Release Notes.

The documentation for your driver. See Drivers [http://docs.mongodb.org/ecosystem/drivers] page for more information.

If your installation includes replica sets, plan the upgrade during a predefined maintenance window.

Before you upgrade a production environment, use the procedures in this document to upgrade a staging environment that reproduces your production environment, to ensure that your production configuration is compatible with all changes.

Upgrade Procedure

Important

Always backup all of your data before upgrading MongoDB.

Upgrade each mongod and mongos binary separately, using the procedure described here. When upgrading a binary, use the procedure Upgrade a MongoDB Instance.

Follow this upgrade procedure:

For deployments that use authentication, first upgrade all of your MongoDB drivers. To upgrade, see the documentation for your driver.

Upgrade sharded clusters, as described in Upgrade Sharded Clusters.

Upgrade any standalone instances. See Upgrade a MongoDB Instance.

Upgrade any replica sets that are not part of a sharded cluster, as described in Upgrade Replica Sets.

Upgrade a MongoDB Instance

To upgrade a mongod or mongos instance, use one of the following approaches:

Upgrade the instance using the operating system’s package management tool and the official MongoDB packages. This is the preferred approach. See Install MongoDB.

Upgrade the instance by replacing the existing binaries with new binaries. See Replace the Existing Binaries.

Replace the Existing Binaries

Important

Always backup all of your data before upgrading MongoDB.

This section describes how to upgrade MongoDB by replacing the existing binaries. The preferred approach to an upgrade is to use the operating system’s package management tool and the official MongoDB packages, as described in Install MongoDB.

To upgrade a mongod or mongos instance by replacing the existing binaries:

Download the binaries for the latest MongoDB revision from the MongoDB Download Page [http://downloads.mongodb.org/] and store the binaries in a temporary location. The binaries download as compressed files that uncompress to the directory structure used by the MongoDB installation.

Shutdown the instance.

Replace the existing MongoDB binaries with the downloaded binaries.

Restart the instance.

Upgrade Sharded Clusters

To upgrade a sharded cluster:

Disable the cluster’s balancer, as described in Disable the Balancer.

Upgrade each mongos instance by following the instructions below in Upgrade a MongoDB Instance. You can upgrade the mongos instances in any order.

Upgrade each mongod config server individually starting with the last config server listed in your mongos --configdb string and working backward. To keep the cluster online, make sure at least one config server is always running. For each config server upgrade, follow the instructions below in Upgrade a MongoDB Instance

Example

Given the following config string:

mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019

You would upgrade the config servers in the following order:

cfg2.example.net

cfg1.example.net

cfg0.example.net

Upgrade each shard.

If a shard is a replica set, upgrade the shard using the procedure below titled Upgrade Replica Sets.

If a shard is a standalone instance, upgrade the shard using the procedure below titled Upgrade a MongoDB Instance.

Re-enable the balancer, as described in Enable the Balancer.

Upgrade Replica Sets

To upgrade a replica set, upgrade each member individually, starting with the secondaries and finishing with the primary. Plan the upgrade during a predefined maintenance window.

Upgrade Secondaries

Upgrade each secondary separately as follows:

Upgrade the secondary’s mongod binary by following the instructions below in Upgrade a MongoDB Instance.

After upgrading a secondary, wait for the secondary to recover to the SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

The secondary may briefly go into STARTUP2 or RECOVERING. This is normal. Make sure to wait for the secondary to fully recover to SECONDARY before you continue the upgrade.

Upgrade the Primary

Step down the primary to initiate the normal failover procedure. Using one of the following:

The rs.stepDown() helper in the mongo shell.

The replSetStepDown database command.

During failover, the set cannot accept writes. Typically this takes 10-20 seconds. Plan the upgrade during a predefined maintenance window.

Note

Stepping down the primary is preferable to directly shutting down the primary. Stepping down expedites the failover procedure.

Once the primary has stepped down, call the rs.status() method from the mongo shell until you see that another member has assumed the PRIMARY state.

Shut down the original primary and upgrade its instance by following the instructions below in Upgrade a MongoDB Instance.

Monitor MongoDB With SNMP on Linux

New in version 2.2.

Enterprise Feature

SNMP is only available in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

Overview

MongoDB Enterprise can provide database metrics via SNMP, in support of centralized data collection and aggregation. This procedure explains the setup and configuration of a mongod instance as an SNMP subagent, as well as initializing and testing of SNMP support with MongoDB Enterprise.

See also

Troubleshoot SNMP and Monitor MongoDB Windows with SNMP for complete instructions on using MongoDB with SNMP on Windows systems.

Considerations

Only mongod instances provide SNMP support. mongos and the other MongoDB binaries do not support SNMP.

Configuration Files

Changed in version 2.6.

MongoDB Enterprise contains the following configuration files to support SNMP:

MONGOD-MIB.txt:

The management information base (MIB) file that defines MongoDB’s SNMP output.

mongod.conf.subagent:

The configuration file to run mongod as the SNMP subagent. This file sets SNMP run-time configuration options, including the AgentX socket to connect to the SNMP master.

mongod.conf.master:

The configuration file to run mongod as the SNMP master. This file sets SNMP run-time configuration options.

Procedure

1

Copy configuration files.

Use the following sequence of commands to move the SNMP configuration files to the SNMP service configuration directory.

First, create the SNMP configuration directory if needed and then, from the installation directory, copy the configuration files to the SNMP service configuration directory:

mkdir -p /etc/snmp/
cp MONGOD-MIB.txt /usr/share/snmp/mibs/MONGOD-MIB.txt
cp mongod.conf.subagent /etc/snmp/mongod.conf

The configuration filename is tool-dependent. For example, when using net-snmp the configuration file is snmpd.conf.

By default SNMP uses UNIX domain for communication between the agent (i.e. snmpd or the master) and sub-agent (i.e. MongoDB).

Ensure that the agentXAddress specified in the SNMP configuration file for MongoDB matches the agentXAddress in the SNMP master configuration file.

Step 1: Copy configuration files.

Use the following sequence of commands to move the SNMP configuration files to the SNMP service configuration directory.

First, create the SNMP configuration directory if needed and then, from the installation directory, copy the configuration files to the SNMP service configuration directory:

mkdir -p /etc/snmp/
cp MONGOD-MIB.txt /usr/share/snmp/mibs/MONGOD-MIB.txt
cp mongod.conf.subagent /etc/snmp/mongod.conf

The configuration filename is tool-dependent. For example, when using net-snmp the configuration file is snmpd.conf.

By default SNMP uses UNIX domain for communication between the agent (i.e. snmpd or the master) and sub-agent (i.e. MongoDB).

Ensure that the agentXAddress specified in the SNMP configuration file for MongoDB matches the agentXAddress in the SNMP master configuration file.

2

Start MongoDB.

Start mongod with the snmp-subagent to send data to the SNMP master.

mongod --snmp-subagent

Step 2: Start MongoDB.

Start mongod with the snmp-subagent to send data to the SNMP master.

mongod --snmp-subagent

3

Confirm SNMP data retrieval.

Use snmpwalk to collect data from mongod:

Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.

Install the net-snmp [http://www.net-snmp.org/] package to access the snmpwalk client. net-snmp provides the snmpwalk SNMP client.

snmpwalk -m /usr/share/snmp/mibs/MONGOD-MIB.txt -v 2c -c mongodb 127.0.0.1:<port> 1.3.6.1.4.1.34601

<port> refers to the port defined by the SNMP master, not the primary port used by mongod for client communication.

Step 3: Confirm SNMP data retrieval.

Use snmpwalk to collect data from mongod:

Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.

Install the net-snmp [http://www.net-snmp.org/] package to access the snmpwalk client. net-snmp provides the snmpwalk SNMP client.

snmpwalk -m /usr/share/snmp/mibs/MONGOD-MIB.txt -v 2c -c mongodb 127.0.0.1:<port> 1.3.6.1.4.1.34601

<port> refers to the port defined by the SNMP master, not the primary port used by mongod for client communication.

Optional: Run MongoDB as SNMP Master

You can run mongod with the snmp-master option for testing purposes. To do this, use the SNMP master configuration file instead of the subagent configuration file. From the directory containing the unpacked MongoDB installation files:

cp mongod.conf.master /etc/snmp/mongod.conf

Additionally, start mongod with the snmp-master option, as in the following:

mongod --snmp-master

Monitor MongoDB Windows with SNMP

New in version 2.6.

Enterprise Feature

SNMP is only available in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

Overview

MongoDB Enterprise can report system information into SNMP traps, to support centralized data collection and aggregation. This procedure explains the setup and configuration of a mongod.exe instance as an SNMP subagent, as well as initializing and testing of SNMP support with MongoDB Enterprise.

See also

Monitor MongoDB With SNMP on Linux and Troubleshoot SNMP for more information.

Considerations

Only mongod.exe instances provide SNMP support. mongos.exe and the other MongoDB binaries do not support SNMP.

Configuration Files

Changed in version 2.6.

MongoDB Enterprise contains the following configuration files to support SNMP:

MONGOD-MIB.txt:

The management information base (MIB) file that defines MongoDB’s SNMP output.

mongod.conf.subagent:

The configuration file to run mongod.exe as the SNMP subagent. This file sets SNMP run-time configuration options, including the AgentX socket to connect to the SNMP master.

mongod.conf.master:

The configuration file to run mongod.exe as the SNMP master. This file sets SNMP run-time configuration options.

Procedure

1

Copy configuration files.

Use the following sequence of commands to move the SNMP configuration files to the SNMP service configuration directory.

First, create the SNMP configuration directory if needed and then, from the installation directory, copy the configuration files to the SNMP service configuration directory:

md C:\snmp\etc\config
copy MONGOD-MIB.txt C:\snmp\etc\config\MONGOD-MIB.txt
copy mongod.conf.subagent C:\snmp\etc\config\mongod.conf

The configuration filename is tool-dependent. For example, when using net-snmp the configuration file is snmpd.conf.

Edit the configuration file to ensure that the communication between the agent (i.e. snmpd or the master) and sub-agent (i.e. MongoDB) uses TCP.

Ensure that the agentXAddress specified in the SNMP configuration file for MongoDB matches the agentXAddress in the SNMP master configuration file.

Step 1: Copy configuration files.

Use the following sequence of commands to move the SNMP configuration files to the SNMP service configuration directory.

First, create the SNMP configuration directory if needed and then, from the installation directory, copy the configuration files to the SNMP service configuration directory:

md C:\snmp\etc\config
copy MONGOD-MIB.txt C:\snmp\etc\config\MONGOD-MIB.txt
copy mongod.conf.subagent C:\snmp\etc\config\mongod.conf

The configuration filename is tool-dependent. For example, when using net-snmp the configuration file is snmpd.conf.

Edit the configuration file to ensure that the communication between the agent (i.e. snmpd or the master) and sub-agent (i.e. MongoDB) uses TCP.

Ensure that the agentXAddress specified in the SNMP configuration file for MongoDB matches the agentXAddress in the SNMP master configuration file.

2

Start MongoDB.

Start mongod.exe with the snmp-subagent to send data to the SNMP master.

mongod.exe --snmp-subagent

Step 2: Start MongoDB.

Start mongod.exe with the snmp-subagent to send data to the SNMP master.

mongod.exe --snmp-subagent

3

Confirm SNMP data retrieval.

Use snmpwalk to collect data from mongod.exe:

Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.

Install the net-snmp [http://www.net-snmp.org/] package to access the snmpwalk client. net-snmp provides the snmpwalk SNMP client.

snmpwalk -m C:\snmp\etc\config\MONGOD-MIB.txt -v 2c -c mongodb 127.0.0.1:<port> 1.3.6.1.4.1.34601

<port> refers to the port defined by the SNMP master, not the primary port used by mongod.exe for client communication.

Step 3: Confirm SNMP data retrieval.

Use snmpwalk to collect data from mongod.exe:

Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.

Install the net-snmp [http://www.net-snmp.org/] package to access the snmpwalk client. net-snmp provides the snmpwalk SNMP client.

snmpwalk -m C:\snmp\etc\config\MONGOD-MIB.txt -v 2c -c mongodb 127.0.0.1:<port> 1.3.6.1.4.1.34601

<port> refers to the port defined by the SNMP master, not the primary port used by mongod.exe for client communication.

Optional: Run MongoDB as SNMP Master

You can run mongod.exe with the snmp-master option for testing purposes. To do this, use the SNMP master configuration file instead of the subagent configuration file. From the directory containing the unpacked MongoDB installation files:

copy mongod.conf.master C:\snmp\etc\config\mongod.conf

Additionally, start mongod.exe with the snmp-master option, as in the following:

mongod.exe --snmp-master

Troubleshoot SNMP

New in version 2.6.

Enterprise Feature

SNMP is only available in MongoDB Enterprise.

Overview

MongoDB Enterprise can report system information into SNMP traps, to support centralized data collection and aggregation. This document identifies common problems you may encounter when deploying MongoDB Enterprise with SNMP as well as possible solutions for these issues.

See Monitor MongoDB With SNMP on Linux and Monitor MongoDB Windows with SNMP for complete installation instructions.

Issues

Failed to Connect

The following in the mongod logfile:

Warning: Failed to connect to the agentx master agent

AgentX is the SNMP agent extensibility protocol defined in Internet RFC 2741 [http://www.ietf.org/rfc/rfc2741.txt]. It explains how to define additional data to monitor over SNMP. When MongoDB fails to connect to the agentx master agent, use the following procedure to ensure that the SNMP subagent can connect properly to the SNMP master.

Make sure the master agent is running.

Compare the SNMP master’s configuration file with the subagent configuration file. Ensure that the agentx socket definition is the same between the two.

Check the SNMP configuration files to see if they specify using UNIX Domain Sockets. If so, confirm that the mongod has appropriate permissions to open a UNIX domain socket.

Error Parsing Command Line

One of the following errors at the command line:

Error parsing command line: unknown option snmp-master
try 'mongod --help' for more information

Error parsing command line: unknown option snmp-subagent
try 'mongod --help' for more information

mongod binaries that are not part of the Enterprise Edition produce this error. Install the Enterprise Edition and attempt to start mongod again.

Other MongoDB binaries, including mongos will produce this error if you attempt to star them with snmp-master or snmp-subagent. Only mongod supports SNMP.

Error Starting SNMPAgent

The following line in the log file indicates that mongod cannot read the mongod.conf file:

[SNMPAgent] warning: error starting SNMPAgent as master err:1

If running on Linux, ensure mongod.conf exists in the /etc/snmp directory, and ensure that the mongod UNIX user has permission to read the mongod.conf file.

If running on Windows, ensure mongod.conf exists in C:\snmp\etc\config.

Backup and Recovery

The following tutorials describe backup and restoration for a mongod instance:

Backup and Restore with Filesystem Snapshots

An outline of procedures for creating MongoDB data set backups using system-level file snapshot tool, such as LVM or native storage appliance tools.

Restore a Replica Set from MongoDB Backups

Describes procedure for restoring a replica set from an archived backup such as a mongodump or MMS [https://mms.mongodb.com/] Backup file.

Back Up and Restore with MongoDB Tools

The procedure for writing the contents of a database to a BSON (i.e. binary) dump file for backing up MongoDB databases.

Backup and Restore Sharded Clusters

Detailed procedures and considerations for backing up sharded clusters and single shards.

Recover Data after an Unexpected Shutdown

Recover data from MongoDB data files that were not properly closed or have an invalid state.

Backup and Restore with Filesystem Snapshots

Restore a Replica Set from MongoDB Backups

Back Up and Restore with MongoDB Tools

Backup and Restore Sharded Clusters

Backup a Small Sharded Cluster with mongodump

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Schedule Backup Window for Sharded Clusters

Restore a Single Shard

Restore a Sharded Cluster

Recover Data after an Unexpected Shutdown

Backup and Restore with Filesystem Snapshots

This document describes a procedure for creating backups of MongoDB systems using system-level tools, such as LVM or storage appliance, as well as the corresponding restoration strategies.

These filesystem snapshots, or “block-level” backup methods use system level tools to create copies of the device that holds MongoDB’s data files. These methods complete quickly and work reliably, but require more system configuration outside of MongoDB.

See also

MongoDB Backup Methods and Back Up and Restore with MongoDB Tools.

Snapshots Overview

Snapshots work by creating pointers between the live data and a special snapshot volume. These pointers are theoretically equivalent to “hard links.” As the working data diverges from the snapshot, the snapshot process uses a copy-on-write strategy. As a result the snapshot only stores modified data.

After making the snapshot, you mount the snapshot image on your file system and copy data from the snapshot. The resulting backup contains a full copy of all data.

Snapshots have the following limitations:

The database must be valid when the snapshot takes place. This means that all writes accepted by the database need to be fully written to disk: either to the journal or to data files.

If all writes are not on disk when the backup occurs, the backup will not reflect these changes. If writes are in progress when the backup occurs, the data files will reflect an inconsistent state. With journaling all data-file states resulting from in-progress writes are recoverable; without journaling you must flush all pending writes to disk before running the backup operation and must ensure that no writes occur during the entire backup procedure.

If you do use journaling, the journal must reside on the same volume as the data.

Snapshots create an image of an entire disk image. Unless you need to back up your entire system, consider isolating your MongoDB data files, journal (if applicable), and configuration on one logical disk that doesn’t contain any other data.

Alternately, store all MongoDB data files on a dedicated device so that you can make backups without duplicating extraneous data.

Ensure that you copy data from snapshots and onto other systems to ensure that data is safe from site failures.

Although different snapshots methods provide different capability, the LVM method outlined below does not provide any capacity for capturing incremental backups.

Snapshots With Journaling

If your mongod instance has journaling enabled, then you can use any kind of file system or volume/block level snapshot tool to create backups.

If you manage your own infrastructure on a Linux-based system, configure your system with LVM to provide your disk packages and provide snapshot capability. You can also use LVM-based setups within a cloud/virtualized environment.

Note

Running LVM provides additional flexibility and enables the possibility of using snapshots to back up MongoDB.

Snapshots with Amazon EBS in a RAID 10 Configuration

If your deployment depends on Amazon’s Elastic Block Storage (EBS) with RAID configured within your instance, it is impossible to get a consistent state across all disks using the platform’s snapshot tool. As an alternative, you can do one of the following:

Flush all writes to disk and create a write lock to ensure consistent state during the backup process.

If you choose this option see Create Backups on Instances that do not have Journaling Enabled.

Configure LVM to run and hold your MongoDB data files on top of the RAID within your system.

If you choose this option, perform the LVM backup operation described in Create a Snapshot.

Backup and Restore Using LVM on a Linux System

This section provides an overview of a simple backup process using LVM on a Linux system. While the tools, commands, and paths may be (slightly) different on your system the following steps provide a high level overview of the backup operation.

Note

Only use the following procedure as a guideline for a backup system and infrastructure. Production backup systems must consider a number of application specific requirements and factors unique to specific environments.

Create a Snapshot

To create a snapshot with LVM, issue a command as root in the following format:

lvcreate --size 100M --snapshot --name mdb-snap01 /dev/vg0/mongodb

This command creates an LVM snapshot (with the --snapshot option) named mdb-snap01 of the mongodb volume in the vg0 volume group.

This example creates a snapshot named mdb-snap01 located at /dev/vg0/mdb-snap01. The location and paths to your systems volume groups and devices may vary slightly depending on your operating system’s LVM configuration.

The snapshot has a cap of at 100 megabytes, because of the parameter --size 100M. This size does not reflect the total amount of the data on the disk, but rather the quantity of differences between the current state of /dev/vg0/mongodb and the creation of the snapshot (i.e. /dev/vg0/mdb-snap01.)

Warning

Ensure that you create snapshots with enough space to account for data growth, particularly for the period of time that it takes to copy data out of the system or to a temporary image.

If your snapshot runs out of space, the snapshot image becomes unusable. Discard this logical volume and create another.

The snapshot will exist when the command returns. You can restore directly from the snapshot at any time or by creating a new logical volume and restoring from this snapshot to the alternate image.

While snapshots are great for creating high quality backups very quickly, they are not ideal as a format for storing backup data. Snapshots typically depend and reside on the same storage infrastructure as the original disk images. Therefore, it’s crucial that you archive these snapshots and store them elsewhere.

Archive a Snapshot

After creating a snapshot, mount the snapshot and copy the data to separate storage. Your system might try to compress the backup images as you move the offline. Alternatively, take a block level copy of the snapshot image, such as with the following procedure:

umount /dev/vg0/mdb-snap01
dd if=/dev/vg0/mdb-snap01 | gzip > mdb-snap01.gz

The above command sequence does the following:

Ensures that the /dev/vg0/mdb-snap01 device is not mounted. Never take a block level copy of a filesystem or filesystem snapshot that is mounted.

Performs a block level copy of the entire snapshot image using the dd command and compresses the result in a gzipped file in the current working directory.

Warning

This command will create a large gz file in your current working directory. Make sure that you run this command in a file system that has enough free space.

Restore a Snapshot

To restore a snapshot created with the above method, issue the following sequence of commands:

lvcreate --size 1G --name mdb-new vg0
gzip -d -c mdb-snap01.gz | dd of=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb

The above sequence does the following:

Creates a new logical volume named mdb-new, in the /dev/vg0 volume group. The path to the new device will be /dev/vg0/mdb-new.

Warning

This volume will have a maximum size of 1 gigabyte. The original file system must have had a total size of 1 gigabyte or smaller, or else the restoration will fail.

Change 1G to your desired volume size.

Uncompresses and unarchives the mdb-snap01.gz into the mdb-new disk image.

Mounts the mdb-new disk image to the /srv/mongodb directory. Modify the mount point to correspond to your MongoDB data file location, or other location as needed.

Note

The restored snapshot will have a stale mongod.lock file. If you do not remove this file from the snapshot, and MongoDB may assume that the stale lock file indicates an unclean shutdown. If you’re running with storage.journal.enabled enabled, and you do not use db.fsyncLock(), you do not need to remove the mongod.lock file. If you use db.fsyncLock() you will need to remove the lock.

Restore Directly from a Snapshot

To restore a backup without writing to a compressed gz file, use the following sequence of commands:

umount /dev/vg0/mdb-snap01
lvcreate --size 1G --name mdb-new vg0
dd if=/dev/vg0/mdb-snap01 of=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb

Remote Backup Storage

You can implement off-system backups using the combined process and SSH.

This sequence is identical to procedures explained above, except that it archives and compresses the backup on a remote system using SSH.

Consider the following procedure:

umount /dev/vg0/mdb-snap01
dd if=/dev/vg0/mdb-snap01 | ssh username@example.com gzip > /opt/backup/mdb-snap01.gz
lvcreate --size 1G --name mdb-new vg0
ssh username@example.com gzip -d -c /opt/backup/mdb-snap01.gz | dd of=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb

Create Backups on Instances that do not have Journaling Enabled

If your mongod instance does not run with journaling enabled, or if your journal is on a separate volume, obtaining a functional backup of a consistent state is more complicated. As described in this section, you must flush all writes to disk and lock the database to prevent writes during the backup process. If you have a replica set configuration, then for your backup use a secondary which is not receiving reads (i.e. hidden member).

Important

In the following procedure, you must issue the db.fsyncLock() and db.fsyncUnlock() operations on the same connection. The client that issues db.fsyncLock() is solely responsible for issuing a db.fsyncUnlock() operation and must be able to handle potential error conditions so that it can perform the db.fsyncUnlock() before terminating the connection.

1

Flush writes to disk and lock the database to prevent further writes.

To flush writes to disk and to “lock” the database, issue the db.fsyncLock() method in the mongo shell:

db.fsyncLock();

Step 1: Flush writes to disk and lock the database to prevent further writes.

To flush writes to disk and to “lock” the database, issue the db.fsyncLock() method in the mongo shell:

db.fsyncLock();

2

Perform the backup operation described in Create a Snapshot.

Step 2: Perform the backup operation described in Create a Snapshot.

3

After the snapshot completes, unlock the database.

To unlock the database after the snapshot has completed, use the following command in the mongo shell:

db.fsyncUnlock();

Changed in version 2.2: When used in combination with fsync or db.fsyncLock(), mongod will block reads, including those from mongodump, when queued write operation waits behind the fsync lock. Do not use mongodump with db.fsyncLock().

Step 3: After the snapshot completes, unlock the database.

To unlock the database after the snapshot has completed, use the following command in the mongo shell:

db.fsyncUnlock();

Changed in version 2.2: When used in combination with fsync or db.fsyncLock(), mongod will block reads, including those from mongodump, when queued write operation waits behind the fsync lock. Do not use mongodump with db.fsyncLock().

Restore a Replica Set from MongoDB Backups

This procedure outlines the process for taking MongoDB data and restoring that data into a new replica set. Use this approach for seeding test deployments from production backups as well as part of disaster recovery.

You cannot restore a single data set to three new mongod instances and then create a replica set. In this situation MongoDB will force the secondaries to perform an initial sync. The procedures in this document describe the correct and efficient ways to deploy a replica set.

Restore Database into a Single Node Replica Set

1

Obtain backup MongoDB Database files.

The backup files may come from a file system snapshot. The MongoDB Management Service (MMS) [https://mms.mongodb.com/] produces MongoDB database files for stored snapshots [https://docs.mms.mongodb.com/tutorial/restore-from-snapshot/] and point in time snapshots [https://docs.mms.mongodb.com/tutorial/restore-from-point-in-time-snapshot/]. You can also use mongorestore to restore database files using data created with mongodump. See Back Up and Restore with MongoDB Tools for more information.

Step 1: Obtain backup MongoDB Database files.

The backup files may come from a file system snapshot. The MongoDB Management Service (MMS) [https://mms.mongodb.com/] produces MongoDB database files for stored snapshots [https://docs.mms.mongodb.com/tutorial/restore-from-snapshot/] and point in time snapshots [https://docs.mms.mongodb.com/tutorial/restore-from-point-in-time-snapshot/]. You can also use mongorestore to restore database files using data created with mongodump. See Back Up and Restore with MongoDB Tools for more information.

2

Start a mongod using data files from the backup as the data path.

The following example uses /data/db as the data path, as specified in the dbpath setting:

mongod --dbpath /data/db

Step 2: Start a mongod using data files from the backup as the data path.

The following example uses /data/db as the data path, as specified in the dbpath setting:

mongod --dbpath /data/db

3

Convert the standalone mongod to a single-node replica set

Convert the standalone mongod process to a single-node replica set by shutting down the mongod instance, and restarting it with the --replSet option, as in the following example:

mongod --dbpath /data/db --replSet <replName>

Optionally, you can explicitly set a oplogSizeMB to control the size of the oplog created for this replica set member.

Step 3: Convert the standalone mongod to a single-node replica set

Convert the standalone mongod process to a single-node replica set by shutting down the mongod instance, and restarting it with the --replSet option, as in the following example:

mongod --dbpath /data/db --replSet <replName>

Optionally, you can explicitly set a oplogSizeMB to control the size of the oplog created for this replica set member.

4

Connect to the mongod instance.

For example, first use the following command to a mongod instance running on the localhost interface:

mongo

Step 4: Connect to the mongod instance.

For example, first use the following command to a mongod instance running on the localhost interface:

mongo

5

Initiate the new replica set.

Use rs.initiate() to initiate the new replica set, as in the following example:

rs.initiate()

Step 5: Initiate the new replica set.

Use rs.initiate() to initiate the new replica set, as in the following example:

rs.initiate()

Add Members to the Replica Set

MongoDB provides two options for restoring secondary members of a replica set:

Manually copy the database files to each data directory.

Allow initial sync to distribute data automatically.

The following sections outlines both approaches.

Note

If your database is large, initial sync can take a long time to complete. For large databases, it might be preferable to copy the database files onto each host.

Copy Database Files and Restart mongod Instance

Use the following sequence of operations to “seed” additional members of the replica set with the restored data by copying MongoDB data files directly.

1

Shut down the mongod instance that you restored.

Use --shutdown or db.shutdownServer() to ensure a clean shut down.

Step 1: Shut down the mongod instance that you restored.

Use --shutdown or db.shutdownServer() to ensure a clean shut down.

2

Copy the primary’s data directory to each secondary.

Copy the primary’s data directory into the dbPath of the other members of the replica set. The dbPath is /data/db by default.

Step 2: Copy the primary’s data directory to each secondary.

Copy the primary’s data directory into the dbPath of the other members of the replica set. The dbPath is /data/db by default.

3

Start the mongod instance that you restored.

Step 3: Start the mongod instance that you restored.

4

Add the secondaries to the replica set.

In a mongo shell connected to the primary, add the secondaries to the replica set using rs.add(). See Deploy a Replica Set for more information about deploying a replica set.

Step 4: Add the secondaries to the replica set.

In a mongo shell connected to the primary, add the secondaries to the replica set using rs.add(). See Deploy a Replica Set for more information about deploying a replica set.

Update Secondaries using Initial Sync

Use the following sequence of operations to “seed” additional members of the replica set with the restored data using the default initial sync operation.

1

Ensure that the data directories on the prospective replica set members are empty.

Step 1: Ensure that the data directories on the prospective replica set members are empty.

2

Add each prospective member to the replica set.

When you add a member to the replica set, Initial Sync copies the data from the primary to the new member.

Step 2: Add each prospective member to the replica set.

When you add a member to the replica set, Initial Sync copies the data from the primary to the new member.

Back Up and Restore with MongoDB Tools

This document describes the process for writing and restoring backups to files in binary format with the mongodump and mongorestore tools.

Use these tools for backups if other backup methods, such as the MMS Backup Service [https://mms.mongodb.com/] or file system snapshots are unavailable.

See also

MongoDB Backup Methods, mongodump, and mongorestore.

Backup a Database with mongodump

mongodump does not dump the content of the local database.

To backup all the databases in a cluster via mongodump, you should have the backup role. The backup role provides all the needed privileges for backing up all database. The role confers no additional access, in keeping with the policy of least privilege.

To backup a given database, you must have read access on the database. Several roles provide this access, including the backup role.

To backup the system.profile collection in a database, you must have read access on certain system collections in the database. Several roles provide this access, including the clusterAdmin and dbAdmin roles.

Changed in version 2.6.

To backup users and user-defined roles for a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to backup a given database’s users, you must have the find action on the admin database’s admin.system.users collection. The backup and userAdminAnyDatabase roles both provide this privilege.

To backup the user-defined roles on a database, you must have the find action on the admin database’s admin.system.roles collection. Both the backup and userAdminAnyDatabase roles provide this privilege.

Basic mongodump Operations

The mongodump utility can back up data by either:

connecting to a running mongod or mongos instance, or

accessing data files without an active instance.

The utility can create a backup for an entire server, database or collection, or can use a query to backup just part of a collection.

When you run mongodump without any arguments, the command connects to the MongoDB instance on the local system (e.g. 127.0.0.1 or localhost) on port 27017 and creates a database backup named dump/ in the current directory.

To backup data from a mongod or mongos instance running on the same machine and on the default port of 27017, use the following command:

mongodump

The data format used by mongodump from version 2.2 or later is incompatible with earlier versions of mongod. Do not use recent versions of mongodump to back up older data stores.

You can also specify the --host and --port of the MongoDB instance that the mongodump should connect to. For example:

mongodump --host mongodb.example.net --port 27017

mongodump will write BSON files that hold a copy of data accessible via the mongod listening on port 27017 of the mongodb.example.net host. See Create Backups from Non-Local mongod Instances for more information.

To use mongodump without a running MongoDB instance, specify the --dbpath option to read directly from MongoDB data files. See Create Backups Without a Running mongod Instance for details.

To specify a different output directory, you can use the --out or -o option:

mongodump --out /data/backup/

To limit the amount of data included in the database dump, you can specify --db and --collection as options to mongodump. For example:

mongodump --collection myCollection --db test

This operation creates a dump of the collection named myCollection from the database test in a dump/ subdirectory of the current working directory.

mongodump overwrites output files if they exist in the backup data folder. Before running the mongodump command multiple times, either ensure that you no longer need the files in the output folder (the default is the dump/ folder) or rename the folders or files.

Point in Time Operation Using Oplogs

Use the --oplog option with mongodump to collect the oplog entries to build a point-in-time snapshot of a database within a replica set. With --oplog, mongodump copies all the data from the source database as well as all of the oplog entries from the beginning to the end of the backup procedure. This operation, in conjunction with mongorestore --oplogReplay, allows you to restore a backup that reflects the specific moment in time that corresponds to when mongodump completed creating the dump file.

Create Backups Without a Running mongod Instance

If your MongoDB instance is not running, you can use the --dbpath option to specify the location to your MongoDB instance’s database files. mongodump reads from the data files directly with this operation. This locks the data directory to prevent conflicting writes. The mongod process must not be running or attached to these data files when you run mongodump in this configuration. Consider the following example:

Given a MongoDB instance that contains the customers, products, and suppliers databases, the following mongodump operation backs up the databases using the --dbpath option, which specifies the location of the database files on the host:

mongodump --dbpath /data -o dataout

The --out or -o option allows you to specify the directory where mongodump will save the backup. mongodump creates a separate backup directory for each of the backed up databases: dataout/customers, dataout/products, and dataout/suppliers.

Create Backups from Non-Local mongod Instances

The --host and --port options for mongodump allow you to connect to and backup from a remote host. Consider the following example:

mongodump --host mongodb1.example.net --port 3017 --username user --password pass --out /opt/backup/mongodump-2013-10-24

On any mongodump command you may, as above, specify username and password credentials to specify database authentication.

Restore a Database with mongorestore

Changed in version 2.6.

To restore users and user-defined roles on a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to restore users to a given database, you must have the insert action on the admin database’s admin.system.users collection. The restore role provides this privilege.

To restore user-defined roles to a database, you must have the insert action on the admin database’s admin.system.roles collection. The restore role provides this privilege.

Basic mongorestore Operations

The mongorestore utility restores a binary backup created by mongodump. By default, mongorestore looks for a database backup in the dump/ directory.

The mongorestore utility can restore data either by:

connecting to a running mongod or mongos directly, or

writing to a set of MongoDB data files without use of a running mongod.

mongorestore can restore either an entire database backup or a subset of the backup.

To use mongorestore to connect to an active mongod or mongos, use a command with the following prototype form:

mongorestore --port <port number> <path to the backup>

To use mongorestore to write to data files without using a running mongod, use a command with the following prototype form:

mongorestore --dbpath <database path> <path to the backup>

Consider the following example:

mongorestore dump-2013-10-25/

Here, mongorestore imports the database backup in the dump-2013-10-25 directory to the mongod instance running on the localhost interface.

Restore Point in Time Oplog Backup

If you created your database dump using the --oplog option to ensure a point-in-time snapshot, call mongorestore with the --oplogReplay option, as in the following example:

mongorestore --oplogReplay

You may also consider using the mongorestore --objcheck option to check the integrity of objects while inserting them into the database, or you may consider the mongorestore --drop option to drop each collection from the database before restoring from backups.

Restore a Subset of data from a Binary Database Dump

mongorestore also includes the ability to a filter to all input before inserting it into the new database. Consider the following example:

mongorestore --filter '{"field": 1}'

Here, mongorestore only adds documents to the database from the dump located in the dump/ folder if the documents have a field name field that holds a value of 1. Enclose the filter in single quotes (e.g. ') to prevent the filter from interacting with your shell environment.

Restore Without a Running mongod

mongorestore can write data to MongoDB data files without needing to connect to a mongod directly.

Example

Restore a Database Without a Running mongod

Given a set of backed up databases in the /data/backup/ directory:

/data/backup/customers,

/data/backup/products, and

/data/backup/suppliers

The following mongorestore command restores the products database. The command uses the --dbpath option to specify the path to the MongoDB data files:

mongorestore --dbpath /data/db --journal /data/backup/products

The mongorestore imports the database backup in the /data/backup/products directory to the mongod instance that runs on the localhost interface. The mongorestore operation imports the backup even if the mongod is not running.

The --journal option ensures that mongorestore records all operation in the durability journal. The journal prevents data file corruption if anything (e.g. power failure, disk failure, etc.) interrupts the restore operation.

Restore Backups to Non-Local mongod Instances

By default, mongorestore connects to a MongoDB instance running on the localhost interface (e.g. 127.0.0.1) and on the default port (27017). If you want to restore to a different host or port, use the --host and --port options.

Consider the following example:

mongorestore --host mongodb1.example.net --port 3017 --username user --password pass /opt/backup/mongodump-2013-10-24

As above, you may specify username and password connections if your mongod requires authentication.

Additional Resources

Backup and it’s Role in Disaster Recovery White Paper [https://www.mongodb.com/lp/white-paper/backup-disaster-recovery]

Cloud Backup through MongoDB Management Service [http://mms.mongodb.com]

Blog Post: Backup vs. Replication, Why you Need Both [http://www.mongodb.com/blog/post/backup-vs-replication-why-do-you-need-both]

Backup and Restore Sharded Clusters

The following tutorials describe backup and restoration for sharded clusters:

Backup a Small Sharded Cluster with mongodump

If your sharded cluster holds a small data set, you can use mongodump to capture the entire backup in a reasonable amount of time.

Backup a Sharded Cluster with Filesystem Snapshots

Use file system snapshots back up each component in the sharded cluster individually. The procedure involves stopping the cluster balancer. If your system configuration allows file system backups, this might be more efficient than using MongoDB tools.

Backup a Sharded Cluster with Database Dumps

Create backups using mongodump to back up each component in the cluster individually.

Schedule Backup Window for Sharded Clusters

Limit the operation of the cluster balancer to provide a window for regular backup operations.

Restore a Single Shard

An outline of the procedure and consideration for restoring a single shard from a backup.

Restore a Sharded Cluster

An outline of the procedure and consideration for restoring an entire sharded cluster from backup.

Backup a Small Sharded Cluster with mongodump

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Schedule Backup Window for Sharded Clusters

Restore a Single Shard

Restore a Sharded Cluster

Backup a Small Sharded Cluster with mongodump

Overview

If your sharded cluster holds a small data set, you can connect to a mongos using mongodump. You can create backups of your MongoDB cluster, if your backup infrastructure can capture the entire backup in a reasonable amount of time and if you have a storage system that can hold the complete MongoDB data set.

See MongoDB Backup Methods and Backup and Restore Sharded Clusters for complete information on backups in MongoDB and backups of sharded clusters in particular.

Important

By default mongodump issue its queries to the non-primary nodes.

To backup all the databases in a cluster via mongodump, you should have the backup role. The backup role provides all the needed privileges for backing up all database. The role confers no additional access, in keeping with the policy of least privilege.

To backup a given database, you must have read access on the database. Several roles provide this access, including the backup role.

To backup the system.profile collection in a database, you must have read access on certain system collections in the database. Several roles provide this access, including the clusterAdmin and dbAdmin roles.

Changed in version 2.6.

To backup users and user-defined roles for a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to backup a given database’s users, you must have the find action on the admin database’s admin.system.users collection. The backup and userAdminAnyDatabase roles both provide this privilege.

To backup the user-defined roles on a database, you must have the find action on the admin database’s admin.system.roles collection. Both the backup and userAdminAnyDatabase roles provide this privilege.

Considerations

If you use mongodump without specifying a database or collection, mongodump will capture collection data and the cluster meta-data from the config servers.

You cannot use the --oplog option for mongodump when capturing data from mongos. As a result, if you need to capture a backup that reflects a single moment in time, you must stop all writes to the cluster for the duration of the backup operation.

Procedure

Capture Data

You can perform a backup of a sharded cluster by connecting mongodump to a mongos. Use the following operation at your system’s prompt:

mongodump --host mongos3.example.net --port 27017

mongodump will write BSON files that hold a copy of data stored in the sharded cluster accessible via the mongos listening on port 27017 of the mongos3.example.net host.

Restore Data

Backups created with mongodump do not reflect the chunks or the distribution of data in the sharded collection or collections. Like all mongodump output, these backups contain separate directories for each database and BSON files for each collection in that database.

You can restore mongodump output to any MongoDB instance, including a standalone, a replica set, or a new sharded cluster. When restoring data to sharded cluster, you must deploy and configure sharding before restoring data from the backup. See Deploy a Sharded Cluster for more information.

Backup a Sharded Cluster with Filesystem Snapshots

Overview

This document describes a procedure for taking a backup of all components of a sharded cluster. This procedure uses file system snapshots to capture a copy of the mongod instance. An alternate procedure uses mongodump to create binary database dumps when file-system snapshots are not available. See Backup a Sharded Cluster with Database Dumps for the alternate procedure.

See MongoDB Backup Methods and Backup and Restore Sharded Clusters for complete information on backups in MongoDB and backups of sharded clusters in particular.

Important

To capture a point-in-time backup from a sharded cluster you must stop all writes to the cluster. On a running production system, you can only capture an approximation of point-in-time snapshot.

Considerations

Balancing

It is essential that you stop the balancer before capturing a backup.

If the balancer is active while you capture backups, the backup artifacts may be incomplete and/or have duplicate data, as chunks may migrate while recording backups.

Precision

In this procedure, you will stop the cluster balancer and take a backup up of the config database, and then take backups of each shard in the cluster using a file-system snapshot tool. If you need an exact moment-in-time snapshot of the system, you will need to stop all application writes before taking the filesystem snapshots; otherwise the snapshot will only approximate a moment in time.

For approximate point-in-time snapshots, you can improve the quality of the backup while minimizing impact on the cluster by taking the backup from a secondary member of the replica set that provides each shard.

Consistency

If the journal and data files are on the same logical volume, you can use a single point-in-time snapshot to capture a valid copy of the data.

If the journal and data files are on different file systems, you must use db.fsyncLock() and db.fsyncUnLock() to capture a valid copy of your data.

Procedure

1

Disable the balancer.

Disable the balancer process that equalizes the distribution of data among the shards. To disable the balancer, use the sh.stopBalancer() method in the mongo shell.

Consider the following example:

use config
sh.stopBalancer()

For more information, see the Disable the Balancer procedure.

Step 1: Disable the balancer.

Disable the balancer process that equalizes the distribution of data among the shards. To disable the balancer, use the sh.stopBalancer() method in the mongo shell.

Consider the following example:

use config
sh.stopBalancer()

For more information, see the Disable the Balancer procedure.

2

If necessary, lock one secondary member of each replica set in each shard.

If your mongod does not have journaling enabled or your journal and data files are on different volumes, you must lock your mongod before capturing a back up.

If your mongod has journaling enabled and your journal and data files are on the same volume, you may skip this step.

If you need to lock the monogd, attempt to lock one secondary member of each replica set in each shard so that your backups reflect the state of your database at the nearest possible approximation of a single moment in time.

To lock a secondary, connect through the mongo shell to the secondary member’s mongod instance and issue the db.fsyncLock() method.

Step 2: If necessary, lock one secondary member of each replica set in each shard.

If your mongod does not have journaling enabled or your journal and data files are on different volumes, you must lock your mongod before capturing a back up.

If your mongod has journaling enabled and your journal and data files are on the same volume, you may skip this step.

If you need to lock the monogd, attempt to lock one secondary member of each replica set in each shard so that your backups reflect the state of your database at the nearest possible approximation of a single moment in time.

To lock a secondary, connect through the mongo shell to the secondary member’s mongod instance and issue the db.fsyncLock() method.

3

Back up one of the config servers.

Backing up a config server backs up the sharded cluster’s metadata. You need back up only one config server, as they all hold the same data. Do one of the following to back up one of the config servers:

Create a file-system snapshot of the config server.

Do this only if the config server has journaling enabled. Use the procedure in Backup and Restore with Filesystem Snapshots. Never use db.fsyncLock() on config databases.

Create a database dump to backup the config server.

Issue mongodump against one of the config mongod instances or via the mongos. If you are running MongoDB 2.4 or later with the --configsvr option, then include the --oplog option to ensure that the dump includes a partial oplog containing operations from the duration of the mongodump operation. For example:

mongodump --oplog --db config

Step 3: Back up one of the config servers.

Backing up a config server backs up the sharded cluster’s metadata. You need back up only one config server, as they all hold the same data. Do one of the following to back up one of the config servers:

Create a file-system snapshot of the config server.

Do this only if the config server has journaling enabled. Use the procedure in Backup and Restore with Filesystem Snapshots. Never use db.fsyncLock() on config databases.

Create a database dump to backup the config server.

Issue mongodump against one of the config mongod instances or via the mongos. If you are running MongoDB 2.4 or later with the --configsvr option, then include the --oplog option to ensure that the dump includes a partial oplog containing operations from the duration of the mongodump operation. For example:

mongodump --oplog --db config

4

Back up the replica set members of the shards that you locked.

You may back up the shards in parallel. For each shard, create a snapshot. Use the procedure in Backup and Restore with Filesystem Snapshots.

Step 4: Back up the replica set members of the shards that you locked.

You may back up the shards in parallel. For each shard, create a snapshot. Use the procedure in Backup and Restore with Filesystem Snapshots.

5

Unlock locked replica set members.

If you locked any mongod instances to capture the backup, unlock them now.

Unlock all locked replica set members of each shard using the db.fsyncUnlock() method in the mongo shell.

Step 5: Unlock locked replica set members.

If you locked any mongod instances to capture the backup, unlock them now.

Unlock all locked replica set members of each shard using the db.fsyncUnlock() method in the mongo shell.

6

Enable the balancer.

Re-enable the balancer with the sh.setBalancerState() method. Use the following command sequence when connected to the mongos with the mongo shell:

use config
sh.setBalancerState(true)

Step 6: Enable the balancer.

Re-enable the balancer with the sh.setBalancerState() method. Use the following command sequence when connected to the mongos with the mongo shell:

use config
sh.setBalancerState(true)

Backup a Sharded Cluster with Database Dumps

Overview

This document describes a procedure for taking a backup of all components of a sharded cluster. This procedure uses mongodump to create dumps of the mongod instance. An alternate procedure uses file system snapshots to capture the backup data, and may be more efficient in some situations if your system configuration allows file system backups. See Backup and Restore Sharded Clusters for more information.

See MongoDB Backup Methods and Backup and Restore Sharded Clusters for complete information on backups in MongoDB and backups of sharded clusters in particular.

Prerequisites

Important

To capture a point-in-time backup from a sharded cluster you must stop all writes to the cluster. On a running production system, you can only capture an approximation of point-in-time snapshot.

To backup all the databases in a cluster via mongodump, you should have the backup role. The backup role provides all the needed privileges for backing up all database. The role confers no additional access, in keeping with the policy of least privilege.

To backup a given database, you must have read access on the database. Several roles provide this access, including the backup role.

To backup the system.profile collection in a database, you must have read access on certain system collections in the database. Several roles provide this access, including the clusterAdmin and dbAdmin roles.

Changed in version 2.6.

To backup users and user-defined roles for a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to backup a given database’s users, you must have the find action on the admin database’s admin.system.users collection. The backup and userAdminAnyDatabase roles both provide this privilege.

To backup the user-defined roles on a database, you must have the find action on the admin database’s admin.system.roles collection. Both the backup and userAdminAnyDatabase roles provide this privilege.

Consideration

To create these backups of a sharded cluster, you will stop the cluster balancer and take a backup up of the config database, and then take backups of each shard in the cluster using mongodump to capture the backup data. To capture a more exact moment-in-time snapshot of the system, you will need to stop all application writes before taking the filesystem snapshots; otherwise the snapshot will only approximate a moment in time.

For approximate point-in-time snapshots, taking the backup from a single offline secondary member of the replica set that provides each shard can improve the quality of the backup while minimizing impact on the cluster.

Procedure

1

Disable the balancer process.

Disable the balancer process that equalizes the distribution of data among the shards. To disable the balancer, use the sh.stopBalancer() method in the mongo shell. For example:

use config
sh.setBalancerState(false)

For more information, see the Disable the Balancer procedure.

Warning

If you do not stop the balancer, the backup could have duplicate data or omit data as chunks migrate while recording backups.

Step 1: Disable the balancer process.

Disable the balancer process that equalizes the distribution of data among the shards. To disable the balancer, use the sh.stopBalancer() method in the mongo shell. For example:

use config
sh.setBalancerState(false)

For more information, see the Disable the Balancer procedure.

Warning

If you do not stop the balancer, the backup could have duplicate data or omit data as chunks migrate while recording backups.

2

Lock replica set members.

Lock one member of each replica set in each shard so that your backups reflect the state of your database at the nearest possible approximation of a single moment in time. Lock these mongod instances in as short of an interval as possible.

To lock or freeze a sharded cluster, you shut down one member of each replica set. Ensure that the oplog has sufficient capacity to allow these secondaries to catch up to the state of the primaries after finishing the backup procedure. See Oplog Size for more information.

Step 2: Lock replica set members.

Lock one member of each replica set in each shard so that your backups reflect the state of your database at the nearest possible approximation of a single moment in time. Lock these mongod instances in as short of an interval as possible.

To lock or freeze a sharded cluster, you shut down one member of each replica set. Ensure that the oplog has sufficient capacity to allow these secondaries to catch up to the state of the primaries after finishing the backup procedure. See Oplog Size for more information.

3

Backup one config server.

Use mongodump to backup one of the config servers. This backs up the cluster’s metadata. You only need to back up one config server, as they all hold the same data.

Use the mongodump tool to capture the content of the config mongod instances.

Your config servers must run MongoDB 2.4 or later with the --configsvr option and the mongodump option must include the --oplog to capture a consistent copy of the config database:

mongodump --oplog --db config

Step 3: Backup one config server.

Use mongodump to backup one of the config servers. This backs up the cluster’s metadata. You only need to back up one config server, as they all hold the same data.

Use the mongodump tool to capture the content of the config mongod instances.

Your config servers must run MongoDB 2.4 or later with the --configsvr option and the mongodump option must include the --oplog to capture a consistent copy of the config database:

mongodump --oplog --db config

4

Backup replica set members.

Back up the replica set members of the shards that shut down using mongodump and specifying the --dbpath option. You may back up the shards in parallel. Consider the following invocation:

mongodump --journal --dbpath /data/db/ --out /data/backup/

You must run mongodump on the same system where the mongod ran. This operation will create a dump of all the data managed by the mongod instances that used the dbPath /data/db/. mongodump writes the output of this dump to the /data/backup/ directory.

Step 4: Backup replica set members.

Back up the replica set members of the shards that shut down using mongodump and specifying the --dbpath option. You may back up the shards in parallel. Consider the following invocation:

mongodump --journal --dbpath /data/db/ --out /data/backup/

You must run mongodump on the same system where the mongod ran. This operation will create a dump of all the data managed by the mongod instances that used the dbPath /data/db/. mongodump writes the output of this dump to the /data/backup/ directory.

5

Restart replica set members.

Restart all stopped replica set members of each shard as normal and allow them to catch up with the state of the primary.

Step 5: Restart replica set members.

Restart all stopped replica set members of each shard as normal and allow them to catch up with the state of the primary.

6

Re-enable the balancer process.

Re-enable the balancer with the sh.setBalancerState() method.

Use the following command sequence when connected to the mongos with the mongo shell:

use config
sh.setBalancerState(true)

Step 6: Re-enable the balancer process.

Re-enable the balancer with the sh.setBalancerState() method.

Use the following command sequence when connected to the mongos with the mongo shell:

use config
sh.setBalancerState(true)

Schedule Backup Window for Sharded Clusters

Overview

In a sharded cluster, the balancer process is responsible for distributing sharded data around the cluster, so that each shard has roughly the same amount of data.

However, when creating backups from a sharded cluster it is important that you disable the balancer while taking backups to ensure that no chunk migrations affect the content of the backup captured by the backup procedure. Using the procedure outlined in the section Disable the Balancer you can manually stop the balancer process temporarily. As an alternative you can use this procedure to define a balancing window so that the balancer is always disabled during your automated backup operation.

Procedure

If you have an automated backup schedule, you can disable all balancing operations for a period of time. For instance, consider the following command:

use config
db.settings.update( { _id : "balancer" }, { $set : { activeWindow : { start : "6:00", stop : "23:00" } } }, true )

This operation configures the balancer to run between 6:00am and 11:00pm, server time. Schedule your backup operation to run and complete outside of this time. Ensure that the backup can complete outside the window when the balancer is running and that the balancer can effectively balance the collection among the shards in the window allotted to each.

Restore a Single Shard

Overview

Restoring a single shard from backup with other unaffected shards requires a number of special considerations and practices. This document outlines the additional tasks you must perform when restoring a single shard.

Consider the following resources on backups in general as well as backup and restoration of sharded clusters specifically:

Backup and Restore Sharded Clusters

Restore a Sharded Cluster

MongoDB Backup Methods

Procedure

Always restore sharded clusters as a whole. When you restore a single shard, keep in mind that the balancer process might have moved chunks to or from this shard since the last backup. If that’s the case, you must manually move those chunks, as described in this procedure.

1

Restore the shard as you would any other mongod instance.

See MongoDB Backup Methods for overviews of these procedures.

Step 1: Restore the shard as you would any other mongod instance.

See MongoDB Backup Methods for overviews of these procedures.

2

Manage the chunks.

For all chunks that migrate away from this shard, you do not need to do anything at this time. You do not need to delete these documents from the shard because the chunks are automatically filtered out from queries by mongos. You can remove these documents from the shard, if you like, at your leisure.

For chunks that migrate to this shard after the most recent backup, you must manually recover the chunks using backups of other shards, or some other source. To determine what chunks have moved, view the changelog collection in the Config Database.

Step 2: Manage the chunks.

For all chunks that migrate away from this shard, you do not need to do anything at this time. You do not need to delete these documents from the shard because the chunks are automatically filtered out from queries by mongos. You can remove these documents from the shard, if you like, at your leisure.

For chunks that migrate to this shard after the most recent backup, you must manually recover the chunks using backups of other shards, or some other source. To determine what chunks have moved, view the changelog collection in the Config Database.

Restore a Sharded Cluster

Overview

You can restore a sharded cluster either from snapshots or from BSON database dumps created by the mongodump tool. This document provides procedures for both:

Restore a Sharded Cluster with Filesystem Snapshots

Restore a Sharded Cluster with Database Dumps

Related Documents

For an overview of backups in MongoDB, see MongoDB Backup Methods. For complete information on backups and backups of sharded clusters in particular, see Backup and Restore Sharded Clusters.

For backup procedures, see:

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Procedures

Use the procedure for the type of backup files to restore.

Restore a Sharded Cluster with Filesystem Snapshots

1

Shut down the entire cluster.

Stop all mongos and mongod processes, including all shards and all config servers.

Connect to each member use the following operation:

use admin
db.shutdownServer()

For version 2.4 or earlier, use db.shutdownServer({force:true}).

Step 1: Shut down the entire cluster.

Stop all mongos and mongod processes, including all shards and all config servers.

Connect to each member use the following operation:

use admin
db.shutdownServer()

For version 2.4 or earlier, use db.shutdownServer({force:true}).

2

Restore the data files.

One each server, extract the data files to the location where the mongod instance will access them. Restore the following:

Data files for each server in each shard.

Because replica sets provide each production shard, restore all the members of the replica set or use the other standard approaches for restoring a replica set from backup. See the Restore a Snapshot and Restore a Database with mongorestore sections for details on these procedures.

Data files for each config server.

Step 2: Restore the data files.

One each server, extract the data files to the location where the mongod instance will access them. Restore the following:

Data files for each server in each shard.

Because replica sets provide each production shard, restore all the members of the replica set or use the other standard approaches for restoring a replica set from backup. See the Restore a Snapshot and Restore a Database with mongorestore sections for details on these procedures.

Data files for each config server.

3

Restart the config servers.

Restart each config server mongod instance by issuing a command similar to the following for each, using values appropriate to your configuration:

mongod --configsvr --dbpath /data/configdb --port 27019

Step 3: Restart the config servers.

Restart each config server mongod instance by issuing a command similar to the following for each, using values appropriate to your configuration:

mongod --configsvr --dbpath /data/configdb --port 27019

4

If shard hostnames have changed, update the config string and config database.

If shard hostnames have changed, start one mongos instance using the updated config string with the new configdb hostnames and ports.

Then update the shards collection in the Config Database to reflect the new hostnames. Then stop the mongos instance.

Step 4: If shard hostnames have changed, update the config string and config database.

If shard hostnames have changed, start one mongos instance using the updated config string with the new configdb hostnames and ports.

Then update the shards collection in the Config Database to reflect the new hostnames. Then stop the mongos instance.

5

Restart all the shard mongod instances.

Step 5: Restart all the shard mongod instances.

6

Restart all the mongos instances.

If shard hostnames have changed, make sure to use the updated config string.

Step 6: Restart all the mongos instances.

If shard hostnames have changed, make sure to use the updated config string.

7

Connect to a mongos to ensure the cluster is operational.

Connect to a mongos instance from a mongo shell and use the db.printShardingStatus() method to ensure that the cluster is operational, as follows:

db.printShardingStatus()
show collections

Step 7: Connect to a mongos to ensure the cluster is operational.

Connect to a mongos instance from a mongo shell and use the db.printShardingStatus() method to ensure that the cluster is operational, as follows:

db.printShardingStatus()
show collections

Restore a Sharded Cluster with Database Dumps

1

Shut down the entire cluster.

Stop all mongos and mongod processes, including all shards and all config servers.

Connect to each member use the following operation:

use admin
db.shutdownServer()

For version 2.4 or earlier, use db.shutdownServer({force:true}).

Step 1: Shut down the entire cluster.

Stop all mongos and mongod processes, including all shards and all config servers.

Connect to each member use the following operation:

use admin
db.shutdownServer()

For version 2.4 or earlier, use db.shutdownServer({force:true}).

2

Restore the data files.

One each server, use mongorestore to restore the database dump to the location where the mongod instance will access the data.

The following example restores a database dump located at /opt/backup/ to the /data/ directory. This requires that there are no active mongod instances attached to the /data directory.

mongorestore --dbpath /data /opt/backup

Step 2: Restore the data files.

One each server, use mongorestore to restore the database dump to the location where the mongod instance will access the data.

The following example restores a database dump located at /opt/backup/ to the /data/ directory. This requires that there are no active mongod instances attached to the /data directory.

mongorestore --dbpath /data /opt/backup

3

Restart the config servers.

Restart each config server mongod instance by issuing a command similar to the following for each, using values appropriate to your configuration:

mongod --configsvr --dbpath /data/configdb --port 27019

Step 3: Restart the config servers.

Restart each config server mongod instance by issuing a command similar to the following for each, using values appropriate to your configuration:

mongod --configsvr --dbpath /data/configdb --port 27019

4

If shard hostnames have changed, update the config string and config database.

If shard hostnames have changed, start one mongos instance using the updated config string with the new configdb hostnames and ports.

Then update the shards collection in the Config Database to reflect the new hostnames. Then stop the mongos instance.

Step 4: If shard hostnames have changed, update the config string and config database.

If shard hostnames have changed, start one mongos instance using the updated config string with the new configdb hostnames and ports.

Then update the shards collection in the Config Database to reflect the new hostnames. Then stop the mongos instance.

5

Restart all the shard mongod instances.

Step 5: Restart all the shard mongod instances.

6

Restart all the mongos instances.

If shard hostnames have changed, make sure to use the updated config string.

Step 6: Restart all the mongos instances.

If shard hostnames have changed, make sure to use the updated config string.

7

Connect to a mongos to ensure the cluster is operational.

Connect to a mongos instance from a mongo shell and use the db.printShardingStatus() method to ensure that the cluster is operational, as follows:

db.printShardingStatus()
show collections

Step 7: Connect to a mongos to ensure the cluster is operational.

Connect to a mongos instance from a mongo shell and use the db.printShardingStatus() method to ensure that the cluster is operational, as follows:

db.printShardingStatus()
show collections

Recover Data after an Unexpected Shutdown

If MongoDB does not shutdown cleanly [1] the on-disk representation of the data files will likely reflect an inconsistent state which could lead to data corruption. [2]

To prevent data inconsistency and corruption, always shut down the database cleanly and use the durability journaling. MongoDB writes data to the journal, by default, every 100 milliseconds, such that MongoDB can always recover to a consistent state even in the case of an unclean shutdown due to power loss or other system failure.

If you are not running as part of a replica set and do not have journaling enabled, use the following procedure to recover data that may be in an inconsistent state. If you are running as part of a replica set, you should always restore from a backup or restart the mongod instance with an empty dbPath and allow MongoDB to perform an initial sync to restore the data.

See also

The Administration documents, including Replica Set Syncing, and the documentation on the --repair repairPath and storage.journal.enabled settings.

[1]
To ensure a clean shut down, use the db.shutdownServer() from the mongo shell, your control script, the mongod --shutdown option on Linux systems, “Control-C” when running mongod in interactive mode, or kill $(pidof mongod) or kill -2 $(pidof mongod).

[2]
You can also use the db.collection.validate() method to test the integrity of a single collection. However, this process is time consuming, and without journaling you can safely assume that the data is in an invalid state and you should either run the repair operation or resync from an intact member of the replica set.

Process

Indications

When you are aware of a mongod instance running without journaling that stops unexpectedly and you’re not running with replication, you should always run the repair operation before starting MongoDB again. If you’re using replication, then restore from a backup and allow replication to perform an initial sync to restore data.

If the mongod.lock file in the data directory specified by dbPath, /data/db by default, is not a zero-byte file, then mongod will refuse to start, and you will find a message that contains the following line in your MongoDB log our output:

Unclean shutdown detected.

This indicates that you need to run mongod with the --repair option. If you run repair when the mongodb.lock file exists in your dbPath, or the optional --repairpath, you will see a message that contains the following line:

old lock file: /data/db/mongod.lock. probably means unclean shutdown

If you see this message, as a last resort you may remove the lockfile and run the repair operation before starting the database normally, as in the following procedure:

Overview

Warning

Recovering a member of a replica set.

Do not use this procedure to recover a member of a replica set. Instead you should either restore from a backup or perform an initial sync using data from an intact member of the set, as described in Resync a Member of a Replica Set.

There are two processes to repair data files that result from an unexpected shutdown:

Use the --repair option in conjunction with the --repairpath option. mongod will read the existing data files, and write the existing data to new data files.

You do not need to remove the mongod.lock file before using this procedure.

Use the --repair option. mongod will read the existing data files, write the existing data to new files and replace the existing, possibly corrupt, files with new files.

You must remove the mongod.lock file before using this procedure.

Note

--repair functionality is also available in the shell with the db.repairDatabase() helper for the repairDatabase command.

Procedures

Important

Always Run mongod as the same user to avoid changing the permissions of the MongoDB data files.

Repair Data Files and Preserve Original Files

To repair your data files using the --repairpath option to preserve the original data files unmodified.

Repair Data Files without Preserving Original Files

To repair your data files without preserving the original files, do not use the --repairpath option, as in the following procedure:

Warning

After you remove the mongod.lock file you must run the --repair process before using your database.

1

Start mongod using the option to replace the original files with the repaired files.

Start the mongod instance using the --repair option and the --repairpath option. Issue a command similar to the following:

mongod --dbpath /data/db --repair --repairpath /data/db0

When this completes, the new repaired data files will be in the /data/db0 directory.

Step 1: Start mongod using the option to replace the original files with the repaired files.

Start the mongod instance using the --repair option and the --repairpath option. Issue a command similar to the following:

mongod --dbpath /data/db --repair --repairpath /data/db0

When this completes, the new repaired data files will be in the /data/db0 directory.

2

Start mongod with the new data directory.

Start mongod using the following invocation to point the dbPath at /data/db0:

mongod --dbpath /data/db0

Once you confirm that the data files are operational you may delete or archive the old data files in the /data/db directory. You may also wish to move the repaired files to the old database location or update the dbPath to indicate the new location.

Step 2: Start mongod with the new data directory.

Start mongod using the following invocation to point the dbPath at /data/db0:

mongod --dbpath /data/db0

Once you confirm that the data files are operational you may delete or archive the old data files in the /data/db directory. You may also wish to move the repaired files to the old database location or update the dbPath to indicate the new location.

1

Remove the stale lock file.

For example:

rm /data/db/mongod.lock

Replace /data/db with your dbPath where your MongoDB instance’s data files reside.

Step 1: Remove the stale lock file.

For example:

rm /data/db/mongod.lock

Replace /data/db with your dbPath where your MongoDB instance’s data files reside.

2

Start mongod using the option to replace the original files with the repaired files.

Start the mongod instance using the --repair option, which replaces the original data files with the repaired data files. Issue a command similar to the following:

mongod --dbpath /data/db --repair

When this completes, the repaired data files will replace the original data files in the /data/db directory.

Step 2: Start mongod using the option to replace the original files with the repaired files.

Start the mongod instance using the --repair option, which replaces the original data files with the repaired data files. Issue a command similar to the following:

mongod --dbpath /data/db --repair

When this completes, the repaired data files will replace the original data files in the /data/db directory.

3

Start mongod as usual.

Start mongod using the following invocation to point the dbPath at /data/db:

mongod --dbpath /data/db

Step 3: Start mongod as usual.

Start mongod using the following invocation to point the dbPath at /data/db:

mongod --dbpath /data/db

mongod.lock

In normal operation, you should never remove the mongod.lock file and start mongod. Instead consider the one of the above methods to recover the database and remove the lock files. In dire situations you can remove the lockfile, and start the database using the possibly corrupt files, and attempt to recover data from the database; however, it’s impossible to predict the state of the database in these situations.

If you are not running with journaling, and your database shuts down unexpectedly for any reason, you should always proceed as if your database is in an inconsistent and likely corrupt state. If at all possible restore from backup or, if running as a replica set, restore by performing an initial sync using data from an intact member of the set, as described in Resync a Member of a Replica Set.

MongoDB Scripting

The mongo shell is an interactive JavaScript shell for MongoDB, and is part of all MongoDB distributions [http://www.mongodb.org/downloads]. This section provides an introduction to the shell, and outlines key functions, operations, and use of the mongo shell. Also consider FAQ: The mongo Shell and the shell method and other relevant reference material.

Note

Most examples in the MongoDB Manual use the mongo shell; however, many drivers provide similar interfaces to MongoDB.

Server-side JavaScript

Details MongoDB’s support for executing JavaScript code for server-side operations.

Data Types in the mongo Shell

Describes the super-set of JSON available for use in the mongo shell.

Write Scripts for the mongo Shell

An introduction to the mongo shell for writing scripts to manipulate data and administer MongoDB.

Getting Started with the mongo Shell

Introduces the use and operation of the MongoDB shell.

Access the mongo Shell Help Information

Describes the available methods for accessing online help for the operation of the mongo interactive shell.

mongo Shell Quick Reference

A high level reference to the use and operation of the mongo shell.

Server-side JavaScript

Data Types in the mongo Shell

Write Scripts for the mongo Shell

Getting Started with the mongo Shell

Access the mongo Shell Help Information

mongo Shell Quick Reference

Server-side JavaScript

Overview

MongoDB provides the following commands, methods, and operator that perform server-side execution of JavaScript code:

mapReduce and the corresponding mongo shell method db.collection.mapReduce(). mapReduce operations map, or associate, values to keys, and for keys with multiple values, reduce the values for each key to a single object. For more information, see Map-Reduce.

eval command and the corresponding mongo shell method db.eval(). eval operations evaluates JavaScript functions on the database server. You cannot use the eval command and db.eval() method with sharded collections. For replica sets, you can only run the eval command and db.eval() method against the primary. For more information, see eval command and db.eval() method reference pages.

$where operator that evaluates a JavaScript expression or a function in order to query for documents.

You can also specify a JavaScript file to the mongo shell to run on the server. For more information, see Running .js files via a mongo shell Instance on the Server

JavaScript in MongoDB

Although the aforementioned operations use JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

You can also disable server-side execution of JavaScript. For details, see Disable Server-Side Execution of JavaScript.

Running .js files via a mongo shell Instance on the Server

You can specify a JavaScript (.js) file to a mongo shell instance to execute the file on the server. This is a good technique for performing batch administrative work. When you run mongo shell on the server, connecting via the localhost interface, the connection is fast with low latency.

The command helpers provided in the mongo shell are not available in JavaScript files because they are not valid JavaScript. The following table maps the most common mongo shell helpers to their JavaScript equivalents.

Shell Helpers
JavaScript Equivalents

show dbs, show databases

db.adminCommand('listDatabases')

use <db>

db = db.getSiblingDB('<db>')

show collections

db.getCollectionNames()

show users

db.getUsers()

show roles

db.getRoles({showBuiltinRoles: true})

show log <logname>

db.adminCommand({ 'getLog' : '<logname>' })

show logs

db.adminCommand({ 'getLog' : '*' })

it

cursor = db.collection.find()
if ( cursor.hasNext() ){
   cursor.next();
}

Concurrency

Changed in version 2.4.

The V8 JavaScript engine, which became the default in 2.4, allows multiple JavaScript operations to execute at the same time. Prior to 2.4, MongoDB operations that required the JavaScript interpreter had to acquire a lock, and a single mongod could only run a single JavaScript operation at a time.

Refer to the individual method or operator documentation for any concurrency information. See also the concurrency table.

Disable Server-Side Execution of JavaScript

You can disable all server-side execution of JavaScript, by passing the --noscripting option on the command line or setting security.javascriptEnabled in a configuration file.

See also

Store a JavaScript Function on the Server

Data Types in the mongo Shell

MongoDB BSON provides support for additional data types than JSON. Drivers provide native support for these data types in host languages and the mongo shell also provides several helper classes to support the use of these data types in the mongo JavaScript shell. See the Extended JSON reference for additional information.

Types

Date

The mongo shell provides various methods to return the date, either as a string or as a Date object:

Date() method which returns the current date as a string.

new Date() constructor which returns a Date object using the ISODate() wrapper.

ISODate() constructor which returns a Date object using the ISODate() wrapper.

Internally, Date objects are stored as a 64 bit integer representing the number of milliseconds since the Unix epoch (Jan 1, 1970), which results in a representable date range of about 290 millions years into the past and future.

Return Date as a String

To return the date as a string, use the Date() method, as in the following example:

var myDateString = Date();

To print the value of the variable, type the variable name in the shell, as in the following:

myDateString

The result is the value of myDateString:

Wed Dec 19 2012 01:03:25 GMT-0500 (EST)

To verify the type, use the typeof operator, as in the following:

typeof myDateString

The operation returns string.

Return Date

The mongo shell wrap objects of Date type with the ISODate helper; however, the objects remain of type Date.

The following example uses both the new Date() constructor and the ISODate() constructor to return Date objects.

var myDate = new Date();
var myDateInitUsingISODateWrapper = ISODate();

You can use the new operator with the ISODate() constructor as well.

To print the value of the variable, type the variable name in the shell, as in the following:

myDate

The result is the Date value of myDate wrapped in the ISODate() helper:

ISODate("2012-12-19T06:01:17.171Z")

To verify the type, use the instanceof operator, as in the following:

myDate instanceof Date
myDateInitUsingISODateWrapper instanceof Date

The operation returns true for both.

ObjectId

The mongo shell provides the ObjectId() wrapper class around the ObjectId data type. To generate a new ObjectId, use the following operation in the mongo shell:

new ObjectId

See

ObjectId for full documentation of ObjectIds in MongoDB.

NumberLong

By default, the mongo shell treats all numbers as floating-point values. The mongo shell provides the NumberLong() wrapper to handle 64-bit integers.

The NumberLong() wrapper accepts the long as a string:

NumberLong("2090845886852")

The following examples use the NumberLong() wrapper to write to the collection:

db.collection.insert( { _id: 10, calc: NumberLong("2090845886852") } )
db.collection.update( { _id: 10 },
                      { $set:  { calc: NumberLong("2555555000000") } } )
db.collection.update( { _id: 10 },
                      { $inc: { calc: NumberLong(5) } } )

Retrieve the document to verify:

db.collection.findOne( { _id: 10 } )

In the returned document, the calc field contains a NumberLong object:

{ "_id" : 10, "calc" : NumberLong("2555555000005") }

If you use the $inc to increment the value of a field that contains a NumberLong object by a float, the data type changes to a floating point value, as in the following example:

Use $inc to increment the calc field by 5, which the mongo shell treats as a float:

db.collection.update( { _id: 10 },
                      { $inc: { calc: 5 } } )

Retrieve the updated document:

db.collection.findOne( { _id: 10 } )

In the updated document, the calc field contains a floating point value:

{ "_id" : 10, "calc" : 2555555000010 }

NumberInt

By default, the mongo shell treats all numbers as floating-point values. The mongo shell provides the NumberInt() constructor to explicitly specify 32-bit integers.

Check Types in the mongo Shell

To determine the type of fields, the mongo shell provides the instanceof and typeof operators.

instanceof

instanceof returns a boolean to test if a value is an instance of some type.

For example, the following operation tests whether the _id field is an instance of type ObjectId:

mydoc._id instanceof ObjectId

The operation returns true.

typeof

typeof returns the type of a field.

For example, the following operation returns the type of the _id field:

typeof mydoc._id

In this case typeof will return the more generic object type rather than ObjectId type.

Write Scripts for the mongo Shell

You can write scripts for the mongo shell in JavaScript that manipulate data in MongoDB or perform administrative operation. For more information about the mongo shell see MongoDB Scripting, and see the Running .js files via a mongo shell Instance on the Server section for more information about using these mongo script.

This tutorial provides an introduction to writing JavaScript that uses the mongo shell to access MongoDB.

Opening New Connections

From the mongo shell or from a JavaScript file, you can instantiate database connections using the Mongo() constructor:

new Mongo()
new Mongo(<host>)
new Mongo(<host:port>)

Consider the following example that instantiates a new connection to the MongoDB instance running on localhost on the default port and sets the global db variable to myDatabase using the getDB() method:

conn = new Mongo();
db = conn.getDB("myDatabase");

Additionally, you can use the connect() method to connect to the MongoDB instance. The following example connects to the MongoDB instance that is running on localhost with the non-default port 27020 and set the global db variable:

db = connect("localhost:27020/myDatabase");

Differences Between Interactive and Scripted mongo

When writing scripts for the mongo shell, consider the following:

To set the db global variable, use the getDB() method or the connect() method. You can assign the database reference to a variable other than db.

Write operations in the mongo shell use the “safe writes” by default. If performing bulk operations, use the Bulk() methods. See Write Method Acknowledgements for more information.

Changed in version 2.6: Before MongoDB 2.6, call db.getLastError() explicitly to wait for the result of write operations.

You cannot use any shell helper (e.g. use <dbname>, show dbs, etc.) inside the JavaScript file because they are not valid JavaScript.

The following table maps the most common mongo shell helpers to their JavaScript equivalents.

Shell Helpers
JavaScript Equivalents

show dbs, show databases

db.adminCommand('listDatabases')

use <db>

db = db.getSiblingDB('<db>')

show collections

db.getCollectionNames()

show users

db.getUsers()

show roles

db.getRoles({showBuiltinRoles: true})

show log <logname>

db.adminCommand({ 'getLog' : '<logname>' })

show logs

db.adminCommand({ 'getLog' : '*' })

it

cursor = db.collection.find()
if ( cursor.hasNext() ){
   cursor.next();
}

In interactive mode, mongo prints the results of operations including the content of all cursors. In scripts, either use the JavaScript print() function or the mongo specific printjson() function which returns formatted JSON.

Example

To print all items in a result cursor in mongo shell scripts, use the following idiom:

cursor = db.collection.find();
while ( cursor.hasNext() ) {
   printjson( cursor.next() );
}

Scripting

From the system prompt, use mongo to evaluate JavaScript.

--eval option

Use the --eval option to mongo to pass the shell a JavaScript fragment, as in the following:

mongo test --eval "printjson(db.getCollectionNames())"

This returns the output of db.getCollectionNames() using the mongo shell connected to the mongod or mongos instance running on port 27017 on the localhost interface.

Execute a JavaScript file

You can specify a .js file to the mongo shell, and mongo will execute the JavaScript directly. Consider the following example:

mongo localhost:27017/test myjsfile.js

This operation executes the myjsfile.js script in a mongo shell that connects to the test database on the mongod instance accessible via the localhost interface on port 27017.

Alternately, you can specify the mongodb connection parameters inside of the javascript file using the Mongo() constructor. See Opening New Connections for more information.

You can execute a .js file from within the mongo shell, using the load() function, as in the following:

load("myjstest.js")

This function loads and executes the myjstest.js file.

The load() method accepts relative and absolute paths. If the current working directory of the mongo shell is /data/db, and the myjstest.js resides in the /data/db/scripts directory, then the following calls within the mongo shell would be equivalent:

load("scripts/myjstest.js")
load("/data/db/scripts/myjstest.js")

Note

There is no search path for the load() function. If the desired script is not in the current working directory or the full specified path, mongo will not be able to access the file.

Getting Started with the mongo Shell

This document provides a basic introduction to using the mongo shell. See Install MongoDB for instructions on installing MongoDB for your system.

Start the mongo Shell

To start the mongo shell and connect to your MongoDB instance running on localhost with default port:

Go to your <mongodb installation dir>:

cd <mongodb installation dir>

Type ./bin/mongo to start mongo:

./bin/mongo

If you have added the <mongodb installation dir>/bin to the PATH environment variable, you can just type mongo instead of ./bin/mongo.

To display the database you are using, type db:

db

The operation should return test, which is the default database. To switch databases, issue the use <db> helper, as in the following example:

use <database>

To list the available databases, use the helper show dbs. See also How can I access different databases temporarily? to access a different database from the current database without switching your current database context (i.e. db..)

To start the mongo shell with other options, see examples of starting up mongo and mongo reference which provides details on the available options.

Note

When starting, mongo checks the user’s HOME directory for a JavaScript file named .mongorc.js. If found, mongo interprets the content of .mongorc.js before displaying the prompt for the first time. If you use the shell to evaluate a JavaScript file or expression, either by using the --eval option on the command line or by specifying a .js file to mongo, mongo will read the .mongorc.js file after the JavaScript has finished processing. You can prevent .mongorc.js from being loaded by using the --norc option.

Executing Queries

From the mongo shell, you can use the shell methods to run queries, as in the following example:

db.<collection>.find()

The db refers to the current database.

The <collection> is the name of the collection to query. See Collection Help to list the available collections.

If the mongo shell does not accept the name of the collection, for instance if the name contains a space, hyphen, or starts with a number, you can use an alternate syntax to refer to the collection, as in the following:

db["3test"].find()

db.getCollection("3test").find()

The find() method is the JavaScript method to retrieve documents from <collection>. The find() method returns a cursor to the results; however, in the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, then the cursor is automatically iterated up to 20 times to print up to the first 20 documents that match the query. The mongo shell will prompt Type it to iterate another 20 times.

You can set the DBQuery.shellBatchSize attribute to change the number of iteration from the default value 20, as in the following example which sets it to 10:

DBQuery.shellBatchSize = 10;

For more information and examples on cursor handling in the mongo shell, see Cursors.

See also Cursor Help for list of cursor help in the mongo shell.

For more documentation of basic MongoDB operations in the mongo shell, see:

Getting Started with MongoDB

mongo Shell Quick Reference

Read Operations

Write Operations

Indexing Tutorials

Print

The mongo shell automatically prints the results of the find() method if the returned cursor is not assigned to a variable using the var keyword. To format the result, you can add the .pretty() to the operation, as in the following:

db.<collection>.find().pretty()

In addition, you can use the following explicit print methods in the mongo shell:

print() to print without formatting

print(tojson(<obj>)) to print with JSON formatting and equivalent to printjson()

printjson() to print with JSON formatting and equivalent to print(tojson(<obj>))

Evaluate a JavaScript File

You can execute a .js file from within the mongo shell, using the load() function, as in the following:

load("myjstest.js")

This function loads and executes the myjstest.js file.

The load() method accepts relative and absolute paths. If the current working directory of the mongo shell is /data/db, and the myjstest.js resides in the /data/db/scripts directory, then the following calls within the mongo shell would be equivalent:

load("scripts/myjstest.js")
load("/data/db/scripts/myjstest.js")

Note

There is no search path for the load() function. If the desired script is not in the current working directory or the full specified path, mongo will not be able to access the file.

Use a Custom Prompt

You may modify the content of the prompt by creating the variable prompt in the shell. The prompt variable can hold strings as well as any arbitrary JavaScript. If prompt holds a function that returns a string, mongo can display dynamic information in each prompt. Consider the following examples:

Example

Create a prompt with the number of operations issued in the current session, define the following variables:

cmdCount = 1;
prompt = function() {
             return (cmdCount++) + "> ";
         }

The prompt would then resemble the following:

1> db.collection.find()
2> show collections
3>

Example

To create a mongo shell prompt in the form of <database>@<hostname>$ define the following variables:

host = db.serverStatus().host;

prompt = function() {
             return db+"@"+host+"$ ";
         }

The prompt would then resemble the following:

<database>@<hostname>$ use records
switched to db records
records@<hostname>$

Example

To create a mongo shell prompt that contains the system up time and the number of documents in the current database, define the following prompt variable:

prompt = function() {
             return "Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > ";
         }

The prompt would then resemble the following:

Uptime:5897 Documents:6 > db.people.save({name : "James"});
Uptime:5948 Documents:7 >

Use an External Editor in the mongo Shell

New in version 2.2.

In the mongo shell you can use the edit operation to edit a function or variable in an external editor. The edit operation uses the value of your environments EDITOR variable.

At your system prompt you can define the EDITOR variable and start mongo with the following two operations:

export EDITOR=vim
mongo

Then, consider the following example shell session:

MongoDB shell version: 2.2.0
> function f() {}
> edit f
> f
function f() {
    print("this really works");
}
> f()
this really works
> o = {}
{ }
> edit o
> o
{ "soDoes" : "this" }
>

Note

As mongo shell interprets code edited in an external editor, it may modify code in functions, depending on the JavaScript compiler. For mongo may convert 1+1 to 2 or remove comments. The actual changes affect only the appearance of the code and will vary based on the version of JavaScript used but will not affect the semantics of the code.

Exit the Shell

To exit the shell, type quit() or use the <Ctrl-c> shortcut.

Access the mongo Shell Help Information

In addition to the documentation in the MongoDB Manual, the mongo shell provides some additional information in its “online” help system. This document provides an overview of accessing this help information.

See also

mongo Manual Page

MongoDB Scripting, and

mongo Shell Quick Reference.

Command Line Help

To see the list of options and help for starting the mongo shell, use the --help option from the command line:

mongo --help

Shell Help

To see the list of help, in the mongo shell, type help:

help

Database Help

To see the list of databases on the server, use the show dbs command:

show dbs

New in version 2.4: show databases is now an alias for show dbs

To see the list of help for methods you can use on the db object, call the db.help() method:

db.help()

To see the implementation of a method in the shell, type the db.<method name> without the parenthesis (()), as in the following example which will return the implementation of the method db.addUser():

db.addUser

Collection Help

To see the list of collections in the current database, use the show collections command:

show collections

To see the help for methods available on the collection objects (e.g. db.<collection>), use the db.<collection>.help() method:

db.collection.help()

<collection> can be the name of a collection that exists, although you may specify a collection that doesn’t exist.

To see the collection method implementation, type the db.<collection>.<method> name without the parenthesis (()), as in the following example which will return the implementation of the save() method:

db.collection.save

Cursor Help

When you perform read operations with the find() method in the mongo shell, you can use various cursor methods to modify the find() behavior and various JavaScript methods to handle the cursor returned from the find() method.

To list the available modifier and cursor handling methods, use the db.collection.find().help() command:

db.collection.find().help()

<collection> can be the name of a collection that exists, although you may specify a collection that doesn’t exist.

To see the implementation of the cursor method, type the db.<collection>.find().<method> name without the parenthesis (()), as in the following example which will return the implementation of the toArray() method:

db.collection.find().toArray

Some useful methods for handling cursors are:

hasNext() which checks whether the cursor has more documents to return.

next() which returns the next document and advances the cursor position forward by one.

forEach(<function>) which iterates the whole cursor and applies the <function> to each document returned by the cursor. The <function> expects a single argument which corresponds to the document from each iteration.

For examples on iterating a cursor and retrieving the documents from the cursor, see cursor handling. See also Cursor for all available cursor methods.

Type Help

To get a list of the wrapper classes available in the mongo shell, such as BinData(), type help misc in the mongo shell:

help misc

mongo Shell Quick Reference

mongo Shell Command History

You can retrieve previous commands issued in the mongo shell with the up and down arrow keys. Command history is stored in ~/.dbshell file. See .dbshell for more information.

Command Line Options

The mongo executable can be started with numerous options. See mongo executable page for details on all available options.

The following table displays some common options for mongo:

Option
Description

--help
Show command line options

--nodb

Start mongo shell without connecting to a database.

To connect later, see Opening New Connections.

--shell

Used in conjunction with a JavaScript file (i.e. <file.js>) to continue in the mongo shell after running the JavaScript file.

See JavaScript file for an example.

Command Helpers

The mongo shell provides various help. The following table displays some common help methods and commands:

Help Methods and Commands
Description

help
Show help.

db.help()
Show help for database methods.

db.<collection>.help()
Show help on collection methods. The <collection> can be the name of an existing collection or a non-existing collection.

show dbs
Print a list of all databases on the server.

use <db>
Switch current database to <db>. The mongo shell variable db is set to the current database.

show collections
Print a list of all collections for current database

show users
Print a list of users for current database.

show roles
Print a list of all roles, both user-defined and built-in, for the current database.

show profile
Print the five most recent operations that took 1 millisecond or more. See documentation on the database profiler for more information.

show databases

New in version 2.4: Print a list of all available databases.

load()
Execute a JavaScript file. See Getting Started with the mongo Shell for more information.

Basic Shell JavaScript Operations

The mongo shell provides a JavaScript API for database operations.

In the mongo shell, db is the variable that references the current database. The variable is automatically set to the default database test or is set when you use the use <db> to switch current database.

The following table displays some common JavaScript operations:

JavaScript Database Operations
Description

db.auth()
If running in secure mode, authenticate the user.

coll = db.<collection>

Set a specific collection in the current database to a variable coll, as in the following example:

coll = db.myCollection;

You can perform operations on the myCollection using the variable, as in the following example:

coll.find();

find()

Find all documents in the collection and returns a cursor.

See the db.collection.find() and Query Documents for more information and examples.

See Cursors for additional information on cursor handling in the mongo shell.

insert()
Insert a new document into the collection.

update()

Update an existing document in the collection.

See Write Operations for more information.

save()

Insert either a new document or update an existing document in the collection.

See Write Operations for more information.

remove()

Delete documents from the collection.

See Write Operations for more information.

drop()
Drops or removes completely the collection.

ensureIndex()
Create a new index on the collection if the index does not exist; otherwise, the operation has no effect.

db.getSiblingDB()
Return a reference to another database using this same connection without explicitly switching the current database. This allows for cross database queries. See How can I access different databases temporarily? for more information.

For more information on performing operations in the shell, see:

MongoDB CRUD Concepts

Read Operations

Write Operations

mongo Shell Methods

Keyboard Shortcuts

Changed in version 2.2.

The mongo shell provides most keyboard shortcuts similar to those found in the bash shell or in Emacs. For some functions mongo provides multiple key bindings, to accommodate several familiar paradigms.

The following table enumerates the keystrokes supported by the mongo shell:

Keystroke | Function
Up-arrow | previous-history
Down-arrow | next-history
Home | beginning-of-line
End | end-of-line
Tab | autocomplete
Left-arrow | backward-character
Right-arrow | forward-character
Ctrl-left-arrow | backward-word
Ctrl-right-arrow | forward-word
Meta-left-arrow | backward-word
Meta-right-arrow | forward-word
Ctrl-A | beginning-of-line
Ctrl-B | backward-char
Ctrl-C | exit-shell
Ctrl-D | delete-char (or exit shell)
Ctrl-E | end-of-line
Ctrl-F | forward-char
Ctrl-G | abort
Ctrl-J | accept-line
Ctrl-K | kill-line
Ctrl-L | clear-screen
Ctrl-M | accept-line
Ctrl-N | next-history
Ctrl-P | previous-history
Ctrl-R | reverse-search-history
Ctrl-S | forward-search-history
Ctrl-T | transpose-chars
Ctrl-U | unix-line-discard
Ctrl-W | unix-word-rubout
Ctrl-Y | yank
Ctrl-Z | Suspend (job control works in linux)
Ctrl-H (i.e. Backspace) | backward-delete-char
Ctrl-I (i.e. Tab) | complete
Meta-B | backward-word
Meta-C | capitalize-word
Meta-D | kill-word
Meta-F | forward-word
Meta-L | downcase-word
Meta-U | upcase-word
Meta-Y | yank-pop
Meta-[Backspace] | backward-kill-word
Meta-< | beginning-of-history
Meta-> | end-of-history

Queries

In the mongo shell, perform read operations using the find() and findOne() methods.

The find() method returns a cursor object which the mongo shell iterates to print documents on screen. By default, mongo prints the first 20. The mongo shell will prompt the user to “Type it” to continue iterating the next 20 results.

The following table provides some common read operations in the mongo shell:

Read Operations
Description

db.collection.find(<query>)

Find the documents matching the <query> criteria in the collection. If the <query> criteria is not specified or is empty (i.e {} ), the read operation selects all documents in the collection.

The following example selects the documents in the users collection with the name field equal to "Joe":

coll = db.users;
coll.find( { name: "Joe" } );

For more information on specifying the <query> criteria, see Query Documents.

db.collection.find( <query>, <projection> )

Find documents matching the <query> criteria and return just specific fields in the <projection>.

The following example selects all documents from the collection but returns only the name field and the _id field. The _id is always returned unless explicitly specified to not return.

coll = db.users;
coll.find( { },
           { name: true }
         );

For more information on specifying the <projection>, see Limit Fields to Return from a Query.

db.collection.find().sort( <sort order> )

Return results in the specified <sort order>.

The following example selects all documents from the collection and returns the results sorted by the name field in ascending order (1). Use -1 for descending order:

coll = db.users;
coll.find().sort( { name: 1 } );

db.collection.find( <query> ).sort( <sort order> )
Return the documents matching the <query> criteria in the specified <sort order>.

db.collection.find( ... ).limit( <n> )
Limit result to <n> rows. Highly recommended if you need only a certain number of rows for best performance.

db.collection.find( ... ).skip( <n> )
Skip <n> results.

count()
Returns total number of documents in the collection.

db.collection.find( <query> ).count()

Returns the total number of documents that match the query.

The count() ignores limit() and skip(). For example, if 100 records match but the limit is 10, count() will return 100. This will be faster than iterating yourself, but still take time.

db.collection.findOne( <query> )

Find and return a single document. Returns null if not found.

The following example selects a single document in the users collection with the name field matches to "Joe":

coll = db.users;
coll.findOne( { name: "Joe" } );

Internally, the findOne() method is the find() method with a limit(1).

See Query Documents and Read Operations documentation for more information and examples. See Query and Projection Operators to specify other query operators.

Error Checking Methods

Changed in version 2.6.

The mongo shell write methods now integrates the Write Concern directly into the method execution rather than with a separate db.getLastError() method. As such, the write methods now return a WriteResult() object that contains the results of the operation, including any write errors and write concern errors.

Previous versions used db.getLastError() and db.getLastErrorObj() methods to return error information.

Administrative Command Helpers

The following table lists some common methods to support database administration:

JavaScript Database Administration Methods
Description

db.cloneDatabase(<host>)
Clone the current database from the <host> specified. The <host> database instance must be in noauth mode.

db.copyDatabase(<from>, <to>, <host>)

Copy the <from> database from the <host> to the <to> database on the current server.

The <host> database instance must be in noauth mode.

db.fromColl.renameCollection(<toColl>)
Rename collection from fromColl to <toColl>.

db.repairDatabase()
Repair and compact the current database. This operation can be very slow on large databases.

db.addUser( <user>, <pwd> )
Add user to current database.

db.getCollectionNames()
Get the list of all collections in the current database.

db.dropDatabase()
Drops the current database.

See also administrative database methods for a full list of methods.

Opening Additional Connections

You can create new connections within the mongo shell.

The following table displays the methods to create the connections:

JavaScript Connection Create Methods
Description

db = connect("<host><:port>/<dbname>")

Open a new database connection.

conn = new Mongo()
db = conn.getDB("dbname")

Open a connection to a new server using new Mongo().

Use getDB() method of the connection to select a database.

See also Opening New Connections for more information on the opening new connections from the mongo shell.

Miscellaneous

The following table displays some miscellaneous methods:

Method | Description
Object.bsonsize(<document>) | Prints the BSON size of a <document> in bytes

See the MongoDB JavaScript API Documentation [http://api.mongodb.org/js/index.html] for a full list of JavaScript methods .

Additional Resources

Consider the following reference material that addresses the mongo shell and its interface:

mongo

mongo Shell Methods

Database Commands

Aggregation Reference

Additionally, the MongoDB source code repository includes a jstests directory [https://github.com/mongodb/mongo/tree/master/jstests/] which contains numerous mongo shell scripts.

MongoDB Tutorials

This page lists the tutorials available as part of the MongoDB Manual. In addition to these documents, you can refer to the introductory MongoDB Tutorial. If there is a process or pattern that you would like to see included here, please open a Jira Case [https://jira.mongodb.org/browse/DOCS].

Getting Started

Install MongoDB on Linux Systems

Install MongoDB on Red Hat Enterprise or CentOS Linux

Install MongoDB on Debian

Install MongoDB on Ubuntu

Install MongoDB on OS X

Install MongoDB on Windows

Getting Started with MongoDB

Generate Test Data

Administration

Replica Sets

Deploy a Replica Set

Deploy Replica Set and Configure Authentication and Authorization

Convert a Standalone to a Replica Set

Add Members to a Replica Set

Remove Members from Replica Set

Replace a Replica Set Member

Adjust Priority for Replica Set Member

Resync a Member of a Replica Set

Deploy a Geographically Redundant Replica Set

Change the Size of the Oplog

Force a Member to Become Primary

Change Hostnames in a Replica Set

Add an Arbiter to Replica Set

Convert a Secondary to an Arbiter

Configure a Secondary’s Sync Target

Configure a Delayed Replica Set Member

Configure a Hidden Replica Set Member

Configure Non-Voting Replica Set Member

Prevent Secondary from Becoming Primary

Configure Replica Set Tag Sets

Manage Chained Replication

Reconfigure a Replica Set with Unavailable Members

Recover Data after an Unexpected Shutdown

Troubleshoot Replica Sets

Sharding

Deploy a Sharded Cluster

Convert a Replica Set to a Replicated Sharded Cluster

Add Shards to a Cluster

Remove Shards from an Existing Sharded Cluster

Deploy Three Config Servers for Production Deployments

Migrate Config Servers with the Same Hostname

Migrate Config Servers with Different Hostnames

Replace Disabled Config Server

Migrate a Sharded Cluster to Different Hardware

Backup Cluster Metadata

Backup a Small Sharded Cluster with mongodump

Backup a Sharded Cluster with Filesystem Snapshots

Backup a Sharded Cluster with Database Dumps

Restore a Single Shard

Restore a Sharded Cluster

Schedule Backup Window for Sharded Clusters

Manage Shard Tags

Basic Operations

Use Database Commands

Recover Data after an Unexpected Shutdown

Expire Data from Collections by Setting TTL

Analyze Performance of Database Operations

Rotate Log Files

Build Old Style Indexes

Manage mongod Processes

Back Up and Restore with MongoDB Tools

Backup and Restore with Filesystem Snapshots

Security

Configure Linux iptables Firewall for MongoDB

Configure Windows netsh Firewall for MongoDB

Enable Client Access Control

Create a User Administrator

Add a User to a Database

Create a Role

Modify a User’s Access

View Roles

Generate a Key File

Configure MongoDB with Kerberos Authentication on Linux

Create a Vulnerability Report

Development Patterns

Perform Two Phase Commits

Create an Auto-Incrementing Sequence Field

Enforce Unique Keys for Sharded Collections

Aggregation Examples

Model Data to Support Keyword Search

Limit Number of Elements in an Array after an Update

Perform Incremental Map-Reduce

Troubleshoot the Map Function

Troubleshoot the Reduce Function

Store a JavaScript Function on the Server

Text Search Patterns

Create a text Index

Specify a Language for Text Index

Specify Name for text Index

Control Search Results with Weights

Limit the Number of Entries Scanned

Data Modeling Patterns

Model One-to-One Relationships with Embedded Documents

Model One-to-Many Relationships with Embedded Documents

Model One-to-Many Relationships with Document References

Model Data for Atomic Operations

Model Tree Structures with Parent References

Model Tree Structures with Child References

Model Tree Structures with Materialized Paths

Model Tree Structures with Nested Sets

Administration Reference

UNIX ulimit Settings

Describes user resources limits (i.e. ulimit) and introduces the considerations and optimal configurations for systems that run MongoDB deployments.

System Collections

Introduces the internal collections that MongoDB uses to track per-database metadata, including indexes, collections, and authentication credentials.

Database Profiler Output

Describes the data collected by MongoDB’s operation profiler, which introspects operations and reports data for analysis on performance and behavior.

Journaling Mechanics

Describes the internal operation of MongoDB’s journaling facility and outlines how the journal allows MongoDB to provide provides durability and crash resiliency.

Exit Codes and Statuses

Lists the unique codes returned by mongos and mongod processes upon exit.

UNIX ulimit Settings

System Collections

Database Profiler Output

Journaling Mechanics

Exit Codes and Statuses

UNIX ulimit Settings

Most UNIX-like operating systems, including Linux and OS X, provide ways to limit and control the usage of system resources such as threads, files, and network connections on a per-process and per-user basis. These “ulimits” prevent single users from using too many system resources. Sometimes, these limits have low default values that can cause a number of issues in the course of normal MongoDB operation.

Note

Red Hat Enterprise Linux and CentOS 6 place a max process limitation of 1024 which overrides ulimit settings. Create a file named /etc/security/limits.d/99-mongodb-nproc.conf with new soft nproc and hard nproc values to increase the process limit. See /etc/security/limits.d/90-nproc.conf file as an example.

Resource Utilization

mongod and mongos each use threads and file descriptors to track connections and manage internal operations. This section outlines the general resource utilization patterns for MongoDB. Use these figures in combination with the actual information about your deployment and its use to determine ideal ulimit settings.

Generally, all mongod and mongos instances:

track each incoming connection with a file descriptor and a thread.

track each internal thread or pthread as a system process.

mongod

1 file descriptor for each data file in use by the mongod instance.

1 file descriptor for each journal file used by the mongod instance when storage.journal.enabled is true.

In replica sets, each mongod maintains a connection to all other members of the set.

mongod uses background threads for a number of internal processes, including TTL collections, replication, and replica set health checks, which may require a small number of additional resources.

mongos

In addition to the threads and file descriptors for client connections, mongos must maintain connects to all config servers and all shards, which includes all members of all replica sets.

For mongos, consider the following behaviors:

mongos instances maintain a connection pool to each shard so that the mongos can reuse connections and quickly fulfill requests without needing to create new connections.

You can limit the number of incoming connections using the maxIncomingConnections run-time option. By restricting the number of incoming connections you can prevent a cascade effect where the mongos creates too many connections on the mongod instances.

Note

Changed in version 2.6: MongoDB removed the upward limit on the maxIncomingConnections setting.

Review and Set Resource Limits

ulimit

You can use the ulimit command at the system prompt to check system limits, as in the following example:

$ ulimit -a
-t: cpu time (seconds)         unlimited
-f: file size (blocks)         unlimited
-d: data seg size (kbytes)     unlimited
-s: stack size (kbytes)        8192
-c: core file size (blocks)    0
-m: resident set size (kbytes) unlimited
-u: processes                  192276
-n: file descriptors           21000
-l: locked-in-memory size (kb) 40000
-v: address space (kb)         unlimited
-x: file locks                 unlimited
-i: pending signals            192276
-q: bytes in POSIX msg queues  819200
-e: max nice                   30
-r: max rt priority            65
-N 15:                         unlimited

ulimit refers to the per-user limitations for various resources. Therefore, if your mongod instance executes as a user that is also running multiple processes, or multiple mongod processes, you might see contention for these resources. Also, be aware that the processes value (i.e. -u) refers to the combined number of distinct processes and sub-process threads.

You can change ulimit settings by issuing a command in the following form:

ulimit -n <value>

There are both “hard” and the “soft” ulimits that affect MongoDB’s performance. The “hard” ulimit refers to the maximum number of processes that a user can have active at any time. This is the ceiling: no non-root process can increase the “hard” ulimit. In contrast, the “soft” ulimit is the limit that is actually enforced for a session or process, but any process can increase it up to “hard” ulimit maximum.

A low “soft” ulimit can cause can't create new thread, closing connection errors if the number of connections grows too high. For this reason, it is extremely important to set both ulimit values to the recommended values.

ulimit will modify both “hard” and “soft” values unless the -H or -S modifiers are specified when modifying limit values.

For many distributions of Linux you can change values by substituting the -n option for any possible value in the output of ulimit -a. On OS X, use the launchctl limit command. See your operating system documentation for the precise procedure for changing system limits on running systems.

After changing the ulimit settings, you must restart the process to take advantage of the modified settings. You can use the /proc file system to see the current limitations on a running process.

Depending on your system’s configuration, and default settings, any change to system limits made using ulimit may revert following system a system restart. Check your distribution and operating system documentation for more information.

Note

SUSE Linux Enterprise Server 11, and potentially other versions of SLES and other SUSE distributions, ship with virtual memory address space limited to 8GB by default. This must be adjusted in order to prevent virtual memory allocation failures as the database grows.

The SLES packages for MongoDB adjust these limits in the default scripts, but you will need to make this change manually if you are using custom scripts and/or the tarball release rather than the SLES packages.

Recommended ulimit Settings

Every deployment may have unique requirements and settings; however, the following thresholds and settings are particularly important for mongod and mongos deployments:

-f (file size): unlimited

-t (cpu time): unlimited

-v (virtual memory): unlimited [1]

-n (open files): 64000

-m (memory size): unlimited [1] [2]

-u (processes/threads): 64000

Always remember to restart your mongod and mongos instances after changing the ulimit settings to ensure that the changes take effect.

Linux distributions using Upstart

For Linux distributions that use Upstart, you can specify limits within service scripts if you start mongod and/or mongos instances as Upstart services. You can do this by using limit stanzas [http://upstart.ubuntu.com/wiki/Stanzas#limit].

Specify the Recommended ulimit Settings, as in the following example:

limit fsize unlimited unlimited  # (file size)
limit cpu unlimited unlimited    # (cpu time)
limit as unlimited unlimited     # (virtual memory size)
limit nofile 64000 64000         # (open files)
limit nproc 64000 64000          # (processes/threads)

Each limit stanza sets the “soft” limit to the first value specified and the “hard” limit to the second.

After after changing limit stanzas, ensure that the changes take effect by restarting the application services, using the following form:

restart <service name>

Linux distributions using systemd

For Linux distributions that use systemd, you can specify limits within the [Service] sections of service scripts if you start mongod and/or mongos instances as systemd services. You can do this by using resource limit directives [http://www.freedesktop.org/software/systemd/man/systemd.exec.html#LimitCPU=].

Specify the Recommended ulimit Settings, as in the following example:

[Service]
# Other directives omitted
# (file size)
LimitFSIZE=infinity
# (cpu time)
LimitCPU=infinity
# (virtual memory size)
LimitAS=infinity
# (open files)
LimitNOFILE=64000
# (processes/threads)
LimitNPROC=64000

Each systemd limit directive sets both the “hard” and “soft” limits to the value specified.

After after changing limit stanzas, ensure that the changes take effect by restarting the application services, using the following form:

systemctl restart <service name>

/proc File System

Note

This section applies only to Linux operating systems.

The /proc file-system stores the per-process limits in the file system object located at /proc/<pid>/limits, where <pid> is the process’s PID or process identifier. You can use the following bash function to return the content of the limits object for a process or processes with a given name:

return-limits(){

     for process in $@; do
          process_pids=`ps -C $process -o pid --no-headers | cut -d " " -f 2`

          if [ -z $@ ]; then
             echo "[no $process running]"
          else
             for pid in $process_pids; do
                   echo "[$process #$pid -- limits]"
                   cat /proc/$pid/limits
             done
          fi

     done

}

You can copy and paste this function into a current shell session or load it as part of a script. Call the function with one the following invocations:

return-limits mongod
return-limits mongos
return-limits mongod mongos

[1]
(1, 2) If you limit virtual or resident memory size on a system running MongoDB the operating system will refuse to honor additional allocation requests.

[2]
The -m parameter to ulimit has no effect on Linux systems with kernel versions more recent than 2.4.30. You may omit -m if you wish.

System Collections

Synopsis

MongoDB stores system information in collections that use the <database>.system.* namespace, which MongoDB reserves for internal use. Do not create collections that begin with system.

MongoDB also stores some additional instance-local metadata in the local database, specifically for replication purposes.

Collections

System collections include these collections stored in the admin database:

admin.system.roles

New in version 2.6.

The admin.system.roles collection stores custom roles that administrators create and assign to users to provide access to specific resources.

admin.system.users

Changed in version 2.6.

The admin.system.users collection stores the user’s authentication credentials as well as any roles assigned to the user. Users may define authorization roles in the admin.system.roles collection.

admin.system.version

New in version 2.6.

Stores the schema version of the user credential documents.

System collections also include these collections stored directly in each database:

<database>.system.namespaces

The <database>.system.namespaces collection contains information about all of the database’s collections. Additional namespace metadata exists in the database.ns files and is opaque to database users.

<database>.system.indexes

The <database>.system.indexes collection lists all the indexes in the database. Add and remove data from this collection via the ensureIndex() and dropIndex()

<database>.system.profile

The <database>.system.profile collection stores database profiling information. For information on profiling, see Database Profiling.

<database>.system.js

The <database>.system.js collection holds special JavaScript code for use in server side JavaScript. See Store a JavaScript Function on the Server for more information.

Database Profiler Output

The database profiler captures data information about read and write operations, cursor operations, and database commands. To configure the database profile and set the thresholds for capturing profile data, see the Analyze Performance of Database Operations section.

The database profiler writes data in the system.profile collection, which is a capped collection. To view the profiler’s output, use normal MongoDB queries on the system.profile collection.

Note

Because the database profiler writes data to the system.profile collection in a database, the profiler will profile some write activity, even for databases that are otherwise read-only.

Example system.profile Document

The documents in the system.profile collection have the following form. This example document reflects an update operation:

{
    "ts" : ISODate("2012-12-10T19:31:28.977Z"),
    "op" : "update",
    "ns" : "social.users",
    "query" : {
        "name" : "j.r."
    },
    "updateobj" : {
        "$set" : {
            "likes" : [
                "basketball",
                "trekking"
            ]
        }
    },
    "nscanned" : 8,
    "scanAndOrder" : true,
    "moved" : true,
    "nmoved" : 1,
    "nupdated" : 1,
    "keyUpdates" : 0,
    "numYield" : 0,
    "lockStats" : {
        "timeLockedMicros" : {
            "r" : NumberLong(0),
            "w" : NumberLong(258)
        },
        "timeAcquiringMicros" : {
            "r" : NumberLong(0),
            "w" : NumberLong(7)
        }
    },
    "millis" : 0,
    "client" : "127.0.0.1",
    "user" : ""
}

Output Reference

For any single operation, the documents created by the database profiler will include a subset of the following fields. The precise selection of fields in these documents depends on the type of operation.

system.profile.ts

The timestamp of the operation.

system.profile.op

The type of operation. The possible values are:

insert

query

update

remove

getmore

command

system.profile.ns

The namespace the operation targets. Namespaces in MongoDB take the form of the database, followed by a dot (.), followed by the name of the collection.

system.profile.query

The query document used.

system.profile.command

The command operation.

system.profile.updateobj

The <update> document passed in during an update operation.

system.profile.cursorid

The ID of the cursor accessed by a getmore operation.

system.profile.ntoreturn

Changed in version 2.2: In 2.0, MongoDB includes this field for query and command operations. In 2.2, this information MongoDB also includes this field for getmore operations.

The number of documents the operation specified to return. For example, the profile command would return one document (a results document) so the ntoreturn value would be 1. The limit(5) command would return five documents so the ntoreturn value would be 5.

If the ntoreturn value is 0, the command did not specify a number of documents to return, as would be the case with a simple find() command with no limit specified.

system.profile.ntoskip

New in version 2.2.

The number of documents the skip() method specified to skip.

system.profile.nscanned

The number of documents that MongoDB scans in the index in order to carry out the operation.

In general, if nscanned is much higher than nreturned, the database is scanning many objects to find the target objects. Consider creating an index to improve this.

system.profile.scanAndOrder

scanAndOrder is a boolean that is true when a query cannot use the order of documents in the index for returning sorted results: MongoDB must sort the documents after it receives the documents from a cursor.

If scanAndOrder is false, MongoDB can use the order of the documents in an index to return sorted results.

system.profile.moved

This field appears with a value of true when an update operation moved one or more documents to a new location on disk. If the operation did not result in a move, this field does not appear. Operations that result in a move take more time than in-place updates and typically occur as a result of document growth.

system.profile.nmoved

New in version 2.2.

The number of documents the operation moved on disk. This field appears only if the operation resulted in a move. The field’s implicit value is zero, and the field is present only when non-zero.

system.profile.nupdated

New in version 2.2.

The number of documents updated by the operation.

system.profile.keyUpdates

New in version 2.2.

The number of index keys the update changed in the operation. Changing an index key carries a small performance cost because the database must remove the old key and inserts a new key into the B-tree index.

system.profile.numYield

New in version 2.2.

The number of times the operation yielded to allow other operations to complete. Typically, operations yield when they need access to data that MongoDB has not yet fully read into memory. This allows other operations that have data in memory to complete while MongoDB reads in data for the yielding operation. For more information, see the FAQ on when operations yield.

system.profile.lockStats

New in version 2.2.

The time in microseconds the operation spent acquiring and holding locks. This field reports data for the following lock types:

R - global read lock

W - global write lock

r - database-specific read lock

w - database-specific write lock

system.profile.lockStats.timeLockedMicros

The time in microseconds the operation held a specific lock. For operations that require more than one lock, like those that lock the local database to update the oplog, this value may be longer than the total length of the operation (i.e. millis.)

system.profile.lockStats.timeAcquiringMicros

The time in microseconds the operation spent waiting to acquire a specific lock.

system.profile.nreturned

The number of documents returned by the operation.

system.profile.responseLength

The length in bytes of the operation’s result document. A large responseLength can affect performance. To limit the size of the result document for a query operation, you can use any of the following:

Projections

The limit() method

The batchSize() method

Note

When MongoDB writes query profile information to the log, the responseLength value is in a field named reslen.

system.profile.millis

The time in milliseconds from the perspective of the mongod from the beginning of the operation to the end of the operation.

system.profile.client

The IP address or hostname of the client connection where the operation originates.

For some operations, such as db.eval(), the client is 0.0.0.0:0 instead of an actual client.

system.profile.user

The authenticated user who ran the operation.

Journaling Mechanics

When running with journaling, MongoDB stores and applies write operations in memory and in the on-disk journal before the changes are present in the data files on disk. Writes to the journal are atomic, ensuring the consistency of the on-disk journal files. This document discusses the implementation and mechanics of journaling in MongoDB systems. See Manage Journaling for information on configuring, tuning, and managing journaling.

Journal Files

With journaling enabled, MongoDB creates a journal subdirectory within the directory defined by dbPath, which is /data/db by default. The journal directory holds journal files, which contain write-ahead redo logs. The directory also holds a last-sequence-number file. A clean shutdown removes all the files in the journal directory. A dirty shutdown (crash) leaves files in the journal directory; these are used to automatically recover the database to a consistent state when the mongod process is restarted.

Journal files are append-only files and have file names prefixed with j._. When a journal file holds 1 gigabyte of data, MongoDB creates a new journal file. Once MongoDB applies all the write operations in a particular journal file to the database data files, it deletes the file, as it is no longer needed for recovery purposes. Unless you write many bytes of data per second, the journal directory should contain only two or three journal files.

You can use the storage.smallFiles run time option when starting mongod to limit the size of each journal file to 128 megabytes, if you prefer.

To speed the frequent sequential writes that occur to the current journal file, you can ensure that the journal directory is on a different filesystem from the database data files.

Important

If you place the journal on a different filesystem from your data files you cannot use a filesystem snapshot alone to capture valid backups of a dbPath directory. In this case, use fsyncLock() to ensure that database files are consistent before the snapshot and fsyncUnlock() once the snapshot is complete.

Note

Depending on your filesystem, you might experience a preallocation lag the first time you start a mongod instance with journaling enabled.

MongoDB may preallocate journal files if the mongod process determines that it is more efficient to preallocate journal files than create new journal files as needed. The amount of time required to pre-allocate lag might last several minutes, during which you will not be able to connect to the database. This is a one-time preallocation and does not occur with future invocations.

To avoid preallocation lag, see Avoid Preallocation Lag.

Storage Views used in Journaling

With journaling, MongoDB’s storage layer has two internal views of the data set.

The shared view stores modified data for upload to the MongoDB data files. The shared view is the only view with direct access to the MongoDB data files. When running with journaling, mongod asks the operating system to map your existing on-disk data files to the shared view virtual memory view. The operating system maps the files but does not load them. MongoDB later loads data files into the shared view as needed.

The private view stores data for use with read operations. The private view is the first place MongoDB applies new write operations. Upon a journal commit, MongoDB copies the changes made in the private view to the shared view, where they are then available for uploading to the database data files.

The journal is an on-disk view that stores new write operations after MongoDB applies the operation to the private view but before applying them to the data files. The journal provides durability. If the mongod instance were to crash without having applied the writes to the data files, the journal could replay the writes to the shared view for eventual upload to the data files.

How Journaling Records Write Operations

MongoDB copies the write operations to the journal in batches called group commits. These “group commits” help minimize the performance impact of journaling, since a group commit must block all writers during the commit. See commitIntervalMs for information on the default commit interval.

Journaling stores raw operations that allow MongoDB to reconstruct the following:

document insertion/updates

index modifications

metadata changes to the namespace files

creation and dropping of databases and their associated data files

As write operations occur, MongoDB writes the data to the private view in RAM and then copies the write operations in batches to the journal. The journal stores the operations on disk to ensure durability. Each journal entry describes the bytes the write operation changed in the data files.

MongoDB next applies the journal’s write operations to the shared view. At this point, the shared view becomes inconsistent with the data files.

At default intervals of 60 seconds, MongoDB asks the operating system to flush the shared view to disk. This brings the data files up-to-date with the latest write operations. The operating system may choose to flush the shared view to disk at a higher frequency than 60 seconds, particularly if the system is low on free memory.

When MongoDB flushes write operations to the data files, MongoDB notes which journal writes have been flushed. Once a journal file contains only flushed writes, it is no longer needed for recovery, and MongoDB either deletes it or recycles it for a new journal file.

As part of journaling, MongoDB routinely asks the operating system to remap the shared view to the private view, in order to save physical RAM. Upon a new remapping, the operating system knows that physical memory pages can be shared between the shared view and the private view mappings.

Note

The interaction between the shared view and the on-disk data files is similar to how MongoDB works without journaling, which is that MongoDB asks the operating system to flush in-memory changes back to the data files every 60 seconds.

Exit Codes and Statuses

MongoDB will return one of the following codes and statuses when exiting. Use this guide to interpret logs and when troubleshooting issues with mongod and mongos instances.

0

Returned by MongoDB applications upon successful exit.

2

The specified options are in error or are incompatible with other options.

3

Returned by mongod if there is a mismatch between hostnames specified on the command line and in the local.sources collection. mongod may also return this status if oplog collection in the local database is not readable.

4

The version of the database is different from the version supported by the mongod (or mongod.exe) instance. The instance exits cleanly. Restart mongod with the --upgrade option to upgrade the database to the version supported by this mongod instance.

5

Returned by mongod if a moveChunk operation fails to confirm a commit.

12

Returned by the mongod.exe process on Windows when it receives a Control-C, Close, Break or Shutdown event.

14

Returned by MongoDB applications which encounter an unrecoverable error, an uncaught exception or uncaught signal. The system exits without performing a clean shut down.

20

Message: ERROR: wsastartup failed <reason>

Returned by MongoDB applications on Windows following an error in the WSAStartup function.

Message: NT Service Error

Returned by MongoDB applications for Windows due to failures installing, starting or removing the NT Service for the application.

45

Returned when a MongoDB application cannot open a file or cannot obtain a lock on a file.

47

MongoDB applications exit cleanly following a large clock skew (32768 milliseconds) event.

48

mongod exits cleanly if the server socket closes. The server socket is on port 27017 by default, or as specified to the --port run-time option.

49

Returned by mongod.exe or mongos.exe on Windows when either receives a shutdown message from the Windows Service Control Manager.

100

Returned by mongod when the process throws an uncaught exception.

Security

This section outlines basic security and risk management strategies and access control. The included tutorials outline specific tasks for configuring firewalls, authentication, and system privileges.

Security Introduction

A high-level introduction to security and MongoDB deployments.

Security Concepts

The core documentation of security.

Authentication

Mechanisms for verifying user and instance access to MongoDB.

Authorization

Control access to MongoDB instances using authorization.

Network Exposure and Security

Discusses potential security risks related to the network and strategies for decreasing possible network-based attack vectors for MongoDB.

Continue reading from Security Concepts for additional documentation of MongoDB’s security features and operation.

Security Tutorials

Tutorials for enabling and configuring security features for MongoDB.

Security Checklist

A high level overview of global security consideration for administrators of MongoDB deployments. Use this checklist if you are new to deploying MongoDB in production and want to implement high quality security practices.

Network Security Tutorials

Ensure that the underlying network configuration supports a secure operating environment for MongoDB deployments, and appropriately limits access to MongoDB deployments.

Access Control Tutorials

These tutorials describe procedures relevant for the configuration, operation, and maintenance of MongoDB’s access control system.

User and Role Management Tutorials

MongoDB’s access control system provides a flexible role-based access control system that you can use to limit access to MongoDB deployments. The tutorials in this section describe the configuration an setup of the authorization system.

Continue reading from Security Tutorials for additional tutorials that address the use and management of secure MongoDB deployments.

Create a Vulnerability Report

Report a vulnerability in MongoDB.

Security Reference

Reference for security related functions.

Security Introduction

Security Concepts

Authentication

Authorization

Collection-Level Access Control

Network Exposure and Security

Security and MongoDB API Interfaces

Auditing

Kerberos Authentication

Security Tutorials

Security Checklist

Network Security Tutorials

Configure Linux iptables Firewall for MongoDB

Configure Windows netsh Firewall for MongoDB

Configure mongod and mongos for SSL

SSL Configuration for Clients

Upgrade a Cluster to Use SSL

Configure MongoDB for FIPS

Security Deployment Tutorials

Deploy Replica Set and Configure Authentication and Authorization

Access Control Tutorials

Enable Client Access Control

Enable Authentication in a Sharded Cluster

Enable Authentication after Creating the User Administrator

Use x.509 Certificates to Authenticate Clients

Use x.509 Certificate for Membership Authentication

Authenticate Using SASL and LDAP with ActiveDirectory

Authenticate Using SASL and LDAP with OpenLDAP

Configure MongoDB with Kerberos Authentication on Linux

Configure MongoDB with Kerberos Authentication on Windows

Authenticate to a MongoDB Instance or Cluster

Generate a Key File

Troubleshoot Kerberos Authentication on Linux

Implement Field Level Redaction

User and Role Management Tutorials

Create a User Administrator

Add a User to a Database

Create an Administrative User with Unrestricted Access

Create a Role

Assign a User a Role

Verify User Privileges

Modify a User’s Access

View Roles

Change a User’s Password

Change Your Password and Custom Data

Configure System Events Auditing

Create a Vulnerability Report

Security Reference

Built-In Roles

system.roles Collection

system.users Collection

Resource Document

Privilege Actions

Default MongoDB Port

System Event Audit Messages

Security Release Notes

Security Introduction

Maintaining a secure MongoDB deployment requires administrators to implement controls to ensure that users and applications have access to only the data that they require. MongoDB provides features that allow administrators to implement these controls and restrictions for any MongoDB deployment.

If you are already familiar with security and MongoDB security practices, consider the Security Checklist for a collection of recommended actions to protect a MongoDB deployment.

Authentication

Before gaining access to a system all clients should identify themselves to MongoDB. This ensures that no client can access the data stored in MongoDB without being explicitly allowed.

MongoDB supports a number of authentication mechanisms that clients can use to verify their identity. MongoDB supports two mechanisms: a password-based challenge and response protocol and x.509 certificates. Additionally, MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] also provides support for LDAP proxy authentication and Kerberos authentication.

See Authentication for more information.

Role Based Access Control

Access control, i.e. authorization, determines a user’s access to resources and operations. Clients should only be able to perform the operations required to fulfill their approved functions. This is the “principle of least privilege” and limits the potential risk of a compromised application.

MongoDB’s role-based access control system allows administrators to control all access and ensure that all granted access applies as narrowly as possible. MongoDB does not enable authorization by default. When you enable authorization, MongoDB will require authentication for all connections.

When authorization is enabled, MongoDB controls a user’s access through the roles assigned to the user. A role consists of a set of privileges, where a privilege consists of actions, or a set of operations, and a resource upon which the actions are allowed.

Users may have one or more role that describes their access. MongoDB provides several built-in roles and users can construct specific roles tailored to clients’ actual requirements.

See Authorization for more information.

Auditing

Auditing provides administrators with the ability to verify that the implemented security policies are controlling activity in the system. Retaining audit information ensures that administrators have enough information to perform forensic investigations and comply with regulations and polices that require audit data.

See Auditing for more information.

Encryption

Transport Encryption

You can use SSL to encrypt all of MongoDB’s network traffic. SSL ensures that MongoDB network traffic is only readable by the intended client.

See Configure mongod and mongos for SSL for more information.

Encryption at Rest

There are two broad classes of approaches to encrypting data at rest with MongoDB. You can use these solutions together or independently:

Application Level Encryption

Provide encryption on a per-field or per-document basis within the application layer. To encrypt document or field level data, write custom encryption and decryption routines or use a commercial solutions such as the Vormetric Data Security Platform [http://www.vormetric.com/sites/default/files/sb-MongoDB-Letter-2014-0611.pdf].

Storage Encryption

Encrypt all MongoDB data on the storage or operating system to ensure that only authorized processes can access protected data. A number of third-party libraries can integrate with the operating system to provide transparent disk-level encryption. For example:

Linux Unified Key Setup (LUKS)

LUKS is available for most Linux distributions. For configuration explanation, see the LUKS documentation from Red Hat [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/sec-Encryption.html].

IBM Guardium Data Encryption

IBM Guardium Data Encryption [http://www-03.ibm.com/software/products/en/infosphere-guardium-data-encryption] provides support for disk-level encryption for Linux and Windows operating systems.

Vormetric Data Security Platform

The Vormetric Data Security Platform [http://www.vormetric.com/sites/default/files/sb-MongoDB-Letter-2014-0611.pdf] provides disk and file-level encryption in addition to application level encryption.

Bitlocker Drive Encryption

Bitlocker Drive Encryption [http://technet.microsoft.com/en-us/library/hh831713.aspx] is a feature available on Windows Server 2008 and 2012 that provides disk encryption.

Properly configured disk encryption, when used alongside good security policies that protect relevant accounts, passwords, and encryption keys, can help ensure compliance with standards, including HIPAA, PCI-DSS, and FERPA.

Hardening Deployments and Environments

In addition to implementing controls within MongoDB, you should also place controls around MongoDB to reduce the risk exposure of the entire MongoDB system. This is a defense in depth strategy.

Hardening MongoDB extends the ideas of least privilege, auditing, and encryption outside of MongoDB. Reducing risk includes: configuring the network rules to ensure that only trusted hosts have access to MongoDB, and that the MongoDB processes only have access to the parts of the filesystem required for operation.

Security Concepts

These documents introduce and address concepts and strategies related to security practices in MongoDB deployments.

Authentication

Mechanisms for verifying user and instance access to MongoDB.

Authorization

Control access to MongoDB instances using authorization.

Collection-Level Access Control

Scope privileges to specific collections.

Network Exposure and Security

Discusses potential security risks related to the network and strategies for decreasing possible network-based attack vectors for MongoDB.

Security and MongoDB API Interfaces

Discusses potential risks related to MongoDB’s JavaScript, HTTP and REST interfaces, including strategies to control those risks.

Auditing

Audit server and client activity for mongod and mongos instances.

Kerberos Authentication

Kerberos authentication and MongoDB.

Authentication

Authorization

Collection-Level Access Control

Network Exposure and Security

Security and MongoDB API Interfaces

Auditing

Kerberos Authentication

Authentication

Authentication is the process of verifying the identity of a client. When access control, i.e. authorization, is enabled, MongoDB requires all clients to authenticate themselves first in order to determine the access for the client.

Although authentication and authorization are closely connected, authentication is distinct from authorization. Authentication verifies the identity of a user; authorization determines the verified user’s access to resources and operations.

MongoDB supports a number of authentication mechanisms that clients can use to verify their identity. These mechanisms allow MongoDB to integrate into your existing authentication system. See Authentication Mechanisms for details.

In addition to verifying the identity of a client, MongoDB can require members of replica sets and sharded clusters to authenticate their membership to their respective replica set or sharded cluster. See Authentication Between MongoDB Instances for more information.

Client Users

To authenticate a client in MongoDB, you must add a corresponding user to MongoDB. When adding a user, you create the user in a specific database. Together, the user’s name and database serve as a unique identifier for that user. That is, if two users have the same name but are created in different databases, they are two separate users. To authenticate, the client must authenticate the user against the user’s database. For instance, if using the mongo shell as a client, you can specify the database for the user with the –authenticationDatabase option.

To add and manage user information, MongoDB provides the db.createUser() method as well as other user management methods. For an example of adding a user to MongoDB, see Add a User to a Database.

MongoDB stores all user information, including name, password, and the user's database, in the system.users collection in the admin database.

Authentication Mechanisms

MongoDB supports multiple authentication mechanisms. MongoDB’s default authentication method is a challenge and response mechanism (MONGODB-CR). MongoDB also supports x509 certificate authentication, LDAP proxy authentication, and Kerberos authentication.

This section introduces the mechanisms available in MongoDB.

To specify the authentication mechanism to use, see authenticationMechanisms.

MONGODB-CR Authentication

MONGODB-CR is a challenge-response mechanism that authenticates users through passwords. MONGODB-CR is the default mechanism.

When you use MONGODB-CR authentication, MONGODB-CR verifies the user against the user’s name, password and database. The user’s database is the database where the user was created, and the user’s database and the user’s name together serves to identify the user.

Using key files, you can also use MONGODB-CR authentication for the internal member authentication of replica set members and sharded cluster members. The contents of the key files serve as the shared password for the members. You must store the key file on each mongod or mongos instance for that replica set or sharded cluster. The content of the key file is arbitrary but must be the same on all mongod and mongos instances that connect to each other.

See Generate a Key File for instructions on generating a key file and turning on key file authentication for members.

x.509 Certificate Authentication

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secure SSL connection.

To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords. See Client x.509 Certificate for more information.

For membership authentication, members of sharded clusters and replica sets can use x.509 certificates instead of key files. See Use x.509 Certificate for Membership Authentication for more information.

Kerberos Authentication

MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server systems.

To use MongoDB with Kerberos, you must have a properly configured Kerberos deployment, configured Kerberos service principals for MongoDB, and added Kerberos user principal to MongoDB.

See Kerberos Authentication for more information on Kerberos and MongoDB. To configure MongoDB to use Kerberos authentication, see Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows.

LDAP Proxy Authority Authentication

MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. See Authenticate Using SASL and LDAP with OpenLDAP and Authenticate Using SASL and LDAP with ActiveDirectory.

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards.

Authentication Behavior

Client Authentication

Clients can authenticate using the challenge and response, x.509, LDAP Proxy and Kerberos mechanisms.

Each client connection should authenticate as exactly one user. If a client authenticates to a database as one user and later authenticates to the same database as a different user, the second authentication invalidates the first. While clients can authenticate as multiple users if the users are defined on different databases, we recommend authenticating as one user at a time, providing the user with appropriate privileges on the databases required by the user.

See Authenticate to a MongoDB Instance or Cluster for more information.

Authentication Between MongoDB Instances

You can authenticate members of replica sets and sharded clusters. To authenticate members of a single MongoDB deployment to each other, MongoDB can use the keyFile and x.509 mechanisms. Using keyFile authentication for members also enables authorization.

Always run replica sets and sharded clusters in a trusted networking environment. Ensure that the network permits only trusted traffic to reach each mongod and mongos instance.

Use your environment’s firewall and network routing to ensure that traffic only from clients and other members can reach your mongod and mongos instances. If needed, use virtual private networks (VPNs) to ensure secure connections over wide area networks (WANs).

Always ensure that:

Your network configuration will allow every member of the replica set or sharded cluster to contact every other member.

If you use MongoDB’s authentication system to limit access to your infrastructure, ensure that you configure a keyFile on all members to permit authentication.

See Generate a Key File for instructions on generating a key file and turning on key file authentication for members. For an example of using key files for sharded cluster authentication, see Enable Authentication in a Sharded Cluster.

Authentication on Sharded Clusters

In sharded clusters, applications authenticate to directly to mongos instances, using credentials stored in the admin database of the config servers. The shards in the sharded cluster also have credentials, and clients can authenticate directly to the shards to perform maintenance directly on the shards. In general, applications and clients should connect to the sharded cluster through the mongos.

Changed in version 2.6: Previously, the credentials for authenticating to a database on a cluster resided on the primary shard for that database.

Some maintenance operations, such as cleanupOrphaned, compact, rs.reconfig(), require direct connections to specific shards in a sharded cluster. To perform these operations with authentication enabled, you must connect directly to the shard and authenticate as a shard local administrative user. To create a shard local administrative user, connect directly to the shard and create the user. MongoDB stores shard local users in the admin database of the shard itself. These shard local users are completely independent from the users added to the sharded cluster via mongos. Shard local users are local to the shard and are inaccessible by mongos. Direct connections to a shard should only be for shard-specific maintenance and configuration.

Localhost Exception

The localhost exception allows you to enable authorization before creating the first user in the system. When active, the localhost exception allows all connections from the localhost interface to have full access to that instance. The exception applies only when there are no users created in the MongoDB instance.

If you use the localhost exception when deploying a new MongoDB system, the first user you create must be in the admin database with privileges to create other users, such as a user with the userAdmin or userAdminAnyDatabase role. See Enable Client Access Control and Create a User Administrator for more information.

In the case of a sharded cluster, the localhost exception can apply to the cluster as a whole or separately to each shard. The localhost exception can apply to the cluster as a whole if there are no user information stored on the config servers and clients access via mongos instances.

The localhost exception can apply separately to each shard if there is no user information stored on the shard itself and clients connect to the shard directly.

To prevent unauthorized access to a cluster’s shards, you must either create an administrator on each shard or disable the localhost exception. To disable the localhost exception, use setParameter to set the enableLocalhostAuthBypass parameter to 0 during startup.

Authorization

MongoDB employs Role-Based Access Control (RBAC) to govern access to a MongoDB system. A user is granted one or more roles that determine the user’s access to database resources and operations. Outside of role assignments, the user has no access to the system.

MongoDB does not enable authorization by default. You can enable authorization using the --auth or the --keyFile options, or if using a configuration file, with the security.authorization or the security.keyFile settings.

MongoDB provides built-in roles, each with a dedicated purpose for a common use case. Examples include the read, readWrite, dbAdmin, and root roles.

Administrators also can create new roles and privileges to cater to operational needs. Administrators can assign privileges scoped as granularly as the collection level.

When granted a role, a user receives all the privileges of that role. A user can have several roles concurrently, in which case the user receives the union of all the privileges of the respective roles.

Roles

A role consists of privileges that pair resources with allowed operations. Each privilege is defined directly in the role or inherited from another role.

A role’s privileges apply to the database where the role is created. A role created on the admin database can include privileges that apply to all databases or to the cluster.

A user assigned a role receives all the privileges of that role. The user can have multiple roles and can have different roles on different databases.

Roles always grant privileges and never limit access. For example, if a user has both read and readWriteAnyDatabase roles on a database, the greater access prevails.

Privileges

A privilege consists of a specified resource and the actions permitted on the resource.

A privilege resource is either a database, collection, set of collections, or the cluster. If the cluster, the affiliated actions affect the state of the system rather than a specific database or collection.

An action is a command or method the user is allowed to perform on the resource. A resource can have multiple allowed actions. For available actions see Privilege Actions.

For example, a privilege that includes the update action allows a user to modify existing documents on the resource. To additionally grant the user permission to create documents on the resource, the administrator would add the insert action to the privilege.

For privilege syntax, see admin.system.roles.privileges.

Inherited Privileges

A role can include one or more existing roles in its definition, in which case the role inherits all the privileges of the included roles.

A role can inherit privileges from other roles in its database. A role created on the admin database can inherit privileges from roles in any database.

User-Defined Roles

New in version 2.6.

User administrators can create custom roles to ensure collection-level and command-level granularity and to adhere to the policy of least privilege. Administrators create and edit roles using the role management commands.

MongoDB scopes a user-defined role to the database in which it is created and uniquely identifies the role by the pairing of its name and its database. MongoDB stores the roles in the admin database’s system.roles collection. Do not access this collection directly but instead use the role management commands to view and edit custom roles.

Collection-Level Access Control

By creating a role with privileges that are scoped to a specific collection in a particular database, administrators can implement collection-level access control.

See Collection-Level Access Control for more information.

Users

MongoDB stores user credentials in the protected admin.system.users. Use the user management methods to view and edit user credentials.

Role Assignment to Users

User administrators create the users that access the system’s databases. MongoDB’s user management commands let administrators create users and assign them roles.

MongoDB scopes a user to the database in which the user is created. MongoDB stores all user definitions in the admin database, no matter which database the user is scoped to. MongoDB stores users in the admin database’s system.users collection. Do not access this collection directly but instead use the user management commands.

The first role assigned in a database should be either userAdmin or userAdminAnyDatabase. This user can then create all other users in the system. See Create a User Administrator.

Protect the User and Role Collections

MongoDB stores role and user data in the protected admin.system.roles and admin.system.users collections, which are only accessible using the user management methods.

If you disable access control, do not modify the admin.system.roles and admin.system.users collections using normal insert() and update() operations.

Additional Information

See the reference section for documentation of all built-in-roles and all available privilege actions. Also consider the reference for the form of the resource documents.

To create users see the Create a User Administrator and Add a User to a Database tutorials.

Collection-Level Access Control

Collection-level access control allows administrators to grant users privileges that are scoped to specific collections.

Administrators can implement collection-level access control through user-defined roles. By creating a role with privileges that are scoped to a specific collection in a particular database, administrators can provision users with roles that grant privileges on a collection level.

Privileges and Scope

A privilege consists of actions and the resources upon which the actions are permissible; i.e. the resources define the scope of the actions for that privilege.

By specifying both the database and the collection in the resource document for a privilege, administrator can limit the privilege actions just to a specific collection in a specific database. Each privilege action in a role can be scoped to a different collection.

For example, a user defined role can contain the following privileges:

privileges: [
  { resource: { db: "products", collection: "inventory" }, actions: [ "find", "update", "insert" ] },
  { resource: { db: "products", collection: "orders" },  actions: [ "find" ] }
]

The first privilege scopes its actions to the inventory collection of the products database. The second privilege scopes its actions to the orders collection of the products database.

Additional Information

For more information on user-defined roles and MongoDB authorization model, see Authorization. For a tutorial on creating user-defined roles, see Create a Role.

Network Exposure and Security

By default, MongoDB programs (i.e. mongos and mongod) will bind to all available network interfaces (i.e. IP addresses) on a system.

This page outlines various runtime options that allow you to limit access to MongoDB programs.

Configuration Options

You can limit the network exposure with the following mongod and mongos configuration options: enabled, net.http.RESTInterfaceEnabled, bindIp, and port. You can use a configuration file to specify these settings.

nohttpinterface

The enabled setting for mongod and mongos instances disables the “home” status page.

Changed in version 2.6: The mongod and mongos instances run with the http interface disabled by default.

The status interface is read-only by default, and the default port for the status page is 28017. Authentication does not control or affect access to this interface.

Important

Disable this interface for production deployments. If you enable this interface, you should only allow trusted clients to access this port. See Firewalls.

rest

The net.http.RESTInterfaceEnabled setting for mongod enables a fully interactive administrative REST interface, which is disabled by default. The net.http.RESTInterfaceEnabled configuration makes the http status interface [1], which is read-only by default, fully interactive. Use the net.http.RESTInterfaceEnabled setting with the enabled setting.

The REST interface does not support any authentication and you should always restrict access to this interface to only allow trusted clients to connect to this port.

You may also enable this interface on the command line as mongod --rest --httpinterface.

Important

Disable this option for production deployments. If do you leave this interface enabled, you should only allow trusted clients to access this port.

[1]
Starting in version 2.6, http interface is disabled by default.

bind_ip

The bindIp setting for mongod and mongos instances limits the network interfaces on which MongoDB programs will listen for incoming connections. You can also specify a number of interfaces by passing bindIp a comma separated list of IP addresses. You can use the mongod --bind_ip and mongos --bind_ip option on the command line at run time to limit the network accessibility of a MongoDB program.

Important

Make sure that your mongod and mongos instances are only accessible on trusted networks. If your system has more than one network interface, bind MongoDB programs to the private or internal network interface.

port

The port setting for mongod and mongos instances changes the main port on which the mongod or mongos instance listens for connections. The default port is 27017. Changing the port does not meaningfully reduce risk or limit exposure. You may also specify this option on the command line as mongod --port or mongos --port. Setting port also indirectly sets the port for the HTTP status interface, which is always available on the port numbered 1000 greater than the primary mongod port.

Only allow trusted clients to connect to the port for the mongod and mongos instances. See Firewalls.

See also Security Considerations and Default MongoDB Port.

Firewalls

Firewalls allow administrators to filter and control access to a system by providing granular control over what network communications. For administrators of MongoDB, the following capabilities are important: limiting incoming traffic on a specific port to specific systems, and limiting incoming traffic from untrusted hosts.

On Linux systems, the iptables interface provides access to the underlying netfilter firewall. On Windows systems, netsh command line interface provides access to the underlying Windows Firewall. For additional information about firewall configuration, see Configure Linux iptables Firewall for MongoDB and Configure Windows netsh Firewall for MongoDB.

For best results and to minimize overall exposure, ensure that only traffic from trusted sources can reach mongod and mongos instances and that the mongod and mongos instances can only connect to trusted outputs.

See also

For MongoDB deployments on Amazon’s web services, see the Amazon EC2 [http://docs.mongodb.org/ecosystem/platforms/amazon-ec2] page, which addresses Amazon’s Security Groups and other EC2-specific security features.

Virtual Private Networks

Virtual private networks, or VPNs, make it possible to link two networks over an encrypted and limited-access trusted network. Typically MongoDB users who use VPNs use SSL rather than IPSEC VPNs for performance issues.

Depending on configuration and implementation, VPNs provide for certificate validation and a choice of encryption protocols, which requires a rigorous level of authentication and identification of all clients. Furthermore, because VPNs provide a secure tunnel, by using a VPN connection to control access to your MongoDB instance, you can prevent tampering and “man-in-the-middle” attacks.

Security and MongoDB API Interfaces

The following section contains strategies to limit risks related to MongoDB’s available interfaces including JavaScript, HTTP, and REST interfaces.

JavaScript and the Security of the mongo Shell

The following JavaScript evaluation behaviors of the mongo shell represents risk exposures.

JavaScript Expression or JavaScript File

The mongo program can evaluate JavaScript expressions using the command line --eval option. Also, the mongo program can evaluate a JavaScript file (.js) passed directly to it (e.g. mongo someFile.js).

Because the mongo program evaluates the JavaScript directly, inputs should only come from trusted sources.

.mongorc.js File

If a .mongorc.js file exists [1], the mongo shell will evaluate a .mongorc.js file before starting. You can disable this behavior by passing the mongo --norc option.

[1]
On Linux and Unix systems, mongo reads the .mongorc.js file from $HOME/.mongorc.js (i.e. ~/.mongorc.js). On Windows, mongo.exe reads the .mongorc.js file from %HOME%.mongorc.js or %HOMEDRIVE%%HOMEPATH%.mongorc.js.

HTTP Status Interface

The HTTP status interface provides a web-based interface that includes a variety of operational data, logs, and status reports regarding the mongod or mongos instance. The HTTP interface is always available on the port numbered 1000 greater than the primary mongod port. By default, the HTTP interface port is 28017, but is indirectly set using the port option which allows you to configure the primary mongod port.

Without the net.http.RESTInterfaceEnabled setting, this interface is entirely read-only, and limited in scope; nevertheless, this interface may represent an exposure. To disable the HTTP interface, set the enabled run time option or the --nohttpinterface command line option. See also Configuration Options.

REST API

The REST API to MongoDB provides additional information and write access on top of the HTTP Status interface. While the REST API does not provide any support for insert, update, or remove operations, it does provide administrative access, and its accessibility represents a vulnerability in a secure environment. The REST interface is disabled by default, and is not recommended for production use.

If you must use the REST API, please control and limit access to the REST API. The REST API does not include any support for authentication, even when running with authorization enabled.

See the following documents for instructions on restricting access to the REST API interface:

Configure Linux iptables Firewall for MongoDB

Configure Windows netsh Firewall for MongoDB

Auditing

New in version 2.6.

MongoDB Enterprise includes an auditing capability for mongod and mongos instances. The auditing facility allows administrators and users to track system activity for deployments with multiple users and applications. The auditing facility can write audit events to the console, the syslog, a JSON file, or a BSON file.

Audit Events and Filter

To enable auditing for MongoDB Enterprise, see Configure System Events Auditing.

Once enabled, the auditing system can record the following operations:

schema (DDL),

replica set,

authentication and authorization, and

general operations.

For details on the audit log messages, see System Event Audit Messages.

By default, the auditing system records all these operations; however, you can set up filters to restrict the events captured. To set up filters, see Filter Events.

Audit Guarantee

The auditing system writes every audit event [1] to an in-memory buffer of audit events. MongoDB writes this buffer to disk periodically. For events collected from any single connection, the events have a total order: if MongoDB writes one event to disk, the system guarantees that it has written all prior events for that connection to disk.

If an audit event entry corresponds to an operation that affects the durable state of the database, such as a modification to data, MongoDB will always write the audit event to disk before writing to the journal for that entry.

That is, before adding an operation to the journal, MongoDB writes all audit events on the connection that triggered the operation, up to and including the entry for the operation.

These auditing guarantees require that MongoDB run with journaling enabled.

Warning

MongoDB may lose events if the server terminates before it commits the events to the audit log. The client may receive confirmation of the event before MongoDB commits to the audit log. For example, while auditing an aggregation operation, the server might crash after returning the result but before the audit log flushes.

[1]
Audit configuration can include a filter to limit events to audit.

Kerberos Authentication

New in version 2.4.

Overview

MongoDB Enterprise provides support for Kerberos authentication of MongoDB clients to mongod and mongos. Kerberos is an industry standard authentication protocol for large client/server systems. Kerberos allows MongoDB and applications to take advantage of existing authentication infrastructure and processes.

Kerberos Components and MongoDB

Principals

In a Kerberos-based system, every participant in the authenticated communication is known as a “principal”, and every principal must have a unique name.

Principals belong to administrative units called realms. For each realm, the Kerberos Key Distribution Center (KDC) maintains a database of the realm’s principal and the principals’ associated “secret keys”.

For a client-server authentication, the client requests from the KDC a “ticket” for access to a specific asset. KDC uses the client’s secret and the server’s secret to construct the ticket which allows the client and server to mutually authenticate each other, while keeping the secrets hidden.

For the configuration of MongoDB for Kerberos support, two kinds of principal names are of interest: user principals and service principals.

User Principal

To authenticate using Kerberos, you must add the Kerberos user principals to MongoDB to the $external database. User principal names have the form:

<username>@<KERBEROS REALM>

For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB in the $external database.

For examples of adding a user to MongoDB as well as authenticating as that user, see Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows.

See also

User and Role Management Tutorials for general information regarding creating and managing users in MongoDB.

Service Principal

Every MongoDB mongod and mongos instance (or mongod.exe or mongos.exe on Windows) must have an associated service principal. Service principal names have the form:

<service>/<fully qualified domain name>@<KERBEROS REALM>

For MongoDB, the <service> defaults to mongodb. For example, if m1.example.com is a MongoDB server, and example.com maintains the EXAMPLE.COM Kerberos realm, then m1 should have the service principal name mongodb/m1.example.com@EXAMPLE.COM.

To specify a different value for <service>, use serviceName during the start up of mongod or mongos (or mongod.exe or mongos.exe). mongo shell or other clients may also specify a different service principal name using serviceName.

Service principal names must be reachable over the network using the fully qualified domain name (FQDN) part of its service principal name.

By default, Kerberos attempts to identify hosts using the /etc/kerb5.conf file before using DNS to resolve hosts.

On Windows, if running MongoDB as a service, see Assign Service Principal Name to MongoDB Windows Service.

Linux Keytab Files

Linux systems can store Kerberos authentication keys for a service principal in keytab files. Each Kerberized mongod and mongos instance running on Linux must have access to a keytab file containing keys for its service principal.

To keep keytab files secure, use file permissions that restrict access to only the user that runs the mongod or mongos process.

Tickets

On Linux, MongoDB clients can use Kerberos’s kinit program to initialize a credential cache for authenticating the user principal to servers.

Windows Active Directory

Unlike on Linux systems, mongod and mongos instances running on Windows do not require access to keytab files. Instead, the mongod and mongos instances read their server credentials from a credential store specific to the operating system.

However, from the Windows Active Directory, you can export a keytab file for use on Linux systems. See Ktpass [http://technet.microsoft.com/en-us/library/cc753771.aspx] for more information.

Authenticate With Kerberos

To configure MongoDB for Kerberos support and authenticate, see Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows.

Operational Considerations

The HTTP Console

The MongoDB HTTP Console [http://docs.mongodb.org/ecosystem/tools/http-interfaces/#http-console] interface does not support Kerberos authentication.

DNS

Each host that runs a mongod or mongos instance must have both A and PTR DNS records to provide forward and reverse lookup.

Without A and PTR DNS records, the host cannot resolve the components of the Kerberos domain or the Key Distribution Center (KDC).

System Time Synchronization

To successfully authenticate, the system time for each mongod and mongos instance must be within 5 minutes of the system time of the other hosts in the Kerberos infrastructure.

Kerberized MongoDB Environments

Driver Support

The following MongoDB drivers support Kerberos authentication:

Java [http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-java-driver/]

C# [http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-csharp-driver/]

C++ [http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-cpp-driver/]

Python [http://api.mongodb.org/python/current/examples/authentication.html]

Use with Additional MongoDB Authentication Mechanism

Although MongoDB supports the use of Kerberos authentication with other authentication mechanisms, only add the other mechanisms as necessary. See the Incorporate Additional Authentication Mechanisms section in Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows for details.

Additional Resources

MongoDB LDAP and Kerberos Authentication with Dell (Quest) Authentication Services [https://www.mongodb.com/blog/post/mongodb-ldap-and-kerberos-authentication-dell-quest-authentication-services]

MongoDB with Red Hat Enterprise Linux Identity Management and Kerberos [http://docs.mongodb.org/ecosystem/tutorial/manage-red-hat-enterprise-linux-identity-management/]

Security Tutorials

The following tutorials provide instructions for enabling and using the security features available in MongoDB.

Security Checklist

A high level overview of global security consideration for administrators of MongoDB deployments. Use this checklist if you are new to deploying MongoDB in production and want to implement high quality security practices.

Network Security Tutorials

Ensure that the underlying network configuration supports a secure operating environment for MongoDB deployments, and appropriately limits access to MongoDB deployments.

Configure Linux iptables Firewall for MongoDB

Basic firewall configuration patterns and examples for iptables on Linux systems.

Configure Windows netsh Firewall for MongoDB

Basic firewall configuration patterns and examples for netsh on Windows systems.

Configure mongod and mongos for SSL

SSL allows MongoDB clients to support encrypted connections to mongod instances.

Continue reading from Network Security Tutorials for more information on running MongoDB in secure environments.

Security Deployment Tutorials

These tutorials describe procedures for deploying MongoDB using authentication and authorization.

Access Control Tutorials

These tutorials describe procedures relevant for the configuration, operation, and maintenance of MongoDB’s access control system.

Enable Client Access Control

Describes the process for enabling authentication for MongoDB deployments.

Use x.509 Certificates to Authenticate Clients

Use x.509 for client authentication.

Use x.509 Certificate for Membership Authentication

Use x.509 for internal member authentication for replica sets and sharded clusters.

Configure MongoDB with Kerberos Authentication on Linux

For MongoDB Enterprise Linux, describes the process to enable Kerberos-based authentication for MongoDB deployments.

Continue reading from Access Control Tutorials for additional tutorials on configuring MongoDB’s authentication systems.

Enable Authentication after Creating the User Administrator

Describes an alternative process for enabling authentication for MongoDB deployments.

User and Role Management Tutorials

MongoDB’s access control system provides a flexible role-based access control system that you can use to limit access to MongoDB deployments. The tutorials in this section describe the configuration an setup of the authorization system.

Add a User to a Database

Create non-administrator users using MongoDB’s role-based authentication system.

Create a Role

Create custom role.

Modify a User’s Access

Modify the actions available to a user on specific database resources.

View Roles

View a role’s privileges.

Continue reading from User and Role Management Tutorials for additional tutorials on managing users and privileges in MongoDB’s authorization system.

Configure System Events Auditing

Enable and configure MongoDB Enterprise system event auditing feature.

Create a Vulnerability Report

Report a vulnerability in MongoDB.

Security Checklist

Network Security Tutorials

Configure Linux iptables Firewall for MongoDB

Configure Windows netsh Firewall for MongoDB

Configure mongod and mongos for SSL

SSL Configuration for Clients

Upgrade a Cluster to Use SSL

Configure MongoDB for FIPS

Security Deployment Tutorials

Deploy Replica Set and Configure Authentication and Authorization

Access Control Tutorials

Enable Client Access Control

Enable Authentication in a Sharded Cluster

Enable Authentication after Creating the User Administrator

Use x.509 Certificates to Authenticate Clients

Use x.509 Certificate for Membership Authentication

Authenticate Using SASL and LDAP with ActiveDirectory

Authenticate Using SASL and LDAP with OpenLDAP

Configure MongoDB with Kerberos Authentication on Linux

Configure MongoDB with Kerberos Authentication on Windows

Authenticate to a MongoDB Instance or Cluster

Generate a Key File

Troubleshoot Kerberos Authentication on Linux

Implement Field Level Redaction

User and Role Management Tutorials

Create a User Administrator

Add a User to a Database

Create an Administrative User with Unrestricted Access

Create a Role

Assign a User a Role

Verify User Privileges

Modify a User’s Access

View Roles

Change a User’s Password

Change Your Password and Custom Data

Configure System Events Auditing

Create a Vulnerability Report

Security Checklist

This documents provides a list of security measures that you should implement to protect your MongoDB installation.

Require Authentication

Enable MongoDB authentication and specify the authentication mechanism. You can use the MongoDB authentication mechanism or an existing external framework. Authentication requires that all clients and servers provide valid credentials before they can connect to the system. In clustered deployments, enable authentication for each MongoDB server.

See Authentication, Enable Client Access Control, and Enable Authentication in a Sharded Cluster.

Configure Role-Based Access Control

Create roles that define the exact access a set of users needs. Follow a principle of least privilege. Then create users and assign them only the roles they need to perform their operations. A user can be a person or a client application.

Create a user administrator first, then create additional users. Create a unique MongoDB user for each person and application that accesses the system.

See Authorization, Create a Role, Create a User Administrator, and Add a User to a Database.

Encrypt Communication

Configure MongoDB to use SSL for all incoming and outgoing connections. Use SSL to encrypt communication between mongod and mongos components of a MongoDB client, as well as between all applications and MongoDB.

See Configure mongod and mongos for SSL.

Limit Network Exposure

Ensure that MongoDB runs in a trusted network environment and limit the interfaces on which MongoDB instances listen for incoming connections. Allow only trusted clients to access the network interfaces and ports on which MongoDB instances are available.

See the bindIp setting, and see Configure Linux iptables Firewall for MongoDB and Configure Windows netsh Firewall for MongoDB.

Audit System Activity

Track access and changes to database configurations and data. MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] includes a system auditing facility that can record system events (e.g. user operations, connection events) on a MongoDB instance. These audit records permit forensic analysis and allow administrators to verify proper controls.

See Auditing and Configure System Events Auditing.

Encrypt and Protect Data

Encrypt MongoDB data on each host using file-system, device, or physical encryption. Protect MongoDB data using file-system permissions. MongoDB data includes data files, configuration files, auditing logs, and key files.

Run MongoDB with a Dedicated User

Run MongoDB processes with a dedicated operating system user account. Ensure that the account has permissions to access data but no unnecessary permissions.

See Install MongoDB for more information on running MongoDB.

Run MongoDB with Secure Configuration Options

MongoDB supports the execution of JavaScript code for certain server-side operations: mapReduce, group, eval, and $where. If you do not use these operations, disable server-side scripting by using the --noscripting option on the command line.

Use only the MongoDB wire protocol on production deployments. Do not enable the following, all of which enable the web server interface: enabled, net.http.JSONPEnabled, and net.http.RESTInterfaceEnabled. Leave these disabled, unless required for backwards compatibility.

Keep input validation enabled. MongoDB enables input validation by default through the wireObjectCheck setting. This ensures that all documents stored by the mongod instance are valid BSON.

Request a Security Technical Implementation Guide (where applicable)

The Security Technical Implementation Guide (STIG) contains security guidelines for deployments within the United States Department of Defense. MongoDB Inc. provides its STIG, upon request, for situations where it is required. Please request a copy [http://www.mongodb.com/lp/contact/stig-requests] for more information.

Consider Security Standards Compliance

For applications requiring HIPAA or PCI-DSS compliance, please refer to the MongoDB Security Reference Architecture [http://info.mongodb.com/rs/mongodb/images/MongoDB_Security_Architecture_WP.pdf] to learn more about how you can use the key security capabilities to build compliant application infrastructure.

Network Security Tutorials

The following tutorials provide information on handling network security for MongoDB.

Configure Linux iptables Firewall for MongoDB

Basic firewall configuration patterns and examples for iptables on Linux systems.

Configure Windows netsh Firewall for MongoDB

Basic firewall configuration patterns and examples for netsh on Windows systems.

Configure mongod and mongos for SSL

SSL allows MongoDB clients to support encrypted connections to mongod instances.

SSL Configuration for Clients

Configure clients to connect to MongoDB instances that use SSL.

Upgrade a Cluster to Use SSL

Rolling upgrade process to use SSL.

Configure MongoDB for FIPS

Configure for Federal Information Processing Standard (FIPS).

Configure Linux iptables Firewall for MongoDB

Configure Windows netsh Firewall for MongoDB

Configure mongod and mongos for SSL

SSL Configuration for Clients

Upgrade a Cluster to Use SSL

Configure MongoDB for FIPS

Configure Linux iptables Firewall for MongoDB

On contemporary Linux systems, the iptables program provides methods for managing the Linux Kernel’s netfilter or network packet filtering capabilities. These firewall rules make it possible for administrators to control what hosts can connect to the system, and limit risk exposure by limiting the hosts that can connect to a system.

This document outlines basic firewall configurations for iptables firewalls on Linux. Use these approaches as a starting point for your larger networking organization. For a detailed overview of security practices and risk management for MongoDB, see Security Concepts.

See also

For MongoDB deployments on Amazon’s web services, see the Amazon EC2 [http://docs.mongodb.org/ecosystem/platforms/amazon-ec2] page, which addresses Amazon’s Security Groups and other EC2-specific security features.

Overview

Rules in iptables configurations fall into chains, which describe the process for filtering and processing specific streams of traffic. Chains have an order, and packets must pass through earlier rules in a chain to reach later rules. This document addresses only the following two chains:

INPUT

Controls all incoming traffic.

OUTPUT

Controls all outgoing traffic.

Given the default ports of all MongoDB processes, you must configure networking rules that permit only required communication between your application and the appropriate mongod and mongos instances.

Be aware that, by default, the default policy of iptables is to allow all connections and traffic unless explicitly disabled. The configuration changes outlined in this document will create rules that explicitly allow traffic from specific addresses and on specific ports, using a default policy that drops all traffic that is not explicitly allowed. When you have properly configured your iptables rules to allow only the traffic that you want to permit, you can Change Default Policy to DROP.

Patterns

This section contains a number of patterns and examples for configuring iptables for use with MongoDB deployments. If you have configured different ports using the port configuration setting, you will need to modify the rules accordingly.

Traffic to and from mongod Instances

This pattern is applicable to all mongod instances running as standalone instances or as part of a replica set.

The goal of this pattern is to explicitly allow traffic to the mongod instance from the application server. In the following examples, replace <ip-address> with the IP address of the application server:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 27017 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27017 -m state --state ESTABLISHED -j ACCEPT

The first rule allows all incoming traffic from <ip-address> on port 27017, which allows the application server to connect to the mongod instance. The second rule, allows outgoing traffic from the mongod to reach the application server.

Optional

If you have only one application server, you can replace <ip-address> with either the IP address itself, such as: 198.51.100.55. You can also express this using CIDR notation as 198.51.100.55/32. If you want to permit a larger block of possible IP addresses you can allow traffic from a /24 using one of the following specifications for the <ip-address>, as follows:

10.10.10.10/24
10.10.10.10/255.255.255.0

Traffic to and from mongos Instances

mongos instances provide query routing for sharded clusters. Clients connect to mongos instances, which behave from the client’s perspective as mongod instances. In turn, the mongos connects to all mongod instances that are components of the sharded cluster.

Use the same iptables command to allow traffic to and from these instances as you would from the mongod instances that are members of the replica set. Take the configuration outlined in the Traffic to and from mongod Instances section as an example.

Traffic to and from a MongoDB Config Server

Config servers, host the config database that stores metadata for sharded clusters. Each production cluster has three config servers, initiated using the mongod --configsvr option. [1] Config servers listen for connections on port 27019. As a result, add the following iptables rules to the config server to allow incoming and outgoing connection on port 27019, for connection to the other config servers.

iptables -A INPUT -s <ip-address> -p tcp --destination-port 27019 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27019 -m state --state ESTABLISHED -j ACCEPT

Replace <ip-address> with the address or address space of all the mongod that provide config servers.

Additionally, config servers need to allow incoming connections from all of the mongos instances in the cluster and all mongod instances in the cluster. Add rules that resemble the following:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 27019 -m state --state NEW,ESTABLISHED -j ACCEPT

Replace <ip-address> with the address of the mongos instances and the shard mongod instances.

[1]
You also can run a config server by using the configsvr value for the clusterRole setting in a configuration file.

Traffic to and from a MongoDB Shard Server

For shard servers, running as mongod --shardsvr [2] Because the default port number is 27018 when running with the shardsvr value for the clusterRole setting, you must configure the following iptables rules to allow traffic to and from each shard:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 27018 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27018 -m state --state ESTABLISHED -j ACCEPT

Replace the <ip-address> specification with the IP address of all mongod. This allows you to permit incoming and outgoing traffic between all shards including constituent replica set members, to:

all mongod instances in the shard’s replica sets.

all mongod instances in other shards. [3]

Furthermore, shards need to be able make outgoing connections to:

all mongos instances.

all mongod instances in the config servers.

Create a rule that resembles the following, and replace the <ip-address> with the address of the config servers and the mongos instances:

iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27018 -m state --state ESTABLISHED -j ACCEPT

[2]
You can also specify the shard server option with the shardsvr value for the clusterRole setting in the configuration file. Shard members are also often conventional replica sets using the default port.

[3]
All shards in a cluster need to be able to communicate with all other shards to facilitate chunk and balancing operations.

Provide Access For Monitoring Systems

The mongostat diagnostic tool, when running with the --discover needs to be able to reach all components of a cluster, including the config servers, the shard servers, and the mongos instances.

If your monitoring system needs access the HTTP interface, insert the following rule to the chain:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 28017 -m state --state NEW,ESTABLISHED -j ACCEPT

Replace <ip-address> with the address of the instance that needs access to the HTTP or REST interface. For all deployments, you should restrict access to this port to only the monitoring instance.

Optional

For config server mongod instances running with the shardsvr value for the clusterRole setting, the rule would resemble the following:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 28018 -m state --state NEW,ESTABLISHED -j ACCEPT

For config server mongod instances running with the configsvr value for the clusterRole setting, the rule would resemble the following:

iptables -A INPUT -s <ip-address> -p tcp --destination-port 28019 -m state --state NEW,ESTABLISHED -j ACCEPT

Change Default Policy to DROP

The default policy for iptables chains is to allow all traffic. After completing all iptables configuration changes, you must change the default policy to DROP so that all traffic that isn’t explicitly allowed as above will not be able to reach components of the MongoDB deployment. Issue the following commands to change this policy:

iptables -P INPUT DROP

iptables -P OUTPUT DROP

Manage and Maintain iptables Configuration

This section contains a number of basic operations for managing and using iptables. There are various front end tools that automate some aspects of iptables configuration, but at the core all iptables front ends provide the same basic functionality:

Make all iptables Rules Persistent

By default all iptables rules are only stored in memory. When your system restarts, your firewall rules will revert to their defaults. When you have tested a rule set and have guaranteed that it effectively controls traffic you can use the following operations to you should make the rule set persistent.

On Red Hat Enterprise Linux, Fedora Linux, and related distributions you can issue the following command:

service iptables save

On Debian, Ubuntu, and related distributions, you can use the following command to dump the iptables rules to the /etc/iptables.conf file:

iptables-save > /etc/iptables.conf

Run the following operation to restore the network rules:

iptables-restore < /etc/iptables.conf

Place this command in your rc.local file, or in the /etc/network/if-up.d/iptables file with other similar operations.

List all iptables Rules

To list all of currently applied iptables rules, use the following operation at the system shell.

iptables --L

Flush all iptables Rules

If you make a configuration mistake when entering iptables rules or simply need to revert to the default rule set, you can use the following operation at the system shell to flush all rules:

iptables --F

If you’ve already made your iptables rules persistent, you will need to repeat the appropriate procedure in the Make all iptables Rules Persistent section.

Configure Windows netsh Firewall for MongoDB

On Windows Server systems, the netsh program provides methods for managing the Windows Firewall. These firewall rules make it possible for administrators to control what hosts can connect to the system, and limit risk exposure by limiting the hosts that can connect to a system.

This document outlines basic Windows Firewall configurations. Use these approaches as a starting point for your larger networking organization. For a detailed over view of security practices and risk management for MongoDB, see Security Concepts.

See also

Windows Firewall [http://technet.microsoft.com/en-us/network/bb545423.aspx] documentation from Microsoft.

Overview

Windows Firewall processes rules in an ordered determined by rule type, and parsed in the following order:

Windows Service Hardening

Connection security rules

Authenticated Bypass Rules

Block Rules

Allow Rules

Default Rules

By default, the policy in Windows Firewall allows all outbound connections and blocks all incoming connections.

Given the default ports of all MongoDB processes, you must configure networking rules that permit only required communication between your application and the appropriate mongod.exe and mongos.exe instances.

The configuration changes outlined in this document will create rules which explicitly allow traffic from specific addresses and on specific ports, using a default policy that drops all traffic that is not explicitly allowed.

You can configure the Windows Firewall with using the netsh command line tool or through a windows application. On Windows Server 2008 this application is Windows Firewall With Advanced Security in Administrative Tools. On previous versions of Windows Server, access the Windows Firewall application in the System and Security control panel.

The procedures in this document use the netsh command line tool.

Patterns

This section contains a number of patterns and examples for configuring Windows Firewall for use with MongoDB deployments. If you have configured different ports using the port configuration setting, you will need to modify the rules accordingly.

Traffic to and from mongod.exe Instances

This pattern is applicable to all mongod.exe instances running as standalone instances or as part of a replica set. The goal of this pattern is to explicitly allow traffic to the mongod.exe instance from the application server.

netsh advfirewall firewall add rule name="Open mongod port 27017" dir=in action=allow protocol=TCP localport=27017

This rule allows all incoming traffic to port 27017, which allows the application server to connect to the mongod.exe instance.

Windows Firewall also allows enabling network access for an entire application rather than to a specific port, as in the following example:

netsh advfirewall firewall add rule name="Allowing mongod" dir=in action=allow program=" C:\mongodb\bin\mongod.exe"

You can allow all access for a mongos.exe server, with the following invocation:

netsh advfirewall firewall add rule name="Allowing mongos" dir=in action=allow program=" C:\mongodb\bin\mongos.exe"

Traffic to and from mongos.exe Instances

mongos.exe instances provide query routing for sharded clusters. Clients connect to mongos.exe instances, which behave from the client’s perspective as mongod.exe instances. In turn, the mongos.exe connects to all mongod.exe instances that are components of the sharded cluster.

Use the same Windows Firewall command to allow traffic to and from these instances as you would from the mongod.exe instances that are members of the replica set.

netsh advfirewall firewall add rule name="Open mongod shard port 27018" dir=in action=allow protocol=TCP localport=27018

Traffic to and from a MongoDB Config Server

Configuration servers, host the config database that stores metadata for sharded clusters. Each production cluster has three configuration servers, initiated using the mongod --configsvr option. [1] Configuration servers listen for connections on port 27019. As a result, add the following Windows Firewall rules to the config server to allow incoming and outgoing connection on port 27019, for connection to the other config servers.

netsh advfirewall firewall add rule name="Open mongod config svr port 27019" dir=in action=allow protocol=TCP localport=27019

Additionally, config servers need to allow incoming connections from all of the mongos.exe instances in the cluster and all mongod.exe instances in the cluster. Add rules that resemble the following:

netsh advfirewall firewall add rule name="Open mongod config svr inbound" dir=in action=allow protocol=TCP remoteip=<ip-address> localport=27019

Replace <ip-address> with the addresses of the mongos.exe instances and the shard mongod.exe instances.

[1]
You also can run a config server by using the configsrv value for the clusterRole setting in a configuration file.

Traffic to and from a MongoDB Shard Server

For shard servers, running as mongod --shardsvr [2] Because the default port number is 27018 when running with the shardsvr value for the clusterRole setting, you must configure the following Windows Firewall rules to allow traffic to and from each shard:

netsh advfirewall firewall add rule name="Open mongod shardsvr inbound" dir=in action=allow protocol=TCP remoteip=<ip-address> localport=27018
netsh advfirewall firewall add rule name="Open mongod shardsvr outbound" dir=out action=allow protocol=TCP remoteip=<ip-address> localport=27018

Replace the <ip-address> specification with the IP address of all mongod.exe instances. This allows you to permit incoming and outgoing traffic between all shards including constituent replica set members to:

all mongod.exe instances in the shard’s replica sets.

all mongod.exe instances in other shards. [3]

Furthermore, shards need to be able make outgoing connections to:

all mongos.exe instances.

all mongod.exe instances in the config servers.

Create a rule that resembles the following, and replace the <ip-address> with the address of the config servers and the mongos.exe instances:

netsh advfirewall firewall add rule name="Open mongod config svr outbound" dir=out action=allow protocol=TCP remoteip=<ip-address> localport=27018

[2]
You can also specify the shard server option with the shardsvr value for the clusterRole setting in the configuration file. Shard members are also often conventional replica sets using the default port.

[3]
All shards in a cluster need to be able to communicate with all other shards to facilitate chunk and balancing operations.

Provide Access For Monitoring Systems

The mongostat diagnostic tool, when running with the --discover needs to be able to reach all components of a cluster, including the config servers, the shard servers, and the mongos.exe instances.

If your monitoring system needs access the HTTP interface, insert the following rule to the chain:

netsh advfirewall firewall add rule name="Open mongod HTTP monitoring inbound" dir=in action=allow protocol=TCP remoteip=<ip-address> localport=28017

Replace <ip-address> with the address of the instance that needs access to the HTTP or REST interface. For all deployments, you should restrict access to this port to only the monitoring instance.

Optional

For config server mongod instances running with the shardsvr value for the clusterRole setting, the rule would resemble the following:

netsh advfirewall firewall add rule name="Open mongos HTTP monitoring inbound" dir=in action=allow protocol=TCP remoteip=<ip-address> localport=28018

For config server mongod instances running with the configsvr value for the clusterRole setting, the rule would resemble the following:

netsh advfirewall firewall add rule name="Open mongod configsvr HTTP monitoring inbound" dir=in action=allow protocol=TCP remoteip=<ip-address> localport=28019

Manage and Maintain Windows Firewall Configurations

This section contains a number of basic operations for managing and using netsh. While you can use the GUI front ends to manage the Windows Firewall, all core functionality is accessible is accessible from netsh.

Delete all Windows Firewall Rules

To delete the firewall rule allowing mongod.exe traffic:

netsh advfirewall firewall delete rule name="Open mongod port 27017" protocol=tcp localport=27017

netsh advfirewall firewall delete rule name="Open mongod shard port 27018" protocol=tcp localport=27018

List All Windows Firewall Rules

To return a list of all Windows Firewall rules:

netsh advfirewall firewall show rule name=all

Reset Windows Firewall

To reset the Windows Firewall rules:

netsh advfirewall reset

Backup and Restore Windows Firewall Rules

To simplify administration of larger collection of systems, you can export or import firewall systems from different servers) rules very easily on Windows:

Export all firewall rules with the following command:

netsh advfirewall export "C:\temp\MongoDBfw.wfw"

Replace "C:\temp\MongoDBfw.wfw" with a path of your choosing. You can use a command in the following form to import a file created using this operation:

netsh advfirewall import "C:\temp\MongoDBfw.wfw"

Configure mongod and mongos for SSL

Overview

This document helps you to configure MongoDB to support SSL. MongoDB clients can use SSL to encrypt connections to mongod and mongos instances.

These instructions assume that you have already installed a build of MongoDB that includes SSL support and that your client driver supports SSL. For instructions on upgrading a cluster currently not using SSL to using SSL, see Upgrade a Cluster to Use SSL.

Changed in version 2.6: MongoDB’s SSL encryption only allows use of strong SSL ciphers with a minimum of 128-bit key length for all connections.

New in version 2.6: MongoDB Enterprise for Windows includes support for SSL.

Prerequisites

MongoDB Support

The default distribution of MongoDB [http://www.mongodb.org/downloads] does not contain support for SSL. To use SSL, you must either build MongoDB locally passing the --ssl option to scons or use MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

Client Support

See SSL Configuration for Clients to learn about SSL support for Python, Java, Ruby, and other clients.

Certificate Authorities

For production use, your MongoDB deployment should use valid certificates generated and signed by a single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.

.pem File

Before you can use SSL, you must have a .pem file containing a public key certificate and its associated private key.

MongoDB can use any valid SSL certificate issued by a certificate authority, or a self-signed certificate. If you use a self-signed certificate, although the communications channel will be encrypted, there will be no validation of server identity. Although such a situation will prevent eavesdropping on the connection, it leaves you vulnerable to a man-in-the-middle attack. Using a certificate signed by a trusted certificate authority will permit MongoDB drivers to verify the server’s identity.

In general, avoid using self-signed certificates unless the network is trusted.

Additionally, with regards to authentication among replica set/sharded cluster members, in order to minimize exposure of the private key and allow hostname validation, it is advisable to use different certificates on different servers.

For testing purposes, you can generate a self-signed certificate and private key on a Unix system with a command that resembles the following:

cd /etc/ssl/
openssl req -newkey rsa:2048 -new -x509 -days 365 -nodes -out mongodb-cert.crt -keyout mongodb-cert.key

This operation generates a new, self-signed certificate with no passphrase that is valid for 365 days. Once you have the certificate, concatenate the certificate and private key to a .pem file, as in the following example:

cat mongodb-cert.key mongodb-cert.crt > mongodb.pem

See also

Use x.509 Certificates to Authenticate Clients

Procedures

Set Up mongod and mongos with SSL Certificate and Key

To use SSL in your MongoDB deployment, include the following run-time options with mongod and mongos:

net.ssl.mode set to requireSSL. This setting restricts each server to use only SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed SSL modes on a port. See net.ssl.mode for details.

PEMKeyfile with the .pem file that contains the SSL certificate and key.

Consider the following syntax for mongod:

mongod --sslMode requireSSL --sslPEMKeyFile <pem>

For example, given an SSL certificate located at /etc/ssl/mongodb.pem, configure mongod to use SSL encryption for all connections with the following command:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem

Note

Specify <pem> with the full path name to the certificate.

If the private key portion of the <pem> is encrypted, specify the passphrase. See SSL Certificate Passphrase.

You may also specify these options in the configuration file, as in the following example:

sslMode = requireSSL
sslPEMKeyFile = /etc/ssl/mongodb.pem

To connect, to mongod and mongos instances using SSL, the mongo shell and MongoDB tools must include the --ssl option. See SSL Configuration for Clients for more information on connecting to mongod and mongos running with SSL.

See also

Upgrade a Cluster to Use SSL

Set Up mongod and mongos with Certificate Validation

To set up mongod or mongos for SSL encryption using an SSL certificate signed by a certificate authority, include the following run-time options during startup:

net.ssl.mode set to requireSSL. This setting restricts each server to use only SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed SSL modes on a port. See net.ssl.mode for details.

PEMKeyfile with the name of the .pem file that contains the signed SSL certificate and key.

CAFile with the name of the .pem file that contains the root certificate chain from the Certificate Authority.

Consider the following syntax for mongod:

mongod --sslMode requireSSL --sslPEMKeyFile <pem> --sslCAFile <ca>

For example, given a signed SSL certificate located at /etc/ssl/mongodb.pem and the certificate authority file at /etc/ssl/ca.pem, you can configure mongod for SSL encryption as follows:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

Note

Specify the <pem> file and the <ca> file with either the full path name or the relative path name.

If the <pem> is encrypted, specify the passphrase. See SSL Certificate Passphrase.

You may also specify these options in the configuration file, as in the following example:

sslMode = requireSSL
sslPEMKeyFile = /etc/ssl/mongodb.pem
sslCAFile = /etc/ssl/ca.pem

To connect, to mongod and mongos instances using SSL, the mongo tools must include the both the --ssl and --sslPEMKeyFile option. See SSL Configuration for Clients for more information on connecting to mongod and mongos running with SSL.

See also

Upgrade a Cluster to Use SSL

Block Revoked Certificates for Clients

To prevent clients with revoked certificates from connecting, include the sslCRLFile to specify a .pem file that contains revoked certificates.

For example, the following mongod with SSL configuration includes the sslCRLFile setting:

mongod --sslMode requireSSL --sslCRLFile /etc/ssl/ca-crl.pem --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

Clients with revoked certificates in the /etc/ssl/ca-crl.pem will not be able to connect to this mongod instance.

Validate Only if a Client Presents a Certificate

In most cases it is important to ensure that clients present valid certificates. However, if you have clients that cannot present a client certificate, or are transitioning to using a certificate authority you may only want to validate certificates from clients that present a certificate.

If you want to bypass validation for clients that don’t present certificates, include the weakCertificateValidation run-time option with mongod and mongos. If the client does not present a certificate, no validation occurs. These connections, though not validated, are still encrypted using SSL.

For example, consider the following mongod with an SSL configuration that includes the weakCertificateValidation setting:

mongod --sslMode requireSSL --sslWeakCertificateValidation --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

Then, clients can connect either with the option --ssl and no certificate or with the option --ssl and a valid certificate. See SSL Configuration for Clients for more information on SSL connections for clients.

Note

If the client presents a certificate, the certificate must be a valid certificate.

All connections, including those that have not presented certificates are encrypted using SSL.

SSL Certificate Passphrase

The PEM files for PEMKeyfile and ClusterFile may be encrypted. With encrypted PEM files, you must specify the passphrase at startup with a command-line or a configuration file option or enter the passphrase when prompted.

Changed in version 2.6: In previous versions, you can only specify the passphrase with a command-line or a configuration file option.

To specify the passphrase in clear text on the command line or in a configuration file, use the PEMKeyPassword and/or the ClusterPassword option.

To have MongoDB prompt for the passphrase at the start of mongod or mongos and avoid specifying the passphrase in clear text, omit the PEMKeyPassword and/or the ClusterPassword option. MongoDB will prompt for each passphrase as necessary.

Important

The passphrase prompt option is available if you run the MongoDB instance in the foreground with a connected terminal. If you run mongod or mongos in a non-interactive session (e.g. without a terminal or as a service on Windows), you cannot use the passphrase prompt option.

Run in FIPS Mode

See Configure MongoDB for FIPS for more details.

SSL Configuration for Clients

Clients must have support for SSL to work with a mongod or a mongos instance that has SSL support enabled. The current versions of the Python, Java, Ruby, Node.js, .NET, and C++ drivers have support for SSL, with full support coming in future releases of other drivers.

See also

Configure mongod and mongos for SSL.

mongo Shell SSL Configuration

For SSL connections, you must use the mongo shell built with SSL support or distributed with MongoDB Enterprise. To support SSL, mongo has the following settings:

--ssl

--sslPEMKeyFile with the name of the .pem file that contains the SSL certificate and key.

--sslCAFile with the name of the .pem file that contains the certificate from the Certificate Authority (CA).

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyPassword option if the client certificate-key file is encrypted.

Connect to MongoDB Instance with SSL Encryption

To connect to a mongod or mongos instance that requires only a SSL encryption mode, start mongo shell with --ssl, as in the following:

mongo --ssl

Connect to MongoDB Instance that Requires Client Certificates

To connect to a mongod or mongos that requires CA-signed client certificates, start the mongo shell with --ssl and the --sslPEMKeyFile option to specify the signed certificate-key file, as in the following:

mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

Connect to MongoDB Instance that Validates when Presented with a Certificate

To connect to a mongod or mongos instance that only requires valid certificates when the client presents a certificate, start mongo shell either with the --ssl ssl and no certificate or with the --ssl ssl and a valid signed certificate.

For example, if mongod is running with weak certificate validation, both of the following mongo shell clients can connect to that mongod:

mongo --ssl
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

Important

If the client presents a certificate, the certificate must be valid.

MMS Monitoring Agent

The MMS Monitoring agent will also have to connect via SSL in order to gather its statistics. Because the agent already utilizes SSL for its communications to the MMS servers, this is just a matter of enabling SSL support in MMS itself on a per host basis.

Use the “Edit” host button (i.e. the pencil) on the Hosts page in the MMS console to enable SSL.

Please see the MMS documentation [https://docs.mms.mongodb.com/] for more information about MMS configuration.

PyMongo

Add the “ssl=True” parameter to a PyMongo MongoClient [http://api.mongodb.org/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient] to create a MongoDB connection to an SSL MongoDB instance:

from pymongo import MongoClient
c = MongoClient(host="mongodb.example.net", port=27017, ssl=True)

To connect to a replica set, use the following operation:

from pymongo import MongoReplicaSetClient
c = MongoReplicaSetClient("mongodb.example.net:27017",
                          replicaSet="mysetname", ssl=True)

PyMongo also supports an “ssl=true” option for the MongoDB URI:

mongodb://mongodb.example.net:27017/?ssl=true

For more details, see the Python MongoDB Driver page [http://docs.mongodb.org/ecosystem/drivers/python].

Java

Consider the following example “SSLApp.java” class file:

import com.mongodb.*;
import javax.net.ssl.SSLSocketFactory;

public class SSLApp {

    public static void main(String args[])  throws Exception {

        MongoClientOptions o = new MongoClientOptions.Builder()
                .socketFactory(SSLSocketFactory.getDefault())
                .build();

        MongoClient m = new MongoClient("localhost", o);

        DB db = m.getDB( "test" );
        DBCollection c = db.getCollection( "foo" );

        System.out.println( c.findOne() );
    }
}

For more details, see the Java MongoDB Driver page [http://docs.mongodb.org/ecosystem/drivers/java].

Ruby

The recent versions of the Ruby driver have support for connections to SSL servers. Install the latest version of the driver with the following command:

gem install mongo

Then connect to a standalone instance, using the following form:

require 'rubygems'
require 'mongo'

connection = MongoClient.new('localhost', 27017, :ssl => true)

Replace connection with the following if you’re connecting to a replica set:

connection = MongoReplicaSetClient.new(['localhost:27017'],
                                       ['localhost:27018'],
                                       :ssl => true)

Here, mongod instance run on “localhost:27017” and “localhost:27018”.

For more details, see the Ruby MongoDB Driver page [http://docs.mongodb.org/ecosystem/drivers/ruby].

Node.JS (node-mongodb-native)

In the node-mongodb-native [https://github.com/mongodb/node-mongodb-native] driver, use the following invocation to connect to a mongod or mongos instance via SSL:

var db1 = new Db(MONGODB, new Server("127.0.0.1", 27017,
                                     { auto_reconnect: false, poolSize:4, ssl:true } );

To connect to a replica set via SSL, use the following form:

var replSet = new ReplSetServers( [
    new Server( RS.host, RS.ports[1], { auto_reconnect: true } ),
    new Server( RS.host, RS.ports[0], { auto_reconnect: true } ),
    ],
  {rs_name:RS.name, ssl:true}
);

For more details, see the Node.JS MongoDB Driver page [http://docs.mongodb.org/ecosystem/drivers/node-js].

.NET

As of release 1.6, the .NET driver supports SSL connections with mongod and mongos instances. To connect using SSL, you must add an option to the connection string, specifying ssl=true as follows:

var connectionString = "mongodb://localhost/?ssl=true";
var server = MongoServer.Create(connectionString);

The .NET driver will validate the certificate against the local trusted certificate store, in addition to providing encryption of the server. This behavior may produce issues during testing if the server uses a self-signed certificate. If you encounter this issue, add the sslverifycertificate=false option to the connection string to prevent the .NET driver from validating the certificate, as follows:

var connectionString = "mongodb://localhost/?ssl=true&sslverifycertificate=false";
var server = MongoServer.Create(connectionString);

For more details, see the .NET MongoDB Driver page [http://docs.mongodb.org/ecosystem/drivers/csharp].

MongoDB Tools

Changed in version 2.6.

Various MongoDB utility programs supports SSL. These tools include:

mongodump

mongoexport

mongofiles

mongoimport

mongooplog

mongorestore

mongostat

mongotop

To use SSL connections with these tools, use the same SSL options as the mongo shell. See mongo Shell SSL Configuration.

Upgrade a Cluster to Use SSL

Note

The default distribution of MongoDB [http://www.mongodb.org/downloads] does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Configure mongod and mongos for SSL for more information about SSL and MongoDB.

Changed in version 2.6.

The MongoDB server supports listening for both SSL encrypted and unencrypted connections on the same TCP port. This allows upgrades of MongoDB clusters to use SSL encrypted connections. To upgrade from a MongoDB cluster using no SSL encryption to one using only SSL encryption, use the following rolling upgrade process:

For each node of a cluster, start the node with the option --sslMode set to allowSSL. The --sslMode allowSSL setting allows the node to accept both SSL and non-SSL incoming connections. Its connections to other servers do not use SSL. Include other SSL options as well as any other options that are required for your specific configuration. For example:

mongod --replSet <name> --sslMode allowSSL --sslPEMKeyFile <path to SSL Certificate and key PEM file> --sslCAFile <path to root CA PEM file>

Upgrade all nodes of the cluster to these settings.

Note

You may also specify these options in the configuration file, as in the following example:

sslMode = <disabled|allowSSL|preferSSL|requireSSL>
sslPEMKeyFile = <path to SSL certificate and key PEM file>
sslCAFile = <path to root CA PEM file>

Switch all clients to use SSL. See SSL Configuration for Clients.

For each node of a cluster, use the setParameter command to update the sslMode to preferSSL. [1] With preferSSL as its net.ssl.mode, the node accepts both SSL and non-SSL incoming connections, and its connections to other servers use SSL. For example:

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "preferSSL" } )

Upgrade all nodes of the cluster to these settings.

At this point, all connections should be using SSL.

For each node of the cluster, use the setParameter command to update the sslMode to requireSSL. [1] With requireSSL as its net.ssl.mode, the node will reject any non-SSL connections. For example:

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "requireSSL" } )

After the upgrade of all nodes, edit the configuration file with the appropriate SSL settings to ensure that upon subsequent restarts, the cluster uses SSL.

[1]
(1, 2) As an alternative to using the setParameter command, you can also restart the nodes with the appropriate SSL options and values.

Configure MongoDB for FIPS

New in version 2.6.

Overview

The Federal Information Processing Standard (FIPS) is a U.S. government computer security standard used to certify software modules and libraries that encrypt and decrypt data securely. You can configure MongoDB to run with a FIPS 140-2 certified library for OpenSSL. Configure FIPS to run by default or as needed from the command line.

Prerequisites

Only the MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] version supports FIPS mode. See Install MongoDB Enterprise to download and install MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise] to use FIPS mode.

Your system must have an OpenSSL library configured with the FIPS 140-2 module. At the command line, type openssl version to confirm your OpenSSL software includes FIPS support.

For Red Hat Enterprise Linux 6.x (RHEL 6.x) or its derivatives such as CentOS 6.x, the OpenSSL toolkit must be at least openssl-1.0.1e-16.el6_5 to use FIPS mode. To upgrade the toolkit for these platforms, issue the following command:

sudo yum update openssl

Some versions of Linux periodically execute a process to prelink dynamic libraries with pre-assigned addresses. This process modifies the OpenSSL libraries, specifically libcrypto. The OpenSSL FIPS mode will subsequently fail the signature check performed upon startup to ensure libcrypto has not been modified since compilation.

To configure the Linux prelink process to not prelink libcrypto:

sudo bash -c "echo '-b /usr/lib64/libcrypto.so.*' >>/etc/prelink.conf.d/openssl-prelink.conf"

Considerations

FIPS is property of the encryption system and not the access control system. However, if your environment requires FIPS compliant encryption and access control, you must ensure that the access control system uses only FIPS-compliant encryption.

MongoDB’s FIPS support covers the way that MongoDB uses OpenSSL for network encryption and X509 authentication. If you use Kerberos or LDAP Proxy authentication, you muse ensure that these external mechanisms are FIPS-compliant. MONGODB-CR authentication is not FIPS compliant.

Procedure

Configure MongoDB to use SSL

See Configure mongod and mongos for SSL for details about configuring OpenSSL.

Run mongod or mongos instance in FIPS mode

Perform these steps after you Configure mongod and mongos for SSL.

1

Change configuration file.

To configure your mongod or mongos instance to use FIPS mode, shut down the instance and update the configuration file with the following setting:

net:
   ssl:
      FIPSMode: true

Step 1: Change configuration file.

To configure your mongod or mongos instance to use FIPS mode, shut down the instance and update the configuration file with the following setting:

net:
   ssl:
      FIPSMode: true

2

Start mongod or mongos instance with configuration file.

For example, run this command to start the mongod instance with its configuration file:

mongod --config /etc/mongodb.conf

Step 2: Start mongod or mongos instance with configuration file.

For example, run this command to start the mongod instance with its configuration file:

mongod --config /etc/mongodb.conf

Confirm FIPS mode is running

Check the server log file for a message FIPS is active:

FIPS 140-2 mode activated

Security Deployment Tutorials

The following tutorials provide information in deploying MongoDB using authentication and authorization.

Deploy Replica Set and Configure Authentication and Authorization

Configure a replica set that has authentication enabled.

Deploy Replica Set and Configure Authentication and Authorization

Deploy Replica Set and Configure Authentication and Authorization

Overview

With authentication enabled, MongoDB forces all clients to identify themselves before granting access to the server. Authorization, in turn, allows administrators to define and limit the resources and operations that a user can access. Using authentication and authorization is a key part of a complete security strategy.

All MongoDB deployments support authentication. By default, MongoDB does not require authorization checking. You can enforce authorization checking when deploying MongoDB, or on an existing deployment; however, you cannot enable authorization checking on a running deployment without downtime.

This tutorial provides a procedure for creating a MongoDB replica set that uses the challenge-response authentication mechanism. The tutorial includes creation of a minimal authorization system to support basic operations.

Considerations

Authentication

In this procedure, you will configure MongoDB using the default challenge-response authentication mechanism, using the keyFile to supply the password for inter-process authentication. The content of the key file is the shared secret used for all internal authentication.

All deployments that enforce authorization checking should have one user administrator user that can create new users and modify existing users. During this procedure you will create a user administrator that you will use to administer this deployment.

Architecture

In a production, deploy each member of the replica set to its own machine and if possible bind to the standard MongoDB port of 27017. Use the bind_ip option to ensure that MongoDB listens for connections from applications on configured addresses.

For a geographically distributed replica sets, ensure that the majority of the set’s mongod instances reside in the primary site.

See Replica Set Deployment Architectures for more information.

Connectivity

Ensure that network traffic can pass between all members of the set and all clients in the network securely and efficiently. Consider the following:

Establish a virtual private network. Ensure that your network topology routes all traffic between members within a single site over the local area network.

Configure access control to prevent connections from unknown clients to the replica set.

Configure networking and firewall rules so that incoming and outgoing packets are permitted only on the default MongoDB port and only from within your deployment.

Finally ensure that each member of a replica set is accessible by way of resolvable DNS or hostnames. You should either configure your DNS names appropriately or set up your systems’ /etc/hosts file to reflect this configuration.

Configuration

Specify the run time configuration on each system in a configuration file stored in /etc/mongodb.conf or a related location. Create the directory where MongoDB stores data files before deploying MongoDB.

For more information about the run time options used above and other configuration options, see Configuration File Options.

Procedure

This procedure deploys a replica set in which all members use the same key file.

1

Start one member of the replica set.

This mongod should not enable auth.

Step 1: Start one member of the replica set.

This mongod should not enable auth.

2

Create administrative users.

The following operations will create two users: a user administrator that will be able to create and modify users (siteUserAdmin), and a root user (siteRootAdmin) that you will use to complete the remainder of the tutorial:

use admin
db.createUser( {
    user: "siteUserAdmin",
    pwd: "<password>",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  });
db.createUser( {
    user: "siteRootAdmin",
    pwd: "<password>",
    roles: [ { role: "root", db: "admin" } ]
  });

Step 2: Create administrative users.

The following operations will create two users: a user administrator that will be able to create and modify users (siteUserAdmin), and a root user (siteRootAdmin) that you will use to complete the remainder of the tutorial:

use admin
db.createUser( {
    user: "siteUserAdmin",
    pwd: "<password>",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  });
db.createUser( {
    user: "siteRootAdmin",
    pwd: "<password>",
    roles: [ { role: "root", db: "admin" } ]
  });

3

Stop the mongod instance.

Step 3: Stop the mongod instance.

4

Create the key file to be used by each member of the replica set.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

Step 4: Create the key file to be used by each member of the replica set.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

5

Copy the key file to each member of the replica set.

Copy the mongodb-keyfile to all hosts where components of a MongoDB deployment run. Set the permissions of these files to 600 so that only the owner of the file can read or write this file to prevent other users on the system from accessing the shared secret.

Step 5: Copy the key file to each member of the replica set.

Copy the mongodb-keyfile to all hosts where components of a MongoDB deployment run. Set the permissions of these files to 600 so that only the owner of the file can read or write this file to prevent other users on the system from accessing the shared secret.

6

Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the key file and the name of the replica set. Also specify other parameters as needed for your deployment. For replication-specific parameters, see Replication Options required by your deployment.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies parameters through the --keyFile and --replSet command-line options:

mongod --keyFile /mysecretdirectory/mongodb-keyfile --replSet "rs0"

The following example specifies parameters through a configuration file:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

Step 6: Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the key file and the name of the replica set. Also specify other parameters as needed for your deployment. For replication-specific parameters, see Replication Options required by your deployment.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies parameters through the --keyFile and --replSet command-line options:

mongod --keyFile /mysecretdirectory/mongodb-keyfile --replSet "rs0"

The following example specifies parameters through a configuration file:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

7

Connect to the member of the replica set where you created the administrative users.

Connect to the replica set member you started and authenticate as the siteRootAdmin user. From the mongo shell, use the following operation to authenticate:

use admin
db.auth("siteRootAdmin", "<password>");

Step 7: Connect to the member of the replica set where you created the administrative users.

Connect to the replica set member you started and authenticate as the siteRootAdmin user. From the mongo shell, use the following operation to authenticate:

use admin
db.auth("siteRootAdmin", "<password>");

8

Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

Step 8: Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

9

Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

Step 9: Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

10

Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

Step 10: Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

11

Check the status of the replica set.

Use the rs.status() operation:

rs.status()

Step 11: Check the status of the replica set.

Use the rs.status() operation:

rs.status()

12

Create additional users to address operational requirements.

You can use built-in roles to create common types of database users, such as the dbOwner role to create a database administrator, the readWrite role to create a user who can update data, or the read role to create user who can search data but no more. You also can define custom roles.

For example, the following creates a database administrator for the products database:

use products
db.createUser(
  {
    user: "productsDBAdmin",
    pwd: "password",
    roles:
    [
      {
        role: "dbOwner",
        db: "products"
      }
    ]
  }
)

For an overview of roles and privileges, see Authorization. For more information on adding users, see Add a User to a Database.

Step 12: Create additional users to address operational requirements.

You can use built-in roles to create common types of database users, such as the dbOwner role to create a database administrator, the readWrite role to create a user who can update data, or the read role to create user who can search data but no more. You also can define custom roles.

For example, the following creates a database administrator for the products database:

use products
db.createUser(
  {
    user: "productsDBAdmin",
    pwd: "password",
    roles:
    [
      {
        role: "dbOwner",
        db: "products"
      }
    ]
  }
)

For an overview of roles and privileges, see Authorization. For more information on adding users, see Add a User to a Database.

Access Control Tutorials

The following tutorials provide instructions for MongoDB’’s authentication and authorization related features.

Enable Client Access Control

Describes the process for enabling authentication for MongoDB deployments.

Enable Authentication in a Sharded Cluster

Control access to a sharded cluster through a key file and the keyFile setting on each of the cluster’s components.

Enable Authentication after Creating the User Administrator

Describes an alternative process for enabling authentication for MongoDB deployments.

Use x.509 Certificates to Authenticate Clients

Use x.509 for client authentication.

Use x.509 Certificate for Membership Authentication

Use x.509 for internal member authentication for replica sets and sharded clusters.

Authenticate Using SASL and LDAP with ActiveDirectory

Describes the process for authentication using SASL/LDAP with ActiveDirectory.

Authenticate Using SASL and LDAP with OpenLDAP

Describes the process for authentication using SASL/LDAP with OpenLDAP.

Configure MongoDB with Kerberos Authentication on Linux

For MongoDB Enterprise Linux, describes the process to enable Kerberos-based authentication for MongoDB deployments.

Configure MongoDB with Kerberos Authentication on Windows

For MongoDB Enterprise for Windows, describes the process to enable Kerberos-based authentication for MongoDB deployments.

Authenticate to a MongoDB Instance or Cluster

Describes the process for authenticating to MongoDB systems using the mongo shell.

Generate a Key File

Use key file to allow the components of MongoDB sharded cluster or replica set to mutually authenticate.

Troubleshoot Kerberos Authentication on Linux

Steps to troubleshoot Kerberos-based authentication for MongoDB deployments.

Implement Field Level Redaction

Describes the process to set up and access document content that can have different access levels for the same data.

Enable Client Access Control

Enable Authentication in a Sharded Cluster

Enable Authentication after Creating the User Administrator

Use x.509 Certificates to Authenticate Clients

Use x.509 Certificate for Membership Authentication

Authenticate Using SASL and LDAP with ActiveDirectory

Authenticate Using SASL and LDAP with OpenLDAP

Configure MongoDB with Kerberos Authentication on Linux

Configure MongoDB with Kerberos Authentication on Windows

Authenticate to a MongoDB Instance or Cluster

Generate a Key File

Troubleshoot Kerberos Authentication on Linux

Implement Field Level Redaction

Enable Client Access Control

Overview

Enabling access control on a MongoDB instance restricts access to the instance by requiring that users identify themselves when connecting. In this procedure, you enable access control and then create the instance’s first user, which must be a user administrator. The user administrator grants further access to the instance by creating additional users.

Considerations

If you create the user administrator before enabling access control, MongoDB disables the localhost exception. In that case, you must use the “Enable Authentication after Creating the User Administrator” procedure to enable access control.

This procedure uses the localhost exception to allow you to create the first user after enabling authentication. See Localhost Exception and Authentication for more information.

Procedure

1

Start the MongoDB instance with authentication enabled.

Start the mongod or mongos instance with the authorization or keyFile setting. Use authorization on a standalone instance. Use keyFile on an instance in a replica set or sharded cluster.

For example, to start a mongod with authentication enabled and a key file stored in /private/var, first set the following option in the mongod‘s configuration file:

security:
  keyFile: /private/var/key.pem

Then start the mongod and specify the config file. For example:

mongod --config /etc/mongodb/mongodb.conf

After you enable authentication, only the user administrator can connect to the MongoDB instance. The user administrator must log in and grant further access to the instance by creating additional users.

Step 1: Start the MongoDB instance with authentication enabled.

Start the mongod or mongos instance with the authorization or keyFile setting. Use authorization on a standalone instance. Use keyFile on an instance in a replica set or sharded cluster.

For example, to start a mongod with authentication enabled and a key file stored in /private/var, first set the following option in the mongod‘s configuration file:

security:
  keyFile: /private/var/key.pem

Then start the mongod and specify the config file. For example:

mongod --config /etc/mongodb/mongodb.conf

After you enable authentication, only the user administrator can connect to the MongoDB instance. The user administrator must log in and grant further access to the instance by creating additional users.

2

Connect to the MongoDB instance via the localhost exception.

Connect to the MongoDB instance from a client running on the same system. This access is made possible by the localhost exception.

Step 2: Connect to the MongoDB instance via the localhost exception.

Connect to the MongoDB instance from a client running on the same system. This access is made possible by the localhost exception.

3

Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

After you create the user administrator, the localhost exception is no longer available.

The mongo shell executes a number of commands at start up. As a result, when you log in as the user administrator, you may see authentication errors from one or more commands. You may ignore these errors, which are expected, because the userAdminAnyDatabase role does not have permissions to run some of the start up commands.

Step 3: Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

After you create the user administrator, the localhost exception is no longer available.

The mongo shell executes a number of commands at start up. As a result, when you log in as the user administrator, you may see authentication errors from one or more commands. You may ignore these errors, which are expected, because the userAdminAnyDatabase role does not have permissions to run some of the start up commands.

4

Create additional users.

Login in with the user administrator’s credentials and create additional users. See Add a User to a Database.

Step 4: Create additional users.

Login in with the user administrator’s credentials and create additional users. See Add a User to a Database.

Next Steps

If you need to disable access control for any reason, restart the process without the authorization or keyFile setting.

Enable Authentication in a Sharded Cluster

New in version 2.0: Support for authentication with sharded clusters.

Overview

When authentication is enabled on a sharded cluster every client that accesses the cluster must provide credentials. This includes MongoDB instances that access each other within the cluster.

To enable authentication on a sharded cluster, you must enable authentication individually on each component of the cluster. This means enabling authentication on each mongos and each mongod, including each config server, and all members of a shard’s replica set.

Authentication requires an authentication mechanism and, in most cases, a key file. The content of the key file must be the same on all cluster members.

Consideration

It is not possible to convert an existing sharded cluster that does not enforce access control to require authentication without taking all components of the cluster offline for a short period of time.

Procedure

1

Create a key file.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

Step 1: Create a key file.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

2

Enable authentication on each component in the cluster.

On each mongos and mongod in the cluster, including all config servers and shards, specify the key file using one of the following approaches:

Specify the key file in the configuration file.

In the configuration file, set the keyFile option to the key file’s path and then start the component, as in the following example:

security:
  keyFile: /srv/mongodb/keyfile

Specify the key file at runtime.

When starting the component, set the --keyFile option, which is an option for both mongos instances and mongod instances. Set the --keyFile to the key file’s path. The keyFile setting implies the authorization setting, which means in most cases you do not need to set authorization explicitly.

Step 2: Enable authentication on each component in the cluster.

On each mongos and mongod in the cluster, including all config servers and shards, specify the key file using one of the following approaches:

Specify the key file in the configuration file.

In the configuration file, set the keyFile option to the key file’s path and then start the component, as in the following example:

security:
  keyFile: /srv/mongodb/keyfile

Specify the key file at runtime.

When starting the component, set the --keyFile option, which is an option for both mongos instances and mongod instances. Set the --keyFile to the key file’s path. The keyFile setting implies the authorization setting, which means in most cases you do not need to set authorization explicitly.

3

Add users.

While connected to a mongos, add the first administrative user and then add subsequent users. See Create a User Administrator.

Step 3: Add users.

While connected to a mongos, add the first administrative user and then add subsequent users. See Create a User Administrator.

Related Documents

Authentication

Security

Use x.509 Certificate for Membership Authentication

Enable Authentication after Creating the User Administrator

Overview

Enabling authentication on a MongoDB instance restricts access to the instance by requiring that users identify themselves when connecting. In this procedure, you will create the instance’s first user, which must be a user administrator and then enable authentication. Then, you can authenticate as the user administrator to create additional users and grant additional access to the instance.

This procedures outlines how enable authentication after creating the user administrator. The approach requires a restart. To enable authentication without restarting, see Enable Client Access Control.

Considerations

This document outlines a procedure for enabling authentication for MongoDB instance where you create the first user on an existing MongoDB system that does not require authentication before restarting the instance and requiring authentication. You can use the localhost exception to gain access to a system with no users and authentication enabled. See Enable Client Access Control for the description of that procedure.

Procedure

1

Start the MongoDB instance without authentication.

Start the mongod or mongos instance without the authorization or keyFile setting. For example:

mongod --port 27017 --dbpath /data/db1

For details on starting a mongod or mongos, see Manage mongod Processes or Deploy a Sharded Cluster.

Step 1: Start the MongoDB instance without authentication.

Start the mongod or mongos instance without the authorization or keyFile setting. For example:

mongod --port 27017 --dbpath /data/db1

For details on starting a mongod or mongos, see Manage mongod Processes or Deploy a Sharded Cluster.

2

Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

Step 2: Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

3

Re-start the MongoDB instance with authentication enabled.

Re-start the mongod or mongos instance with the authorization or keyFile setting. Use authorization on a standalone instance. Use keyFile on an instance in a replica set or sharded cluster.

The following example enables authentication on a standalone mongod using the authorization command-line option:

mongod --auth --config /etc/mongodb/mongodb.conf

Step 3: Re-start the MongoDB instance with authentication enabled.

Re-start the mongod or mongos instance with the authorization or keyFile setting. Use authorization on a standalone instance. Use keyFile on an instance in a replica set or sharded cluster.

The following example enables authentication on a standalone mongod using the authorization command-line option:

mongod --auth --config /etc/mongodb/mongodb.conf

4

Create additional users.

Log in with the user administrator’s credentials and create additional users. See Add a User to a Database.

Step 4: Create additional users.

Log in with the user administrator’s credentials and create additional users. See Add a User to a Database.

Next Steps

If you need to disable authentication for any reason, restart the process without the authorization or keyFile option.

Use x.509 Certificates to Authenticate Clients

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secure SSL connection. The x.509 client authentication allows clients to authenticate to servers with certificates rather than with a username and password.

To use x.509 authentication for the internal authentication of replica set/sharded cluster members, see Use x.509 Certificate for Membership Authentication.

Prerequisites

Certificate Authority

For production use, your MongoDB deployment should use valid certificates generated and signed by a single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.

Client x.509 Certificate

The client certificate must have the following properties:

A single Certificate Authority (CA) must issue the certificates for both the client and the server.

Client certificates must contain the following fields:

keyUsage = digitalSignature
extendedKeyUsage = clientAuth

A client x.509 certificate’s subject, which contains the Distinguished Name (DN), must differ from that of a Member x.509 Certificate to prevent client certificates from identifying the client as a cluster member and granting full permission on the system. Specifically, the subjects must differ with regards to at least one of the following attributes: Organization (O), the Organizational Unit (OU) or the Domain Component (DC).

Each unique MongoDB user must have a unique certificate.

Procedures

Configure MongoDB Server

Use Command-line Options

You can configure the MongoDB server from the command line, e.g.:

mongod --clusterAuthMode x509 --sslMode requireSSL --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

Use Configuration File

You may also specify these options in the configuration file.

Starting in MongoDB 2.6, you can specify the configuration for MongoDB in YAML format, e.g.:

security:
   clusterAuthMode: x509
net:
   ssl:
      mode: requireSSL
      PEMKeyFile: <path to SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

For backwards compatibility, you can also specify the configuration using the older configuration file format [http://docs.mongodb.org/v2.4/reference/configuration], e.g.:

clusterAuthMode = x509
sslMode = requireSSL
sslPEMKeyFile = <path to SSL certificate and key PEM file>
sslCAFile = <path to the root CA PEM file>

Include any additional options, SSL or otherwise, that are required for your specific configuration.

Add x.509 Certificate subject as a User

To authenticate with a client certificate, you must first add the value of the subject from the client certificate as a MongoDB user. Each unique x.509 client certificate corresponds to a single MongoDB user; i.e. you cannot use a single client certificate to authenticate more than one MongoDB user.

You can retrieve the subject from the client certificate with the following command:

openssl x509 -in <pathToClient PEM> -inform PEM -subject -nameopt RFC2253

The command returns the subject string as well as certificate:

subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry
-----BEGIN CERTIFICATE-----
# ...
-----END CERTIFICATE-----

Add the value of the subject, omitting the spaces, from the certificate as a user.

For example, in the mongo shell, to add the user with both the readWrite role in the test database and the userAdminAnyDatabase role which is defined only in the admin database:

db.getSiblingDB("$external").runCommand(
  {
    createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry",
    roles: [
             { role: 'readWrite', db: 'test' },
             { role: 'userAdminAnyDatabase', db: 'admin' }
           ],
    writeConcern: { w: "majority" , wtimeout: 5000 }
  }
)

In the above example, to add the user with the readWrite role in the test database, the role specification document specified 'test' in the db field. To add userAdminAnyDatabase role for the user, the above example specified 'admin' in the db field.

Note

Some roles are defined only in the admin database, including: clusterAdmin, readAnyDatabase, readWriteAnyDatabase, dbAdminAnyDatabase, and userAdminAnyDatabase. To add a user with these roles, specify 'admin' in the db.

See Add a User to a Database for details on adding a user with roles.

Authenticate with a x.509 Certificate

To authenticate with a client certificate, you must first add a MongoDB user that corresponds to the client certificate. See Add x.509 Certificate subject as a User.

To authenticate, use the db.auth() method in the $external database, specifying "MONGODB-X509" for the mechanism field, and the user that corresponds to the client certificate for the user field.

For example, if using the mongo shell,

Connect mongo shell to the mongod set up for SSL:

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>

To perform the authentication, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509", and for the user field, specify the user, or the subject, that corresponds to the client certificate.

db.getSiblingDB("$external").auth(
  {
    mechanism: "MONGODB-X509",
    user: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry"
  }
)

Use x.509 Certificate for Membership Authentication

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secure SSL connection. Sharded cluster members and replica set members can use x.509 certificates to verify their membership to the cluster or the replica set instead of using keyfiles. The membership authentication is an internal process.

For client authentication with x.509, see Use x.509 Certificates to Authenticate Clients.

Member x.509 Certificate

The member certificate, used for internal authentication to verify membership to the sharded cluster or a replica set, must have the following properties:

A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set.

The Distinguished Name (DN), found in the member certificate’s subject, must specify a non-empty value for at least one of the following attributes: Organization (O), the Organizational Unit (OU) or the Domain Component (DC).

The Organization attributes (O‘s), the Organizational Unit attributes (OU‘s), and the Domain Components (DC‘s) must match those from the certificates for the other cluster members. To match, the certificate must match all specifications of these attributes, or even the non-specification of these attributes. The order of the attributes does not matter.

In the following example, the two DN‘s contain matching specifications for O, OU as well as the non-specification of the DC attribute.

CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2

However, the following two DN‘s contain a mismatch for the OU attribute since one contains two OU specifications and the other, only one specification.

CN=host1,OU=Dept1,OU=Sales,O=MongoDB
CN=host2,OU=Dept1,O=MongoDB

Either the Common Name (CN) or one of the Subject Alternative Name (SAN) entries must match the hostname of the server, used by the other members of the cluster.

For example, the certificates for a cluster could have the following subjects:

subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US

You can use an x509 certificate that does not have Extended Key Usage (EKU) attributes set. If you use EKU attribute in the PEMKeyFile certificate, then specify the clientAuth and/or serverAuth attributes (i.e. “TLS Web Client Authentication” and “TLS Web Server Authentication,”) as needed. The certificate that you specify for the PEMKeyFile option requires the serverAuth attribute, and the certificate you specify to clusterFile requires the clientAuth attribute. If you omit ClusterFile, mongod will use the certificate specified to PEMKeyFile for member authentication.

Configure Replica Set/Sharded Cluster

Use Command-line Options

To specify the x.509 certificate for internal cluster member authentication, append the additional SSL options --clusterAuthMode and --sslClusterFile, as in the following example for a member of a replica set:

mongod --replSet <name> --sslMode requireSSL --clusterAuthMode x509 --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>

Include any additional options, SSL or otherwise, that are required for your specific configuration. For instance, if the membership key is encrypted, set the --sslClusterPassword to the passphrase to decrypt the key or have MongoDB prompt for the passphrase. See SSL Certificate Passphrase for details.

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

Use Configuration File

You can specify the configuration for MongoDB in a YAML formatted configuration file, as in the following example:

security:
   clusterAuthMode: x509
net:
   ssl:
      mode: requireSSL
      PEMKeyFile: <path to SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>
      clusterFile: <path to x.509 membership certificate and key PEM file>

See security.clusterAuthMode, net.ssl.mode, net.ssl.PEMKeyFile, net.ssl.CAFile, and net.ssl.clusterFile for more information on the settings.

Upgrade from Keyfile Authentication to x.509 Authentication

To upgrade clusters that are currently using keyfile authentication to x.509 authentication, use a rolling upgrade process.

Clusters Currently Using SSL

For clusters using SSL and keyfile authentication, to upgrade to x.509 cluster authentication, use the following rolling upgrade process:

For each node of a cluster, start the node with the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node’s certificate. Include other SSL options as well as any other options that are required for your specific configuration. For example:

mongod --replSet <name> --sslMode requireSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL Certificate and key PEM file>  --sslCAFile <path to root CA PEM file>

With this setting, each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

Then, for each node of a cluster, connect to the node and use the setParameter command to update the clusterAuthMode to sendX509. [1] For example,

db.getSiblingDB('admin').runCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

With this setting, each node uses its x.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the clusterAuthMode to x509 to only use the x.509 certificate for authentication. [1] For example:

db.getSiblingDB('admin').runCommand( { setParameter: 1, clusterAuthMode: "x509" } )

After the upgrade of all nodes, edit the configuration file with the appropriate x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

Clusters Currently Not Using SSL

For clusters using keyfile authentication but not SSL, to upgrade to x.509 authentication, use the following rolling upgrade process:

For each node of a cluster, start the node with the option --sslMode set to allowSSL, the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node’s certificate. Include other SSL options as well as any other options that are required for your specific configuration. For example:

mongod --replSet <name> --sslMode allowSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL certificate and key PEM file>  --sslCAFile <path to root CA PEM file>

The --sslMode allowSSL setting allows the node to accept both SSL and non-SSL incoming connections. Its outgoing connections do not use SSL.

The --clusterAuthMode sendKeyFile setting allows each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members.

Upgrade all nodes of the cluster to these settings.

Then, for each node of a cluster, connect to the node and use the setParameter command to update the sslMode to preferSSL and the clusterAuthMode to sendX509. [1] For example:

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "preferSSL", clusterAuthMode: "sendX509" } )

With the sslMode set to preferSSL, the node accepts both SSL and non-SSL incoming connections, and its outgoing connections use SSL.

With the clusterAuthMode set to sendX509, each node uses its x.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members.

Upgrade all nodes of the cluster to these settings.

Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the sslMode to requireSSL and the clusterAuthMode to x509. [1] For example:

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "requireSSL", clusterAuthMode: "x509" } )

With the sslMode set to requireSSL, the node only uses SSL connections.

With the clusterAuthMode set to x509, the node only uses the x.509 certificate for authentication.

After the upgrade of all nodes, edit the configuration file with the appropriate SSL and x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

[1]
(1, 2, 3, 4) As an alternative to using the setParameter command, you can also restart the nodes with the appropriate SSL and x509 options and values.

Authenticate Using SASL and LDAP with ActiveDirectory

MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to configure a MongoDB cluster to authenticate users by proxying authentication requests to a specified Lightweight Directory Access Protocol (LDAP) service.

Considerations

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards. See Upgrade MongoDB to 2.6 for upgrade instructions.

Use secure encrypted or trusted connections between clients and the server, as well as between saslauthd and the LDAP server. The LDAP server uses the SASL PLAIN mechanism, sending and receiving data in plain text. You should use only a trusted channel such as a VPN, a connection encrypted with SSL, or a trusted wired network.

Configure saslauthd

LDAP support for user authentication requires proper configuration of the saslauthd daemon process as well as the MongoDB server.

1

Specify the mechanism.

On systems that configure saslauthd with the /etc/sysconfig/saslauthd file, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon Linux AMI, set the mechanism MECH to ldap:

MECH=ldap

On systems that configure saslauthd with the /etc/default/saslauthd file, such as Ubuntu, set the MECHANISMS option to ldap:

MECHANISMS="ldap"

Step 1: Specify the mechanism.

On systems that configure saslauthd with the /etc/sysconfig/saslauthd file, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon Linux AMI, set the mechanism MECH to ldap:

MECH=ldap

On systems that configure saslauthd with the /etc/default/saslauthd file, such as Ubuntu, set the MECHANISMS option to ldap:

MECHANISMS="ldap"

2

Adjust caching behavior.

On certain Linux distributions, saslauthd starts with the caching of authentication credentials enabled. Until restarted or until the cache expires, saslauthd will not contact the LDAP server to re-authenticate users in its authentication cache. This allows saslauthd to successfully authenticate users in its cache, even in the LDAP server is down or if the cached users’ credentials are revoked.

To set the expiration time (in seconds) for the authentication cache, see the -t option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

Step 2: Adjust caching behavior.

On certain Linux distributions, saslauthd starts with the caching of authentication credentials enabled. Until restarted or until the cache expires, saslauthd will not contact the LDAP server to re-authenticate users in its authentication cache. This allows saslauthd to successfully authenticate users in its cache, even in the LDAP server is down or if the cached users’ credentials are revoked.

To set the expiration time (in seconds) for the authentication cache, see the -t option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

3

Configure LDAP Options with ActiveDirectory.

If the saslauthd.conf file does not exist, create it. The saslauthd.conf file usually resides in the /etc folder. If specifying a different file path, see the -O option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

To use with ActiveDirectory, start saslauthd with the following configuration options set in the saslauthd.conf file:

ldap_servers: <ldap uri>
ldap_use_sasl: yes
ldap_mech: DIGEST-MD5
ldap_auth_method: fastbind

For the <ldap uri>, specify the uri of the ldap server. For example, ldap_servers: ldaps://ad.example.net.

For more information on saslauthd configuration, see http://www.openldap.org/doc/admin24/guide.html#Configuringsaslauthd.

Step 3: Configure LDAP Options with ActiveDirectory.

If the saslauthd.conf file does not exist, create it. The saslauthd.conf file usually resides in the /etc folder. If specifying a different file path, see the -O option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

To use with ActiveDirectory, start saslauthd with the following configuration options set in the saslauthd.conf file:

ldap_servers: <ldap uri>
ldap_use_sasl: yes
ldap_mech: DIGEST-MD5
ldap_auth_method: fastbind

For the <ldap uri>, specify the uri of the ldap server. For example, ldap_servers: ldaps://ad.example.net.

For more information on saslauthd configuration, see http://www.openldap.org/doc/admin24/guide.html#Configuringsaslauthd.

4

Test the saslauthd configuration.

Use testsaslauthd utility to test the saslauthd configuration. For example:

testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux

Step 4: Test the saslauthd configuration.

Use testsaslauthd utility to test the saslauthd configuration. For example:

testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux

Configure MongoDB

1

Add user to MongoDB for authentication.

Add the user to the $external database in MongoDB. To specify the user’s privileges, assign roles to the user.

For example, the following adds a user with read-only access to the records database.

db.getSiblingDB("$external").createUser(
    {
      user : <username>,
      roles: [ { role: "read", db: "records" } ]
    }
)

Add additional principals as needed. For more information about creating and managing users, see User Management Commands.

Step 1: Add user to MongoDB for authentication.

Add the user to the $external database in MongoDB. To specify the user’s privileges, assign roles to the user.

For example, the following adds a user with read-only access to the records database.

db.getSiblingDB("$external").createUser(
    {
      user : <username>,
      roles: [ { role: "read", db: "records" } ]
    }
)

Add additional principals as needed. For more information about creating and managing users, see User Management Commands.

2

Configure MongoDB server.

To configure the MongoDB server to use the saslauthd instance for proxy authentication, start the mongod with the following options:

--auth,

authenticationMechanisms parameter set to PLAIN, and

saslauthdPath parameter set to the path to the Unix-domain Socket of the saslauthd instance.

Configure the MongoDB server using either the command line option –setParameter or the configuration file. Specify additional configurations as appropriate for your configuration.

If you use the authorization option to enforce authentication, you will need privileges to create a user.

Use specific saslauthd socket path.

For socket path of /<some>/<path>/saslauthd, set the saslauthdPath to /<some>/<path>/saslauthd/mux, as in the following command line example:

mongod --auth --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Use default Unix-domain socket path.

To use the default Unix-domain socket path, set the saslauthdPath to the empty string "", as in the following command line example:

mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Step 2: Configure MongoDB server.

To configure the MongoDB server to use the saslauthd instance for proxy authentication, start the mongod with the following options:

--auth,

authenticationMechanisms parameter set to PLAIN, and

saslauthdPath parameter set to the path to the Unix-domain Socket of the saslauthd instance.

Configure the MongoDB server using either the command line option –setParameter or the configuration file. Specify additional configurations as appropriate for your configuration.

If you use the authorization option to enforce authentication, you will need privileges to create a user.

Use specific saslauthd socket path.

For socket path of /<some>/<path>/saslauthd, set the saslauthdPath to /<some>/<path>/saslauthd/mux, as in the following command line example:

mongod --auth --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Use default Unix-domain socket path.

To use the default Unix-domain socket path, set the saslauthdPath to the empty string "", as in the following command line example:

mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

3

Authenticate the user in the mongo shell.

To perform the authentication in the mongo shell, use the db.auth() method in the $external database.

Specify the value "PLAIN" in the mechanism field, the user and password in the user and pwd fields respectively, and the value false in the digestPassword field. You must specify false for digestPassword since the server must receive an undigested password to forward on to saslauthd, as in the following example:

db.getSiblingDB("$external").auth(
   {
     mechanism: "PLAIN",
     user: <username>,
     pwd:  <cleartext password>,
     digestPassword: false
   }
)

The server forwards the password in plain text. In general, use only on a trusted channel (VPN, SSL, trusted wired network). See Considerations.

Step 3: Authenticate the user in the mongo shell.

To perform the authentication in the mongo shell, use the db.auth() method in the $external database.

Specify the value "PLAIN" in the mechanism field, the user and password in the user and pwd fields respectively, and the value false in the digestPassword field. You must specify false for digestPassword since the server must receive an undigested password to forward on to saslauthd, as in the following example:

db.getSiblingDB("$external").auth(
   {
     mechanism: "PLAIN",
     user: <username>,
     pwd:  <cleartext password>,
     digestPassword: false
   }
)

The server forwards the password in plain text. In general, use only on a trusted channel (VPN, SSL, trusted wired network). See Considerations.

Authenticate Using SASL and LDAP with OpenLDAP

MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to configure a MongoDB cluster to authenticate users by proxying authentication requests to a specified Lightweight Directory Access Protocol (LDAP) service.

Considerations

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards. See Upgrade MongoDB to 2.6 for upgrade instructions.

Use secure encrypted or trusted connections between clients and the server, as well as between saslauthd and the LDAP server. The LDAP server uses the SASL PLAIN mechanism, sending and receiving data in plain text. You should use only a trusted channel such as a VPN, a connection encrypted with SSL, or a trusted wired network.

Configure saslauthd

LDAP support for user authentication requires proper configuration of the saslauthd daemon process as well as the MongoDB server.

1

Specify the mechanism.

On systems that configure saslauthd with the /etc/sysconfig/saslauthd file, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon Linux AMI, set the mechanism MECH to ldap:

MECH=ldap

On systems that configure saslauthd with the /etc/default/saslauthd file, such as Ubuntu, set the MECHANISMS option to ldap:

MECHANISMS="ldap"

Step 1: Specify the mechanism.

On systems that configure saslauthd with the /etc/sysconfig/saslauthd file, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon Linux AMI, set the mechanism MECH to ldap:

MECH=ldap

On systems that configure saslauthd with the /etc/default/saslauthd file, such as Ubuntu, set the MECHANISMS option to ldap:

MECHANISMS="ldap"

2

Adjust caching behavior.

On certain Linux distributions, saslauthd starts with the caching of authentication credentials enabled. Until restarted or until the cache expires, saslauthd will not contact the LDAP server to re-authenticate users in its authentication cache. This allows saslauthd to successfully authenticate users in its cache, even in the LDAP server is down or if the cached users’ credentials are revoked.

To set the expiration time (in seconds) for the authentication cache, see the -t option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

Step 2: Adjust caching behavior.

On certain Linux distributions, saslauthd starts with the caching of authentication credentials enabled. Until restarted or until the cache expires, saslauthd will not contact the LDAP server to re-authenticate users in its authentication cache. This allows saslauthd to successfully authenticate users in its cache, even in the LDAP server is down or if the cached users’ credentials are revoked.

To set the expiration time (in seconds) for the authentication cache, see the -t option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

3

Configure LDAP Options with OpenLDAP.

If the saslauthd.conf file does not exist, create it. The saslauthd.conf file usually resides in the /etc folder. If specifying a different file path, see the -O option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

To connect to an OpenLDAP server, update the saslauthd.conf file with the following configuration options:

ldap_servers: <ldap uri>
ldap_search_base: <search base>
ldap_filter: <filter>

The ldap_servers specifies the uri of the LDAP server used for authentication. In general, for OpenLDAP installed on the local machine, you can specify the value ldap://localhost:389 or if using LDAP over SSL, you can specify the value ldaps://localhost:636.

The ldap_search_base specifies distinguished name to which the search is relative. The search includes the base or objects below.

The ldap_filter specifies the search filter.

The values for these configuration options should correspond to the values specific for your test. For example, to filter on email, specify ldap_filter: (mail=%n) instead.

OpenLDAP Example

A sample saslauthd.conf file for OpenLDAP includes the following content:

ldap_servers: ldaps://ad.example.net
ldap_search_base: ou=Users,dc=example,dc=com
ldap_filter: (uid=%u)

To use this sample OpenLDAP configuration, create users with a uid attribute (login name) and place under the Users organizational unit (ou) under the domain components (dc) example and com.

For more information on saslauthd configuration, see http://www.openldap.org/doc/admin24/guide.html#Configuringsaslauthd.

Step 3: Configure LDAP Options with OpenLDAP.

If the saslauthd.conf file does not exist, create it. The saslauthd.conf file usually resides in the /etc folder. If specifying a different file path, see the -O option [http://www.linuxcommand.org/man_pages/saslauthd8.html] of saslauthd.

To connect to an OpenLDAP server, update the saslauthd.conf file with the following configuration options:

ldap_servers: <ldap uri>
ldap_search_base: <search base>
ldap_filter: <filter>

The ldap_servers specifies the uri of the LDAP server used for authentication. In general, for OpenLDAP installed on the local machine, you can specify the value ldap://localhost:389 or if using LDAP over SSL, you can specify the value ldaps://localhost:636.

The ldap_search_base specifies distinguished name to which the search is relative. The search includes the base or objects below.

The ldap_filter specifies the search filter.

The values for these configuration options should correspond to the values specific for your test. For example, to filter on email, specify ldap_filter: (mail=%n) instead.

OpenLDAP Example

A sample saslauthd.conf file for OpenLDAP includes the following content:

ldap_servers: ldaps://ad.example.net
ldap_search_base: ou=Users,dc=example,dc=com
ldap_filter: (uid=%u)

To use this sample OpenLDAP configuration, create users with a uid attribute (login name) and place under the Users organizational unit (ou) under the domain components (dc) example and com.

For more information on saslauthd configuration, see http://www.openldap.org/doc/admin24/guide.html#Configuringsaslauthd.

4

Test the saslauthd configuration.

Use testsaslauthd utility to test the saslauthd configuration. For example:

testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux

Step 4: Test the saslauthd configuration.

Use testsaslauthd utility to test the saslauthd configuration. For example:

testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux

Configure MongoDB

1

Add user to MongoDB for authentication.

Add the user to the $external database in MongoDB. To specify the user’s privileges, assign roles to the user.

For example, the following adds a user with read-only access to the records database.

db.getSiblingDB("$external").createUser(
    {
      user : <username>,
      roles: [ { role: "read", db: "records" } ]
    }
)

Add additional principals as needed. For more information about creating and managing users, see User Management Commands.

Step 1: Add user to MongoDB for authentication.

Add the user to the $external database in MongoDB. To specify the user’s privileges, assign roles to the user.

For example, the following adds a user with read-only access to the records database.

db.getSiblingDB("$external").createUser(
    {
      user : <username>,
      roles: [ { role: "read", db: "records" } ]
    }
)

Add additional principals as needed. For more information about creating and managing users, see User Management Commands.

2

Configure MongoDB server.

To configure the MongoDB server to use the saslauthd instance for proxy authentication, start the mongod with the following options:

--auth,

authenticationMechanisms parameter set to PLAIN, and

saslauthdPath parameter set to the path to the Unix-domain Socket of the saslauthd instance.

Configure the MongoDB server using either the command line option –setParameter or the configuration file. Specify additional configurations as appropriate for your configuration.

If you use the authorization option to enforce authentication, you will need privileges to create a user.

Use specific saslauthd socket path.

For socket path of /<some>/<path>/saslauthd, set the saslauthdPath to /<some>/<path>/saslauthd/mux, as in the following command line example:

mongod --auth --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Use default Unix-domain socket path.

To use the default Unix-domain socket path, set the saslauthdPath to the empty string "", as in the following command line example:

mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Step 2: Configure MongoDB server.

To configure the MongoDB server to use the saslauthd instance for proxy authentication, start the mongod with the following options:

--auth,

authenticationMechanisms parameter set to PLAIN, and

saslauthdPath parameter set to the path to the Unix-domain Socket of the saslauthd instance.

Configure the MongoDB server using either the command line option –setParameter or the configuration file. Specify additional configurations as appropriate for your configuration.

If you use the authorization option to enforce authentication, you will need privileges to create a user.

Use specific saslauthd socket path.

For socket path of /<some>/<path>/saslauthd, set the saslauthdPath to /<some>/<path>/saslauthd/mux, as in the following command line example:

mongod --auth --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

Use default Unix-domain socket path.

To use the default Unix-domain socket path, set the saslauthdPath to the empty string "", as in the following command line example:

mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN

Or if using a configuration file, specify the following parameters in the file:

auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN

3

Authenticate the user in the mongo shell.

To perform the authentication in the mongo shell, use the db.auth() method in the $external database.

Specify the value "PLAIN" in the mechanism field, the user and password in the user and pwd fields respectively, and the value false in the digestPassword field. You must specify false for digestPassword since the server must receive an undigested password to forward on to saslauthd, as in the following example:

db.getSiblingDB("$external").auth(
   {
     mechanism: "PLAIN",
     user: <username>,
     pwd:  <cleartext password>,
     digestPassword: false
   }
)

The server forwards the password in plain text. In general, use only on a trusted channel (VPN, SSL, trusted wired network). See Considerations.

Step 3: Authenticate the user in the mongo shell.

To perform the authentication in the mongo shell, use the db.auth() method in the $external database.

Specify the value "PLAIN" in the mechanism field, the user and password in the user and pwd fields respectively, and the value false in the digestPassword field. You must specify false for digestPassword since the server must receive an undigested password to forward on to saslauthd, as in the following example:

db.getSiblingDB("$external").auth(
   {
     mechanism: "PLAIN",
     user: <username>,
     pwd:  <cleartext password>,
     digestPassword: false
   }
)

The server forwards the password in plain text. In general, use only on a trusted channel (VPN, SSL, trusted wired network). See Considerations.

Configure MongoDB with Kerberos Authentication on Linux

New in version 2.4.

Overview

MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server system.

Prerequisites

Setting up and configuring a Kerberos deployment is beyond the scope of this document. This tutorial assumes you have have configured a Kerberos service principal for each mongod and mongos instance in your MongoDB deployment, and you have a valid keytab file for for each mongod and mongos instance.

To verify MongoDB Enterprise binaries:

mongod --version

In the output from this command, look for the string modules: subscription or modules: enterprise to confirm your system has MongoDB Enterprise.

Procedure

The following procedure outlines the steps to add a Kerberos user principal to MongoDB, configure a standalone mongod instance for Kerberos support, and connect using the mongo shell and authenticate the user principal.

1

Start mongod without Kerberos.

For the initial addition of Kerberos users, start mongod without Kerberos support.

If a Kerberos user is already in MongoDB and has the privileges required to create a user, you can start mongod with Kerberos support.

Step 1: Start mongod without Kerberos.

For the initial addition of Kerberos users, start mongod without Kerberos support.

If a Kerberos user is already in MongoDB and has the privileges required to create a user, you can start mongod with Kerberos support.

2

Connect to mongod.

Connect via the mongo shell to the mongod instance. If mongod has --auth enabled, ensure you connect with the privileges required to create a user.

Step 2: Connect to mongod.

Connect via the mongo shell to the mongod instance. If mongod has --auth enabled, ensure you connect with the privileges required to create a user.

3

Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM> or <username>/<instance>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in all uppercase. The $external database allows mongod to consult an external source (e.g. Kerberos) to authenticate. To specify the user’s privileges, assign roles to the user.

The following example adds the Kerberos principal application/reporting@EXAMPLE.NET with read-only access to the records database:

use $external
db.createUser(
   {
     user: "application/reporting@EXAMPLE.NET",
     roles: [ { role: "read", db: "records" } ]
   }
)

Add additional principals as needed. For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB. For more information about creating and managing users, see User Management Commands.

Step 3: Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM> or <username>/<instance>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in all uppercase. The $external database allows mongod to consult an external source (e.g. Kerberos) to authenticate. To specify the user’s privileges, assign roles to the user.

The following example adds the Kerberos principal application/reporting@EXAMPLE.NET with read-only access to the records database:

use $external
db.createUser(
   {
     user: "application/reporting@EXAMPLE.NET",
     roles: [ { role: "read", db: "records" } ]
   }
)

Add additional principals as needed. For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB. For more information about creating and managing users, see User Management Commands.

4

Start mongod with Kerberos support.

To start mongod with Kerberos support, set the environmental variable KRB5_KTNAME to the path of the keytab file and the mongod parameter authenticationMechanisms to GSSAPI in the following form:

env KRB5_KTNAME=<path to keytab file> \
mongod \
--setParameter authenticationMechanisms=GSSAPI
<additional mongod options>

For example, the following starts a standalone mongod instance with Kerberos support:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --auth \
--setParameter authenticationMechanisms=GSSAPI \
--dbpath /opt/mongodb/data

The path to your mongod as well as your keytab file may differ. Modify or include additional mongod options as required for your configuration. The keytab file must be only accessible to the owner of the mongod process.

With the official .deb or .rpm packages, you can set the KRB5_KTNAME in a environment settings file. See KRB5_KTNAME for details.

Step 4: Start mongod with Kerberos support.

To start mongod with Kerberos support, set the environmental variable KRB5_KTNAME to the path of the keytab file and the mongod parameter authenticationMechanisms to GSSAPI in the following form:

env KRB5_KTNAME=<path to keytab file> \
mongod \
--setParameter authenticationMechanisms=GSSAPI
<additional mongod options>

For example, the following starts a standalone mongod instance with Kerberos support:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --auth \
--setParameter authenticationMechanisms=GSSAPI \
--dbpath /opt/mongodb/data

The path to your mongod as well as your keytab file may differ. Modify or include additional mongod options as required for your configuration. The keytab file must be only accessible to the owner of the mongod process.

With the official .deb or .rpm packages, you can set the KRB5_KTNAME in a environment settings file. See KRB5_KTNAME for details.

5

Connect mongo shell to mongod and authenticate.

Connect the mongo shell client as the Kerberos principal application/reporting@EXAMPLE.NET. Before connecting, you must have used Kerberos’s kinit program to get credentials for application/reporting@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongo --authenticationMechanism=GSSAPI --authenticationDatabase='$external' \
--username application/reporting@EXAMPLE.NET

Or, alternatively, you can first connect mongo to the mongod, and then from the mongo shell, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "application/reporting@EXAMPLE.NET" } )

Step 5: Connect mongo shell to mongod and authenticate.

Connect the mongo shell client as the Kerberos principal application/reporting@EXAMPLE.NET. Before connecting, you must have used Kerberos’s kinit program to get credentials for application/reporting@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongo --authenticationMechanism=GSSAPI --authenticationDatabase='$external' \
--username application/reporting@EXAMPLE.NET

Or, alternatively, you can first connect mongo to the mongod, and then from the mongo shell, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "application/reporting@EXAMPLE.NET" } )

Additional Considerations

KRB5_KTNAME

If you installed MongoDB Enterprise using one of the official .deb or .rpm packages, and you use the included init/upstart scripts to control the mongod instance, you can set the KR5_KTNAME variable in the default environment settings file instead of setting the variable each time.

For .rpm packages, the default environment settings file is /etc/sysconfig/mongod.

For .deb packages, the file is /etc/default/mongodb.

Set the KRB5_KTNAME value in a line that resembles the following:

export KRB5_KTNAME="<path to keytab>"

Configure mongos for Kerberos

To start mongos with Kerberos support, set the environmental variable KRB5_KTNAME to the path of its keytab file and the mongos parameter authenticationMechanisms to GSSAPI in the following form:

env KRB5_KTNAME=<path to keytab file> \
mongos \
--setParameter authenticationMechanisms=GSSAPI \
<additional mongos options>

For example, the following starts a mongos instance with Kerberos support:

env KRB5_KTNAME=/opt/mongodb/mongos.keytab \
mongos \
--setParameter authenticationMechanisms=GSSAPI \
--configdb shard0.example.net, shard1.example.net,shard2.example.net \
--keyFile /opt/mongodb/mongos.keyfile

The path to your mongos as well as your keytab file may differ. The keytab file must be only accessible to the owner of the mongos process.

Modify or include any additional mongos options as required for your configuration. For example, instead of using --keyFile for internal authentication of sharded cluster members, you can use x.509 member authentication instead.

Use a Config File

To configure mongod or mongos for Kerberos support using a configuration file, specify the authenticationMechanisms setting in the configuration file:

setParameter=authenticationMechanisms=GSSAPI

Modify or include any additional mongod options as required for your configuration.

For example, if /opt/mongodb/mongod.conf contains the following configuration settings for a standalone mongod:

auth = true
setParameter=authenticationMechanisms=GSSAPI
dbpath=/opt/mongodb/data

To start mongod with Kerberos support, use the following form:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --config /opt/mongodb/mongod.conf

The path to your mongod, keytab file, and configuration file may differ. The keytab file must be only accessible to the owner of the mongod process.

Troubleshoot Kerberos Setup for MongoDB

If you encounter problems when starting mongod or mongos with Kerberos authentication, see Troubleshoot Kerberos Authentication on Linux.

Incorporate Additional Authentication Mechanisms

Kerberos authentication (GSSAPI) can work alongside MongoDB’s challenge/response authentication mechanism (MONGODB-CR), MongoDB’s authentication mechanism for LDAP (PLAIN), and MongoDB’s authentication mechanism for x.509 (MONGODB-X509). Specify the mechanisms, as follows:

--setParameter authenticationMechanisms=GSSAPI,MONGODB-CR

Only add the other mechanisms if in use. This parameter setting does not affect MongoDB’s internal authentication of cluster members.

Additional Resources

MongoDB LDAP and Kerberos Authentication with Dell (Quest) Authentication Services [https://www.mongodb.com/blog/post/mongodb-ldap-and-kerberos-authentication-dell-quest-authentication-services]

MongoDB with Red Hat Enterprise Linux Identity Management and Kerberos [http://docs.mongodb.org/ecosystem/tutorial/manage-red-hat-enterprise-linux-identity-management/]

Configure MongoDB with Kerberos Authentication on Windows

New in version 2.6.

Overview

MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server system. Kerberos allows MongoDB and applications to take advantage of existing authentication infrastructure and processes.

Prerequisites

Setting up and configuring a Kerberos deployment is beyond the scope of this document. This tutorial assumes have configured a Kerberos service principal for each mongod.exe and mongos.exe instance.

Procedures

1

Start mongod.exe without Kerberos.

For the initial addition of Kerberos users, start mongod.exe without Kerberos support.

If a Kerberos user is already in MongoDB and has the privileges required to create a user, you can start mongod.exe with Kerberos support.

Step 1: Start mongod.exe without Kerberos.

For the initial addition of Kerberos users, start mongod.exe without Kerberos support.

If a Kerberos user is already in MongoDB and has the privileges required to create a user, you can start mongod.exe with Kerberos support.

2

Connect to mongod.

Connect via the mongo.exe shell to the mongod.exe instance. If mongod.exe has --auth enabled, ensure you connect with the privileges required to create a user.

Step 2: Connect to mongod.

Connect via the mongo.exe shell to the mongod.exe instance. If mongod.exe has --auth enabled, ensure you connect with the privileges required to create a user.

3

Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in all uppercase. The $external database allows mongod.exe to consult an external source (e.g. Kerberos) to authenticate. To specify the user’s privileges, assign roles to the user.

The following example adds the Kerberos principal reportingapp@EXAMPLE.NET with read-only access to the records database:

use $external
db.createUser(
   {
     user: "reportingapp@EXAMPLE.NET",
     roles: [ { role: "read", db: "records" } ]
   }
)

Add additional principals as needed. For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB. For more information about creating and managing users, see User Management Commands.

Step 3: Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in all uppercase. The $external database allows mongod.exe to consult an external source (e.g. Kerberos) to authenticate. To specify the user’s privileges, assign roles to the user.

The following example adds the Kerberos principal reportingapp@EXAMPLE.NET with read-only access to the records database:

use $external
db.createUser(
   {
     user: "reportingapp@EXAMPLE.NET",
     roles: [ { role: "read", db: "records" } ]
   }
)

Add additional principals as needed. For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB. For more information about creating and managing users, see User Management Commands.

4

Start mongod.exe with Kerberos support.

You must start mongod.exe as the service principal account.

To start mongod.exe with Kerberos support, set the mongod.exe parameter authenticationMechanisms to GSSAPI:

mongod.exe --setParameter authenticationMechanisms=GSSAPI <additional mongod.exe options>

For example, the following starts a standalone mongod.exe instance with Kerberos support:

mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI

Modify or include additional mongod.exe options as required for your configuration.

Step 4: Start mongod.exe with Kerberos support.

You must start mongod.exe as the service principal account.

To start mongod.exe with Kerberos support, set the mongod.exe parameter authenticationMechanisms to GSSAPI:

mongod.exe --setParameter authenticationMechanisms=GSSAPI <additional mongod.exe options>

For example, the following starts a standalone mongod.exe instance with Kerberos support:

mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI

Modify or include additional mongod.exe options as required for your configuration.

5

Connect mongo.exe shell to mongod.exe and authenticate.

Connect the mongo.exe shell client as the Kerberos principal application@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongo.exe --authenticationMechanism=GSSAPI --authenticationDatabase='$external' \
--username reportingapp@EXAMPLE.NET

Or, alternatively, you can first connect mongo.exe to the mongod.exe, and then from the mongo.exe shell, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "reportingapp@EXAMPLE.NET" } )

Step 5: Connect mongo.exe shell to mongod.exe and authenticate.

Connect the mongo.exe shell client as the Kerberos principal application@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongo.exe --authenticationMechanism=GSSAPI --authenticationDatabase='$external' \
--username reportingapp@EXAMPLE.NET

Or, alternatively, you can first connect mongo.exe to the mongod.exe, and then from the mongo.exe shell, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "reportingapp@EXAMPLE.NET" } )

Additional Considerations

Configure mongos.exe for Kerberos

To start mongos.exe with Kerberos support, set the mongos.exe parameter authenticationMechanisms to GSSAPI. You must start mongos.exe as the service principal account.:

mongos.exe --setParameter authenticationMechanisms=GSSAPI <additional mongos options>

For example, the following starts a mongos instance with Kerberos support:

mongos.exe --setParameter authenticationMechanisms=GSSAPI --configdb shard0.example.net, shard1.example.net,shard2.example.net --keyFile C:\<path>\mongos.keyfile

Modify or include any additional mongos.exe options as required for your configuration. For example, instead of using --keyFile for for internal authentication of sharded cluster members, you can use x.509 member authentication instead.

Assign Service Principal Name to MongoDB Windows Service

Use setspn.exe to assign the service principal name (SPN) to the account running the mongod.exe and the mongos.exe service:

setspn.exe -A <service>/<fully qualified domain name> <service account name>

For example, if mongod.exe runs as a service named mongodb on testserver.mongodb.com with the service account name mongodtest, assign the SPN as follows:

setspn.exe -A mongodb/testserver.mongodb.com mongodtest

Incorporate Additional Authentication Mechanisms

Kerberos authentication (GSSAPI) can work alongside MongoDB’s challenge/response authentication mechanism (MONGODB-CR), MongoDB’s authentication mechanism for LDAP (PLAIN), and MongoDB’s authentication mechanism for x.509 (MONGODB-X509). Specify the mechanisms, as follows:

--setParameter authenticationMechanisms=GSSAPI,MONGODB-CR

Only add the other mechanisms if in use. This parameter setting does not affect MongoDB’s internal authentication of cluster members.

Authenticate to a MongoDB Instance or Cluster

Overview

To authenticate to a running mongod or mongos instance, you must have user credentials for a resource on that instance. When you authenticate to MongoDB, you authenticate either to a database or to a cluster. Your user privileges determine the resource you can authenticate to.

You authenticate to a resource either by:

using the authentication options when connecting to the mongod or mongos instance, or

connecting first and then authenticating to the resource with the authenticate command or the db.auth() method.

This section describes both approaches.

In general, always use a trusted channel (VPN, SSL, trusted wired network) for connecting to a MongoDB instance.

Prerequisites

You must have user credentials on the database or cluster to which you are authenticating.

Procedures

Authenticate When First Connecting to MongoDB

1

Specify your credentials when starting the mongo instance.

When using mongo to connect to a mongod or mongos, enter your username, password, and authenticationDatabase. For example:

mongo --username "prodManager" --password "cleartextPassword" --authenticationDatabase "products"

Step 1: Specify your credentials when starting the mongo instance.

When using mongo to connect to a mongod or mongos, enter your username, password, and authenticationDatabase. For example:

mongo --username "prodManager" --password "cleartextPassword" --authenticationDatabase "products"

2

Close the session when your work is complete.

To close an authenticated session, use the logout command.:

db.runCommand( { logout: 1 } )

Step 2: Close the session when your work is complete.

To close an authenticated session, use the logout command.:

db.runCommand( { logout: 1 } )

Authenticate After Connecting to MongoDB

1

Connect to a MongoDB instance.

Connect to a mongod or mongos instance.

Step 1: Connect to a MongoDB instance.

Connect to a mongod or mongos instance.

2

Switch to the database to which to authenticate.

use <database>

Step 2: Switch to the database to which to authenticate.

use <database>

3

Authenticate.

Use either the authenticate command or the db.auth() method to provide your username and password to the database. For example:

db.auth( "prodManager", "cleartextPassword" )

Step 3: Authenticate.

Use either the authenticate command or the db.auth() method to provide your username and password to the database. For example:

db.auth( "prodManager", "cleartextPassword" )

4

Close the session when your work is complete.

To close an authenticated session, use the logout command.:

db.runCommand( { logout: 1 } )

Step 4: Close the session when your work is complete.

To close an authenticated session, use the logout command.:

db.runCommand( { logout: 1 } )

Generate a Key File

Overview

This section describes how to generate a key file to store authentication information. After generating a key file, specify the key file using the keyFile option when starting a mongod or mongos instance.

A key’s length must be between 6 and 1024 characters and may only contain characters in the base64 set. The key file must not have group or world permissions on UNIX systems. Key file permissions are not checked on Windows systems.

MongoDB strips whitespace characters (e.g. x0d, x09, and x20) for cross-platform convenience. As a result, the following operations produce identical keys:

echo -e "my secret key" > key1
echo -e "my secret key\n" > key2
echo -e "my    secret    key" > key3
echo -e "my\r\nsecret\r\nkey\r\n" > key4

Procedure

1

Create a key file.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

Step 1: Create a key file.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

2

Specify the key file when starting a MongoDB instance.

Specify the path to the key file with the keyFile option.

Step 2: Specify the key file when starting a MongoDB instance.

Specify the path to the key file with the keyFile option.

Troubleshoot Kerberos Authentication on Linux

New in version 2.4.

Kerberos Configuration Checklist

If you have difficulty starting mongod or mongos with Kerberos on Linux systems, ensure that:

The mongod and the mongos binaries are from MongoDB Enterprise.

To verify MongoDB Enterprise binaries:

mongod --version

In the output from this command, look for the string modules: subscription or modules: enterprise to confirm your system has MongoDB Enterprise.

You are not using the HTTP Console [http://docs.mongodb.org/ecosystem/tools/http-interface/#http-console]. MongoDB Enterprise does not support Kerberos authentication over the HTTP Console interface.

Either the service principal name (SPN) in the keytab file matches the SPN for the mongod or mongos instance, or the mongod or the mongos instance use the --setParameter saslHostName=<host name> to match the name in the keytab file.

The canonical system hostname of the system that runs the mongod or mongos instance is a resolvable, fully qualified domain for this host. You can test the system hostname resolution with the hostname -f command at the system prompt.

Each host that runs a mongod or mongos instance has both the A and PTR DNS records to provide forward and reverse lookup. The records allow the host to resolve the components of the Kerberos infrastructure.

Both the Kerberos Key Distribution Center (KDC) and the system running mongod instance or mongos must be able to resolve each other using DNS. By default, Kerberos attempts to resolve hosts using the content of the /etc/kerb5.conf before using DNS to resolve hosts.

The time synchronization of the systems running mongod or the mongos instances and the Kerberos infrastructure are within the maximum time skew (default is 5 minutes) of each other. Time differences greater than the maximum time skew will prevent successful authentication.

Debug with More Verbose Logs

If you still encounter problems with Kerberos on Linux, you can start both mongod and mongo (or another client) with the environment variable KRB5_TRACE set to different files to produce more verbose logging of the Kerberos process to help further troubleshooting. For example, the following starts a standalone mongod with KRB5_TRACE set:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
    KRB5_TRACE=/opt/mongodb/log/mongodb-kerberos.log \
    /opt/mongodb/bin/mongod --dbpath /opt/mongodb/data \
    --fork --logpath /opt/mongodb/log/mongod.log \
    --auth --setParameter authenticationMechanisms=GSSAPI

Common Error Messages

In some situations, MongoDB will return error messages from the GSSAPI interface if there is a problem with the Kerberos service. Some common error messages are:

GSSAPI error in client while negotiating security context.

This error occurs on the client and reflects insufficient credentials or a malicious attempt to authenticate.

If you receive this error, ensure that you are using the correct credentials and the correct fully qualified domain name when connecting to the host.

GSSAPI error acquiring credentials.

This error occurs during the start of the mongod or mongos and reflects improper configuration of the system hostname or a missing or incorrectly configured keytab file.

If you encounter this problem, consider the items in the Kerberos Configuration Checklist, in particular, whether the SPN in the keytab file matches the SPN for the mongod or mongos instance.

To determine whether the SPNs match:

Examine the keytab file, with the following command:

klist -k <keytab>

Replace <keytab> with the path to your keytab file.

Check the configured hostname for your system, with the following command:

hostname -f

Ensure that this name matches the name in the keytab file, or start mongod or mongos with the --setParameter saslHostName=<hostname>.

See also

Kerberos Authentication

Configure MongoDB with Kerberos Authentication on Linux

Configure MongoDB with Kerberos Authentication on Windows

Implement Field Level Redaction

The $redact pipeline operator restricts the contents of the documents based on information stored in the documents themselves.

To store the access criteria data, add a field to the documents and embedded documents. To allow for multiple combinations of access levels for the same data, consider setting the access field to an array of arrays. Each array element contains a required set that allows a user with that set to access the data.

Then, include the $redact stage in the db.collection.aggregate() operation to restrict contents of the result set based on the access required to view the data.

For more information on the $redact pipeline operator, including its syntax and associated system variables as well as additional examples, see $redact.

Procedure

For example, a forecasts collection contains documents of the following form where the tags field determines the access levels required to view the data:

{
   _id: 1,
   title: "123 Department Report",
   tags: [ [ "G" ], [ "FDW" ] ],
   year: 2014,
   subsections: [
       {
           subtitle: "Section 1: Overview",
           tags: [ [ "SI", "G" ], [ "FDW" ] ],
           content:  "Section 1: This is the content of section 1."
       },
       {
           subtitle: "Section 2: Analysis",
           tags: [ [ "STLW" ] ],
           content: "Section 2: This is the content of section 2."
       },
       {
           subtitle: "Section 3: Budgeting",
           tags: [ [ "TK" ], [ "FDW", "TGE" ] ],
           content: {
               text: "Section 3: This is the content of section3.",
               tags: [ [ "HCS"], [ "FDW", "TGE", "BX" ] ]
           }
       }
   ]
}

For each document, the tags field contains various access groupings necessary to view the data. For example, the value [ [ "G" ], [ "FDW", "TGE" ] ] can specify that a user requires either access level ["G"] or both [ "FDW", "TGE" ] to view the data.

Consider a user who only has access to view information tagged with either "FDW" or "TGE". To run a query on all documents with year 2014 for this user, include a $redact stage as in the following:

var userAccess = [ "FDW", "TGE" ];
db.forecasts.aggregate(
   [
     { $match: { year: 2014 } },
     { $redact:
         {
           $cond: {
                    if: { $anyElementTrue:
                           {
                             $map: {
                                     input: "$tags" ,
                                     as: "fieldTag",
                                     in: { $setIsSubset: [ "$$fieldTag", userAccess ] }
                                   }
                           }
                        },
                     then: "$$DESCEND",
                     else: "$$PRUNE"
                  }
         }
     }
   ]
)

The aggregation operation returns the following “redacted” document for the user:

{ "_id" : 1,
  "title" : "123 Department Report",
  "tags" : [ [ "G" ], [ "FDW" ] ],
  "year" : 2014,
  "subsections" :
     [
        {
          "subtitle" : "Section 1: Overview",
          "tags" : [ [ "SI", "G" ], [ "FDW" ] ],
          "content" : "Section 1: This is the content of section 1."
        },
       {
         "subtitle" : "Section 3: Budgeting",
         "tags" : [ [ "TK" ], [ "FDW", "TGE" ] ]
       }
     ]
}

See also

$map, $setIsSubset, $anyElementTrue

User and Role Management Tutorials

The following tutorials provide instructions on how to enable authentication and limit access for users with privilege roles.

Create a User Administrator

Create users with special permissions to to create, modify, and remove other users, as well as administer authentication credentials (e.g. passwords).

Add a User to a Database

Create non-administrator users using MongoDB’s role-based authentication system.

Create an Administrative User with Unrestricted Access

Create a user with unrestricted access. Create such a user only in unique situations. In general, all users in the system should have no more access than needed to perform their required operations.

Create a Role

Create custom role.

Assign a User a Role

Assign a user a role. A role grants the user a defined set of privileges. A user can have multiple roles.

Verify User Privileges

View a user’s current privileges.

Modify a User’s Access

Modify the actions available to a user on specific database resources.

View Roles

View a role’s privileges.

Change a User’s Password

Only user administrators can edit credentials. This tutorial describes the process for editing an existing user’s password.

Change Your Password and Custom Data

Users with sufficient access can change their own passwords and modify the optional custom data associated with their user credential.

Create a User Administrator

Add a User to a Database

Create an Administrative User with Unrestricted Access

Create a Role

Assign a User a Role

Verify User Privileges

Modify a User’s Access

View Roles

Change a User’s Password

Change Your Password and Custom Data

Create a User Administrator

Overview

User administrators create users and create and assigns roles. A user administrator can grant any privilege in the database and can create new ones. In a MongoDB deployment, create the user administrator as the first user. Then let this user create all other users.

To provide user administrators, MongoDB has userAdmin and userAdminAnyDatabase roles, which grant access to actions that support user and role management. Following the policy of least privilege userAdmin and userAdminAnyDatabase confer no additional privileges.

Carefully control access to these roles. A user with either of these roles can grant itself unlimited additional privileges. Specifically, a user with the userAdmin role can grant itself any privilege in the database. A user assigned either the userAdmin role on the admin database or the userAdminAnyDatabase can grant itself any privilege in the system.

Prerequisites

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

First User Restrictions

If your MongoDB deployment has no users, you must connect to mongod using the localhost exception or use the --noauth option when starting mongod to gain full access the system. Once you have access, you can skip to Creating the system user administrator in this procedure.

If users exist in the MongoDB database, but none of them has the appropriate prerequisites to create a new user or you do not have access to them, you must restart mongod with the --noauth option.

Procedure

1

Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos either through the localhost exception or as a user with the privileges indicated in the prerequisites section.

In the following example, manager has the required privileges specified in Prerequisites.

mongo --port 27017 -u manager -p 123456 --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos either through the localhost exception or as a user with the privileges indicated in the prerequisites section.

In the following example, manager has the required privileges specified in Prerequisites.

mongo --port 27017 -u manager -p 123456 --authenticationDatabase admin

2

Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

Step 2: Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user siteUserAdmin user on the admin database:

use admin
db.createUser(
  {
    user: "siteUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

3

Create a user administrator for a single database.

Optionally, you may want to create user administrators that only have access to administer users in a specific database by way of the userAdmin role.

The following example creates the user recordsUserAdmin on the records database:

use records
db.createUser(
  {
    user: "recordsUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdmin", db: "records" } ]
  }
)

Step 3: Create a user administrator for a single database.

Optionally, you may want to create user administrators that only have access to administer users in a specific database by way of the userAdmin role.

The following example creates the user recordsUserAdmin on the records database:

use records
db.createUser(
  {
    user: "recordsUserAdmin",
    pwd: "password",
    roles: [ { role: "userAdmin", db: "records" } ]
  }
)

Related Documents

Authentication

Security Introduction

Enable Client Access Control

Access Control Tutorials

Additional Resources

Security Architecture White Paper [https://www.mongodb.com/lp/white-paper/mongodb-security-architecture]

Webinar: Securing Your MongoDB Deployment [http://www.mongodb.com/webinar/securing-your-mongodb-deployment]

Creating a Single View Part 3: Securing Your Deployment [https://www.mongodb.com/presentations/creating-single-view-part-3-securing-your-deployment]

Add a User to a Database

Changed in version 2.6.

Overview

Each application and user of a MongoDB system should map to a distinct application or administrator. This access isolation facilitates access revocation and ongoing user maintenance. At the same time users should have only the minimal set of privileges required to ensure a system of least privilege.

To create a user, you must define the user’s credentials and assign that user roles. Credentials verify the user’s identity to a database, and roles determine the user’s access to database resources and operations.

For an overview of credentials and roles in MongoDB see Security Introduction.

Considerations

For users that authenticate using external mechanisms, [1] you do not need to provide credentials when creating users.

For all users, select the roles that have the exact required privileges. If the correct roles do not exist, create roles.

You can create a user without assigning roles, choosing instead to assign the roles later. To do so, create the user with an empty roles array.

[1]
Configure MongoDB with Kerberos Authentication on Linux, Authenticate Using SASL and LDAP with OpenLDAP, Authenticate Using SASL and LDAP with ActiveDirectory, and x.509 certificates provide external authentication mechanisms.

Prerequisites

To create a user on a system that uses authentication, you must authenticate as a user administrator. If you have not yet created a user administrator, do so as described in Create a User Administrator.

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

First User Restrictions

If your MongoDB deployment has no users, you must connect to mongod using the localhost exception or use the --noauth option when starting mongod to gain full access the system. Once you have access, you can skip to Creating the system user administrator in this procedure.

If users exist in the MongoDB database, but none of them has the appropriate prerequisites to create a new user or you do not have access to them, you must restart mongod with the --noauth option.

Procedures

1

Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Create the new user.

Create the user in the database to which the user will belong. Pass a well formed user document to the db.createUser() method.

The following operation creates a user in the reporting database with the specified name, password, and roles.

use reporting
db.createUser(
    {
      user: "reportsUser",
      pwd: "12345678",
      roles: [
         { role: "read", db: "reporting" },
         { role: "read", db: "products" },
         { role: "read", db: "sales" },
         { role: "readWrite", db: "accounts" }
      ]
    }
)

To authenticate the reportsUser, you must authenticate the user in the reporting database.

Step 2: Create the new user.

Create the user in the database to which the user will belong. Pass a well formed user document to the db.createUser() method.

The following operation creates a user in the reporting database with the specified name, password, and roles.

use reporting
db.createUser(
    {
      user: "reportsUser",
      pwd: "12345678",
      roles: [
         { role: "read", db: "reporting" },
         { role: "read", db: "products" },
         { role: "read", db: "sales" },
         { role: "readWrite", db: "accounts" }
      ]
    }
)

To authenticate the reportsUser, you must authenticate the user in the reporting database.

Create an Administrative User with Unrestricted Access

Overview

Most users should have only the minimal set of privileges required for their operations, in keeping with the policy of least privilege. However, some authorization architectures may require a user with unrestricted access. To support these super users, you can create users with access to all database resources and actions.

For many deployments, you may be able to avoid having any users with unrestricted access by having an administrative user with the createUser and grantRole actions granted as needed to support operations.

If users truly need unrestricted access to a MongoDB deployment, MongoDB provides a built-in role named root that grants the combined privileges of all built-in roles. This document describes how to create an administrative user with the root role.

For descriptions of the access each built-in role provides, see the section on built-in roles.

Prerequisites

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

First User Restrictions

If your MongoDB deployment has no users, you must connect to mongod using the localhost exception or use the --noauth option when starting mongod to gain full access the system. Once you have access, you can skip to Creating the system user administrator in this procedure.

If users exist in the MongoDB database, but none of them has the appropriate prerequisites to create a new user or you do not have access to them, you must restart mongod with the --noauth option.

Procedure

1

Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos as a user with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos as a user with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Create the administrative user.

In the admin database, create a new user using the db.createUser() method. Give the user the built-in root role.

For example:

use admin
db.createUser(
    {
      user: "superuser",
      pwd: "12345678",
      roles: [ "root" ]
    }
)

Authenticate against the admin database to test the new user account. Use db.auth() while using the admin database or use the mongo shell with the --authenticationDatabase option.

Step 2: Create the administrative user.

In the admin database, create a new user using the db.createUser() method. Give the user the built-in root role.

For example:

use admin
db.createUser(
    {
      user: "superuser",
      pwd: "12345678",
      roles: [ "root" ]
    }
)

Authenticate against the admin database to test the new user account. Use db.auth() while using the admin database or use the mongo shell with the --authenticationDatabase option.

Create a Role

Overview

Roles grant users access to MongoDB resources. By default, MongoDB provides a number of built-in roles that administrators may use to control access to a MongoDB system. However, if these roles cannot describe the desired set of privileges, you can create a new, customized role in a particular database.

Except for roles created in the admin database, a role can only include privileges that apply to its database and can only inherit from other roles in its database.

A role created in the admin database can include privileges that apply to the admin database, other databases or to the cluster resource, and can inherit from roles in other databases as well as the admin database.

MongoDB uses the combination of the database name and the role name to uniquely define a role.

Prerequisites

To create a role in a database, the user must have:

the createRole action on that database resource.

the grantRole action on that database to specify privileges for the new role as well as to specify roles to inherit from.

Built-in roles userAdmin and userAdminAnyDatabase provide createRole and grantRole actions on their respective resources.

Procedures

To create a new role, use the db.createRole() method, specifying the privileges in the privileges array and the inherited roles in the roles array.

Create a Role to Manage Current Operations

The following example creates a role named manageOpRole which provides only the privileges to run both db.currentOp() and db.killOp(). [1]

1

Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

The siteUserAdmin has privileges to create roles in the admin as well as other databases.

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

The siteUserAdmin has privileges to create roles in the admin as well as other databases.

2

Create a new role to manage current operations.

manageOpRole has privileges that act on multiple databases as well as the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "manageOpRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "killop", "inprog" ] },
       { resource: { db: "", collection: "" }, actions: [ "killCursors" ] }
     ],
     roles: []
   }
)

The new role grants permissions to kill any operations.

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

Step 2: Create a new role to manage current operations.

manageOpRole has privileges that act on multiple databases as well as the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "manageOpRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "killop", "inprog" ] },
       { resource: { db: "", collection: "" }, actions: [ "killCursors" ] }
     ],
     roles: []
   }
)

The new role grants permissions to kill any operations.

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

[1]
The built-in role clusterMonitor also provides the privilege to run db.currentOp() along with other privileges, and the built-in role hostManager provides the privilege to run db.killOp() along with other privileges.

Create a Role to Run mongostat

The following example creates a role named mongostatRole that provides only the privileges to run mongostat. [2]

1

Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

The siteUserAdmin has privileges to create roles in the admin as well as other databases.

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

The siteUserAdmin has privileges to create roles in the admin as well as other databases.

2

Create a new role to manage current operations.

mongostatRole has privileges that act on the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "mongostatRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "serverStatus" ] }
     ],
     roles: []
   }
)

Step 2: Create a new role to manage current operations.

mongostatRole has privileges that act on the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "mongostatRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "serverStatus" ] }
     ],
     roles: []
   }
)

[2]
The built-in role clusterMonitor also provides the privilege to run mongostat along with other privileges.

Assign a User a Role

Changed in version 2.6.

Overview

A role provides a user privileges to perform a set of actions on a resource. A user can have multiple roles.

In MongoDB systems with authorization enforced, you must grant a user a role for the user to access a database resource. To assign a role, first determine the privileges the user needs and then determine the role that grants those privileges.

For an overview of roles and privileges, see Authorization. For descriptions of the access each built-in role provides, see the section on built-in roles.

Prerequisites

You must have the grantRole action on a database to grant a role on that database.

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Procedure

1

Connect with the privilege to grant roles.

Connect to the mongod or mongos as a user with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect with the privilege to grant roles.

Connect to the mongod or mongos as a user with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Identify the user’s roles and privileges.

To display the roles and privileges of the user to be modified, use the db.getUser() and db.getRole() methods.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

To display the privileges granted to the user by the readWrite role on the "accounts" database, issue:

use accounts
db.getRole( "readWrite", { showPrivileges: true } )

Step 2: Identify the user’s roles and privileges.

To display the roles and privileges of the user to be modified, use the db.getUser() and db.getRole() methods.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

To display the privileges granted to the user by the readWrite role on the "accounts" database, issue:

use accounts
db.getRole( "readWrite", { showPrivileges: true } )

3

Identify the privileges to grant or revoke.

If the user requires additional privileges, grant to the user the role, or roles, with the required set of privileges. If such a role does not exist, create a new role with the appropriate set of privileges.

Step 3: Identify the privileges to grant or revoke.

If the user requires additional privileges, grant to the user the role, or roles, with the required set of privileges. If such a role does not exist, create a new role with the appropriate set of privileges.

4

Grant a role to a user.

Grant the user the role using the db.grantRolesToUser() method.

For example, the following grants new roles to the user reportsUser created in Add a User to a Database.

use reporting
db.grantRolesToUser(
  "reportsUser",
  [
    { role: "readWrite", db: "products" } ,
    { role: "readAnyDatabase", db:"admin" }
  ]
)

Step 4: Grant a role to a user.

Grant the user the role using the db.grantRolesToUser() method.

For example, the following grants new roles to the user reportsUser created in Add a User to a Database.

use reporting
db.grantRolesToUser(
  "reportsUser",
  [
    { role: "readWrite", db: "products" } ,
    { role: "readAnyDatabase", db:"admin" }
  ]
)

Verify User Privileges

Overview

A user’s privileges determine the access the user has to MongoDB resources and the actions that user can perform. Users receive privileges through role assignments. A user can have multiple roles, and each role can have multiple privileges.

For an overview of roles and privileges, see Authorization.

Prerequisites

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Procedure

1

Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Identify the user’s roles.

Use the usersInfo command or db.getUser() method to display user information.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

In the returned document, the roles field displays all roles for reportsUser:

...
"roles" : [
   { "role" : "readWrite", "db" : "accounts" },
   { "role" : "read", "db" : "reporting" },
   { "role" : "read", "db" : "products" },
   { "role" : "read", "db" : "sales" }
]

Step 2: Identify the user’s roles.

Use the usersInfo command or db.getUser() method to display user information.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

In the returned document, the roles field displays all roles for reportsUser:

...
"roles" : [
   { "role" : "readWrite", "db" : "accounts" },
   { "role" : "read", "db" : "reporting" },
   { "role" : "read", "db" : "products" },
   { "role" : "read", "db" : "sales" }
]

3

Identify the privileges granted by the roles.

For a given role, use the db.getRole() method, or the rolesInfo command, with the showPrivileges option:

For example, to view the privileges granted by read role on the products database, use the following operation, issue:

use products
db.getRole( "read", { showPrivileges: true } )

In the returned document, the privileges and inheritedPrivileges arrays. The privileges lists the privileges directly specified by the role and excludes those privileges inherited from other roles. The inheritedPrivileges lists all privileges granted by this role, both directly specified and inherited. If the role does not inherit from other roles, the two fields are the same.

...
"privileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.indexes" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.namespaces" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
],
"inheritedPrivileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.indexes" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.namespaces" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
]

Step 3: Identify the privileges granted by the roles.

For a given role, use the db.getRole() method, or the rolesInfo command, with the showPrivileges option:

For example, to view the privileges granted by read role on the products database, use the following operation, issue:

use products
db.getRole( "read", { showPrivileges: true } )

In the returned document, the privileges and inheritedPrivileges arrays. The privileges lists the privileges directly specified by the role and excludes those privileges inherited from other roles. The inheritedPrivileges lists all privileges granted by this role, both directly specified and inherited. If the role does not inherit from other roles, the two fields are the same.

...
"privileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.indexes" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.namespaces" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
],
"inheritedPrivileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.indexes" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.namespaces" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
]

Modify a User’s Access

Overview

When a user’s responsibilities change, modify the user’s access to include only those roles the user requires. This follows the policy of least privilege.

To change a user’s access, first determine the privileges the user needs and then determine the roles that grants those privileges. Grant and revoke roles using the db.grantRolesToUser() and db.revokeRolesFromUser() methods.

For an overview of roles and privileges, see Authorization. For descriptions of the access each built-in role provides, see the section on built-in roles.

Prerequisites

You must have the grantRole action on a database to grant a role on that database.

You must have the revokeRole action on a database to revoke a role on that database.

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Procedure

1

Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Identify the user’s roles and privileges.

To display the roles and privileges of the user to be modified, use the db.getUser() and db.getRole() methods.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

To display the privileges granted to the user by the readWrite role on the "accounts" database, issue:

use accounts
db.getRole( "readWrite", { showPrivileges: true } )

Step 2: Identify the user’s roles and privileges.

To display the roles and privileges of the user to be modified, use the db.getUser() and db.getRole() methods.

For example, to view roles for reportsUser created in Add a User to a Database, issue:

use reporting
db.getUser("reportsUser")

To display the privileges granted to the user by the readWrite role on the "accounts" database, issue:

use accounts
db.getRole( "readWrite", { showPrivileges: true } )

3

Identify the privileges to grant or revoke.

If the user requires additional privileges, grant to the user the role, or roles, with the required set of privileges. If such a role does not exist, create a new role with the appropriate set of privileges.

To revoke a subset of privileges provided by an existing role: revoke the original role and grant a role that contains only the required privileges. You may need to create a new role if a role does not exist.

Step 3: Identify the privileges to grant or revoke.

If the user requires additional privileges, grant to the user the role, or roles, with the required set of privileges. If such a role does not exist, create a new role with the appropriate set of privileges.

To revoke a subset of privileges provided by an existing role: revoke the original role and grant a role that contains only the required privileges. You may need to create a new role if a role does not exist.

4

Modify the user’s access.

Revoke a Role

Revoke a role with the db.revokeRolesFromUser() method. The following example operation removes the readWrite role on the accounts database from the reportsUser:

use reporting
db.revokeRolesFromUser(
    "reportsUser",
    [
      { role: "readWrite", db: "accounts" }
    ]
)

Grant a Role

Grant a role using the db.grantRolesToUser() method. For example, the following operation grants the reportsUser user the read role on the accounts database:

use reporting
db.grantRolesToUser(
    "reportsUser",
    [
      { role: "read", db: "accounts" }
    ]
)

For sharded clusters, the changes to the user are instant on the mongos on which the command runs. However, for other mongos instances in the cluster, the user cache may wait up to 10 minutes to refresh. See userCacheInvalidationIntervalSecs.

Step 4: Modify the user’s access.

Revoke a Role

Revoke a role with the db.revokeRolesFromUser() method. The following example operation removes the readWrite role on the accounts database from the reportsUser:

use reporting
db.revokeRolesFromUser(
    "reportsUser",
    [
      { role: "readWrite", db: "accounts" }
    ]
)

Grant a Role

Grant a role using the db.grantRolesToUser() method. For example, the following operation grants the reportsUser user the read role on the accounts database:

use reporting
db.grantRolesToUser(
    "reportsUser",
    [
      { role: "read", db: "accounts" }
    ]
)

For sharded clusters, the changes to the user are instant on the mongos on which the command runs. However, for other mongos instances in the cluster, the user cache may wait up to 10 minutes to refresh. See userCacheInvalidationIntervalSecs.

View Roles

Overview

A role grants privileges to the users who are assigned the role. Each role is scoped to a particular database, but MongoDB stores all role information in the admin.system.roles collection in the admin database.

Prerequisites

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Procedures

The following procedures use the rolesInfo command. You also can use the methods db.getRole() (singular) and db.getRoles().

View a Role in the Current Database

If the role is in the current database, you can refer to the role by name, as for the role dataEntry on the current database:

db.runCommand({ rolesInfo: "dataEntry" })

View a Role in a Different Database

If the role is in a different database, specify the role as a document. Use the following form:

{ role: "<role name>", db: "<role db>" }

To view the custom appWriter role in the orders database, issue the following command from the mongo shell:

db.runCommand({ rolesInfo: { role: "appWriter", db: "orders" } })

View Multiple Roles

To view information for multiple roles, specify each role as a document or string in an array.

To view the custom appWriter and clientWriter roles in the orders database, as well as the dataEntry role on the current database, use the following command from the mongo shell:

db.runCommand( { rolesInfo: [ { role: "appWriter", db: "orders" },
                              { role: "clientWriter", db: "orders" },
                              "dataEntry" ]
               } )

View All Custom Roles

To view the all custom roles, query admin.system.roles collection directly, for example:

db = db.getSiblingDB('admin')
db.system.roles.find()

Change a User’s Password

Changed in version 2.6.

Overview

Strong passwords help prevent unauthorized access, and all users should have strong passwords. You can use the openssl program to generate unique strings for use in passwords, as in the following command:

openssl rand -base64 48

Prerequisites

You must have the changeAnyPassword action on a database to modify the password of any user on that database.

To change your own password, you must have the changeOwnPassword action on your database. See Change Your Password and Custom Data.

Procedure

1

Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Change the password.

Pass the user’s username and the new password to the db.changeUserPassword() method.

The following operation changes the reporting user’s password to SOh3TbYhxuLiW8ypJPxmt1oOfL:

db.changeUserPassword("reporting", "SOh3TbYhxuLiW8ypJPxmt1oOfL")

Step 2: Change the password.

Pass the user’s username and the new password to the db.changeUserPassword() method.

The following operation changes the reporting user’s password to SOh3TbYhxuLiW8ypJPxmt1oOfL:

db.changeUserPassword("reporting", "SOh3TbYhxuLiW8ypJPxmt1oOfL")

Change Your Password and Custom Data

Changed in version 2.6.

Overview

Users with appropriate privileges can change their own passwords and custom data. Custom data stores optional user information.

Considerations

To generate a strong password for use in this procedure, you can use the openssl utility’s rand command. For example, issue openssl rand with the following options to create a base64-encoded string of 48 pseudo-random bytes:

openssl rand -base64 48

Prerequisites

To modify your own password and custom data, you must have privileges that grant changeOwnPassword and changeOwnCustomData actions respectively on the user’s database.

1

Connect as a user with privileges to manage users and roles.

Connect to the mongod or mongos with privileges to manage users and roles, such as a user with userAdminAnyDatabase role. The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Step 1: Connect as a user with privileges to manage users and roles.

Connect to the mongod or mongos with privileges to manage users and roles, such as a user with userAdminAnyDatabase role. The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

2

Create a role with appropriate privileges.

In the admin database, create a new role with changeOwnPassword and changeOwnCustomData.

use admin
db.createRole(
   { role: "changeOwnPasswordCustomDataRole",
     privileges: [
        {
          resource: { db: "", collection: ""},
          actions: [ "changeOwnPassword", "changeOwnCustomData" ]
        }
     ],
     roles: []
   }
)

Step 2: Create a role with appropriate privileges.

In the admin database, create a new role with changeOwnPassword and changeOwnCustomData.

use admin
db.createRole(
   { role: "changeOwnPasswordCustomDataRole",
     privileges: [
        {
          resource: { db: "", collection: ""},
          actions: [ "changeOwnPassword", "changeOwnCustomData" ]
        }
     ],
     roles: []
   }
)

3

Add a user with this role.

In the test database, create a new user with the created "changeOwnPasswordCustomDataRole" role. For example, the following operation creates a user with both the built-in role readWrite and the user-created "changeOwnPasswordCustomDataRole".

use test
db.createUser(
   {
     user:"user123",
     pwd:"12345678",
     roles:[ "readWrite", { role:"changeOwnPasswordCustomDataRole", db:"admin" } ]
   }
)

To grant an existing user the new role, use db.grantRolesToUser().

Step 3: Add a user with this role.

In the test database, create a new user with the created "changeOwnPasswordCustomDataRole" role. For example, the following operation creates a user with both the built-in role readWrite and the user-created "changeOwnPasswordCustomDataRole".

use test
db.createUser(
   {
     user:"user123",
     pwd:"12345678",
     roles:[ "readWrite", { role:"changeOwnPasswordCustomDataRole", db:"admin" } ]
   }
)

To grant an existing user the new role, use db.grantRolesToUser().

Procedure

1

Connect with the appropriate privileges.

Connect to the mongod or mongos as a user with appropriate privileges.

For example, the following operation connects to MongoDB as user123 created in the Prerequisites section.

mongo --port 27017 -u user123 -p 12345678 --authenticationDatabase test

To check that you have the privileges specified in the Prerequisites section as well as to see user information, use the usersInfo command with the showPrivileges option.

Step 1: Connect with the appropriate privileges.

Connect to the mongod or mongos as a user with appropriate privileges.

For example, the following operation connects to MongoDB as user123 created in the Prerequisites section.

mongo --port 27017 -u user123 -p 12345678 --authenticationDatabase test

To check that you have the privileges specified in the Prerequisites section as well as to see user information, use the usersInfo command with the showPrivileges option.

2

Change your password and custom data.

Use the db.updateUser() method to update the password and custom data.

For example, the following operation changes thw user’s password to KNlZmiaNUp0B and custom data to { title: "Senior Manager" }:

use test
db.updateUser(
   "user123",
   {
      pwd: "KNlZmiaNUp0B",
      customData: { title: "Senior Manager" }
   }
)

Step 2: Change your password and custom data.

Use the db.updateUser() method to update the password and custom data.

For example, the following operation changes thw user’s password to KNlZmiaNUp0B and custom data to { title: "Senior Manager" }:

use test
db.updateUser(
   "user123",
   {
      pwd: "KNlZmiaNUp0B",
      customData: { title: "Senior Manager" }
   }
)

Configure System Events Auditing

New in version 2.6.

MongoDB Enterprise supports auditing of various operations. A complete auditing solution must involve all mongod server and mongos router processes.

The audit facility can write audit events to the console, the syslog (option is unavailable on Windows), a JSON file, or a BSON file. For details on the audited operations and the audit log messages, see System Event Audit Messages.

Enable and Configure Audit Output

Use the --auditDestination option to enable auditing and specify where to output the audit events.

Output to Syslog

To enable auditing and print audit events to the syslog (option is unavailable on Windows) in JSON format, specify syslog for the --auditDestination setting. For example:

mongod --dbpath data/db --auditDestination syslog

Warning

The syslog message limit can result in the truncation of the audit messages. The auditing system will neither detect the truncation nor error upon its occurrence.

You may also specify these options in the configuration file:

storage:
   dbPath: data/db
auditLog:
   destination: syslog

Output to Console

To enable auditing and print the audit events to standard output (i.e. stdout), specify console for the --auditDestination setting. For example:

mongod --dbpath data/db --auditDestination console

You may also specify these options in the configuration file:

storage:
   dbPath: data/db
auditLog:
   destination: console

Output to JSON File

To enable auditing and print audit events to a file in JSON format, specify file for the --auditDestination setting, JSON for the --auditFormat setting, and the output filename for the --auditPath. The --auditPath option accepts either full path name or relative path name. For example, the following enables auditing and records audit events to a file with the relative path name of data/db/auditLog.json:

mongod --dbpath data/db --auditDestination file --auditFormat JSON --auditPath data/db/auditLog.json

The audit file rotates at the same time as the server log file.

You may also specify these options in the configuration file:

storage:
   dbPath: data/db
auditLog:
   destination: file
   format: JSON
   path: data/db/auditLog.json

Note

Printing audit events to a file in JSON format degrades server performance more than printing to a file in BSON format.

Output to BSON File

To enable auditing and print audit events to a file in BSON binary format, specify file for the --auditDestination setting, BSON for the --auditFormat setting, and the output filename for the --auditPath. The --auditPath option accepts either full path name or relative path name. For example, the following enables auditing and records audit events to a BSON file with the relative path name of data/db/auditLog.bson:

mongod --dbpath data/db --auditDestination file --auditFormat BSON --auditPath data/db/auditLog.bson

The audit file rotates at the same time as the server log file.

You may also specify these options in the configuration file:

storage:
   dbPath: data/db
auditLog:
   destination: file
   format: BSON
   path: data/db/auditLog.bson

To view the contents of the file, pass the file to the MongoDB utility bsondump. For example, the following converts the audit log into a human-readable form and output to the terminal:

bsondump data/db/auditLog.bson

Filter Events

By default, the audit facility records all auditable operations as detailed in Audit Event Actions, Details, and Results. The audit feature has an --auditFilter option to determine which events to record.

The --auditFilter option takes a string representation of a query document of the form:

{ <field1>: <expression1>, ... }

The <field> can be any field in the audit message, including fields returned in the param document.

The <expression> is a query condition expression.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

Filter for Multiple Operation Types

The following example uses the filter { atype: { $in: [ "createCollection", "dropCollection" ] } } to audit only the createCollection and dropCollection actions.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auditDestination file --auditFilter '{ atype: { $in: [ "createCollection", "dropCollection" ] } }' --auditFormat JSON --auditPath data/db/auditLog.json

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

storage:
   dbPath: data/db
auditLog:
   destination: file
   format: JSON
   path: data/db/auditLog.json
   filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] } }'

Filter on Authentication Operations on a Single Database

The <field> can include any field in the audit message. For authentication operations, the audit messages include a db field in the param document.

The following example uses the filter { atype: "authenticate", "param.db": "test" } to audit only the authenticate operations that occur against the test database.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ atype: "authenticate", "param.db": "test" }' --auditFormat JSON --auditPath data/db/auditLog.json

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

storage:
   dbPath: data/db
security:
   authorization: enabled
auditLog:
   destination: file
   format: JSON
   path: data/db/auditLog.json
   filter: '{ atype: "authenticate", "param.db": "test" }'

To filter on all authenticate operations across databases, use the filter { atype: "authenticate" }.

Filter by Authorization Role

The following example uses the filter { roles: { role: "readWrite", db: "test" } } to only audit operations for users with readWrite role on the test database. This includes users with roles that inherit from readWrite.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ roles: { role: "readWrite", db: "test" } }' --auditFormat JSON --auditPath data/db/auditLog.json

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

storage:
   dbPath: data/db
security:
   authorization: enabled
auditLog:
   destination: file
   format: JSON
   path: data/db/auditLog.json
   filter: '{ roles: { role: "readWrite", db: "test" } }'

Filter by insert and remove Operations

To capture read and write operations in the audit, you must also enable the audit system to log authorization successes using the auditAuthorizationSuccess parameter. [1]

Note

Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ atype: "authCheck", "param.command": { $in: [ "insert", "delete" ] } }' --auditFormat JSON --auditPath data/db/auditLog.json

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

storage:
   dbPath: data/db
security:
   authorization: enabled
auditLog:
   destination: file
   format: JSON
   path: data/db/auditLog.json
   filter: '{ atype: "authCheck", "param.command": { $in: [ "insert", "delete" ] } }'
setParameter: { auditAuthorizationSuccess: true }

[1]
You can enable auditAuthorizationSuccess parameter without enabling --auth; however, all operations will return success for authorization checks.

Create a Vulnerability Report

If you believe you have discovered a vulnerability in MongoDB or have experienced a security incident related to MongoDB, please report the issue to aid in its resolution.

To report an issue, we strongly suggest filing a ticket in the SECURITY [https://jira.mongodb.org/browse/SECURITY] project in JIRA. MongoDB, Inc responds to vulnerability notifications within 48 hours.

Create the Report in JIRA

Submit a ticket in the Security [https://jira.mongodb.org/browse/SECURITY] project at: <http://jira.mongodb.org/browse>. The ticket number will become the reference identification for the issue for its lifetime. You can use this identifier for tracking purposes.

Information to Provide

All vulnerability reports should contain as much information as possible so MongoDB’s developers can move quickly to resolve the issue. In particular, please include the following:

The name of the product.

Common Vulnerability information, if applicable, including:

CVSS (Common Vulnerability Scoring System) Score.

CVE (Common Vulnerability and Exposures) Identifier.

Contact information, including an email address and/or phone number, if applicable.

Send the Report via Email

While JIRA is the preferred reporting method, you may also report vulnerabilities via email to security@mongodb.com.

You may encrypt email using MongoDB’s public key at https://docs.mongodb.org/10gen-security-gpg-key.asc.

MongoDB, Inc. responds to vulnerability reports sent via email with a response email that contains a reference number for a JIRA ticket posted to the SECURITY [https://jira.mongodb.org/browse/SECURITY] project.

Evaluation of a Vulnerability Report

MongoDB, Inc. validates all submitted vulnerabilities and uses Jira to track all communications regarding a vulnerability, including requests for clarification or additional information. If needed, MongoDB representatives set up a conference call to exchange information regarding the vulnerability.

Disclosure

MongoDB, Inc. requests that you do not publicly disclose any information regarding the vulnerability or exploit the issue until it has had the opportunity to analyze the vulnerability, to respond to the notification, and to notify key users, customers, and partners.

The amount of time required to validate a reported vulnerability depends on the complexity and severity of the issue. MongoDB, Inc. takes all required vulnerabilities very seriously and will always ensure that there is a clear and open channel of communication with the reporter.

After validating an issue, MongoDB, Inc. coordinates public disclosure of the issue with the reporter in a mutually agreed timeframe and format. If required or requested, the reporter of a vulnerability will receive credit in the published security bulletin.

Security Reference

Security Methods in the mongo Shell

Name | Description
db.auth() | Authenticates a user to a database.

User Management Methods

Name | Description
db.createUser() | Creates a new user.
db.addUser() | Deprecated. Adds a user to a database, and allows administrators to configure the user’s privileges.
db.updateUser() | Updates user data.
db.changeUserPassword() | Changes an existing user’s password.
db.removeUser() | Deprecated. Removes a user from a database.
db.dropAllUsers() | Deletes all users associated with a database.
db.dropUser() | Removes a single user.
db.grantRolesToUser() | Grants a role and its privileges to a user.
db.revokeRolesFromUser() | Removes a role from a user.
db.getUser() | Returns information about the specified user.
db.getUsers() | Returns information about all users associated with a database.

Role Management Methods

Name | Description
db.createRole() | Creates a role and specifies its privileges.
db.updateRole() | Updates a user-defined role.
db.dropRole() | Deletes a user-defined role.
db.dropAllRoles() | Deletes all user-defined roles associated with a database.
db.grantPrivilegesToRole() | Assigns privileges to a user-defined role.
db.revokePrivilegesFromRole() | Removes the specified privileges from a user-defined role.
db.grantRolesToRole() | Specifies roles from which a user-defined role inherits privileges.
db.revokeRolesFromRole() | Removes a role from a user.
db.getRole() | Returns information for the specified role.
db.getRoles() | Returns information for all the user-defined roles in a database.

Security Reference Documentation

Built-In Roles

Reference on MongoDB provided roles and corresponding access.

system.roles Collection

Describes the content of the collection that stores user-defined roles.

system.users Collection

Describes the content of the collection that stores users’ credentials and role assignments.

Resource Document

Describes the resource document for roles.

Privilege Actions

List of the actions available for privileges.

Default MongoDB Port

List of default ports used by MongoDB.

System Event Audit Messages

Reference on system event audit messages.

Built-In Roles

system.roles Collection

system.users Collection

Resource Document

Privilege Actions

Default MongoDB Port

System Event Audit Messages

Security Release Notes Alerts

Security Release Notes

Security vulnerability for password.

Security Release Notes

Built-In Roles

MongoDB grants access to data and commands through role-based authorization and provides built-in roles that provide the different levels of access commonly needed in a database system. You can additionally create user-defined roles.

A role grants privileges to perform sets of actions on defined resources. A given role applies to the database on which it is defined and can grant access down to a collection level of granularity.

Each of MongoDB’s built-in roles defines access at the database level for all non-system collections in the role’s database and at the collection level for all system collections.

MongoDB provides the built-in database user and database administration roles on every database. MongoDB provides all other built-in roles only on the admin database.

This section describes the privileges for each built-in role. You can also view the privileges for a built-in role at any time by issuing the rolesInfo command with the showPrivileges and showBuiltinRoles fields both set to true.

Database User Roles

Every database includes the following client roles:

read

Provides the ability to read data on all non-system collections and on the following system collections: system.indexes, system.js, and system.namespaces collections. The role provides read access by granting the following actions:

collStats

dbHash

dbStats

find

killCursors

readWrite

Provides all the privileges of the read role plus ability to modify data on all non-system collections and the system.js collection. The role provides the following actions on those collections:

collStats

convertToCapped

createCollection

dbHash

dbStats

dropCollection

createIndex

dropIndex

emptycapped

find

insert

killCursors

remove

renameCollectionSameDB

update

Database Administration Roles

Every database includes the following database administration roles:

dbAdmin

Provides the following actions on the database’s system.indexes, system.namespaces, and system.profile collections:

collStats

dbHash

dbStats

find

killCursors

dropCollection and createCollection on system.profile only

Changed in version 2.6.4: dbAdmin added the createCollection for the system.profile collection. Previous versions only had the dropCollection on the system.profile collection.

Provides the following actions on all non-system collections. This role*does not* include full read access on non-system collections:

collMod

collStats

compact

convertToCapped

createCollection

createIndex

dbStats

dropCollection

dropDatabase

dropIndex

enableProfiler

indexStats

reIndex

renameCollectionSameDB

repairDatabase

storageDetails

validate

dbOwner

The database owner can perform any administrative action on the database. This role combines the privileges granted by the readWrite, dbAdmin and userAdmin roles.

userAdmin

Provides the ability to create and modify roles and users on the current database. This role also indirectly provides superuser access to either the database or, if scoped to the admin database, the cluster. The userAdmin role allows users to grant any user any privilege, including themselves.

The userAdmin role explicitly provides the following actions:

changeCustomData

changePassword

createRole

createUser

dropRole

dropUser

grantRole

revokeRole

viewRole

viewUser

Cluster Administration Roles

The admin database includes the following roles for administering the whole system rather than just a single database. These roles include but are not limited to replica set and sharded cluster administrative functions.

clusterAdmin

Provides the greatest cluster-management access. This role combines the privileges granted by the clusterManager, clusterMonitor, and hostManager roles. Additionally, the role provides the dropDatabase action.

clusterManager

Provides management and monitoring actions on the cluster. A user with this role can access the config and local databases, which are used in sharding and replication, respectively.

Provides the following actions on the cluster as a whole:

addShard

applicationMessage

cleanupOrphaned

flushRouterConfig

listShards

removeShard

replSetConfigure

replSetGetStatus

replSetStateChange

resync

Provides the following actions on all databases in the cluster:

enableSharding

moveChunk

splitChunk

splitVector

On the config database, provides the following actions on the settings collection:

insert

remove

update

On the config database, provides the following actions on all configuration collections and on the system.indexes, system.js, and system.namespaces collections:

collStats

dbHash

dbStats

find

killCursors

On the local database, provides the following actions on the replset collection:

collStats

dbHash

dbStats

find

killCursors

clusterMonitor

Provides read-only access to monitoring tools, such as the MongoDB Management Service (MMS) [https://docs.mms.mongodb.com/] monitoring agent.

Provides the following actions on the cluster as a whole:

connPoolStats

cursorInfo

getCmdLineOpts

getLog

getParameter

getShardMap

hostInfo

inprog

listDatabases

listShards

netstat

replSetGetStatus

serverStatus

shardingState

top

Provides the following actions on all databases in the cluster:

collStats

dbStats

getShardVersion

Provides the find action on all system.profile collections in the cluster.

Provides the following actions on the config database’s configuration collections and system.indexes, system.js, and system.namespaces collections:

collStats

dbHash

dbStats

find

killCursors

hostManager

Provides the ability to monitor and manage servers.

Provides the following actions on the cluster as a whole:

applicationMessage

closeAllDatabases

connPoolSync

cpuProfiler

diagLogging

flushRouterConfig

fsync

invalidateUserCache

killop

logRotate

resync

setParameter

shutdown

touch

unlock

Provides the following actions on all databases in the cluster:

killCursors

repairDatabase

Backup and Restoration Roles

The admin database includes the following roles for backing up and restoring data:

backup

Provides minimal privileges needed for backing up data. This role provides sufficient privileges to use the MongoDB Management Service (MMS) [https://docs.mms.mongodb.com/] backup agent, or to use mongodump to back up an entire mongod instance.

Provides the following actions on the mms.backup collection in the admin database:

insert

update

Provides the listDatabases action on the cluster as a whole.

Provides the find action on the following:

all non-system collections in the cluster

all the following system collections in the cluster: system.indexes, system.namespaces, and system.js

the admin.system.users and admin.system.roles collections

legacy system.users collections from versions of MongoDB prior to 2.6

restore

Provides minimal privileges needed for restoring data from backups. This role provides sufficient privileges to use the mongorestore tool to restore an entire mongod instance.

Provides the following actions on all non-system collections and system.js collections in the cluster; on the admin.system.users and admin.system.roles collections in the admin database; and on legacy system.users collections from versions of MongoDB prior to 2.6:

collMod

createCollection

createIndex

dropCollection

insert

Provides the following additional actions on admin.system.users and legacy system.users collections:

find

remove

update

Provides the find action on all the system.namespaces collections in the cluster.

Although, restore includes the ability to modify the documents in the admin.system.users collection using normal modification operations, only modify these data using the user management methods.

All-Database Roles

The admin database provides the following roles that apply to all databases in a mongod instance and are roughly equivalent to their single-database equivalents:

readAnyDatabase

Provides the same read-only permissions as read, except it applies to all databases in the cluster. The role also provides the listDatabases action on the cluster as a whole.

readWriteAnyDatabase

Provides the same read and write permissions as readWrite, except it applies to all databases in the cluster. The role also provides the listDatabases action on the cluster as a whole.

userAdminAnyDatabase

Provides the same access to user administration operations as userAdmin, except it applies to all databases in the cluster. The role also provides the following actions on the cluster as a whole:

authSchemaUpgrade

invalidateUserCache

listDatabases

The role also provides the following actions on the admin.system.users and admin.system.roles collections on the admin database, and on legacy system.users collections from versions of MongoDB prior to 2.6:

collStats

dbHash

dbStats

find

killCursors

planCacheRead

Changed in version 2.6.4: userAdminAnyDatabase added the following permissions on the admin.system.users and admin.system.roles collections:

createIndex

dropIndex

The userAdminAnyDatabase role does not restrict the permissions that a user can grant. As a result, userAdminAnyDatabase users can grant themselves privileges in excess of their current privileges and even can grant themselves all privileges, even though the role does not explicitly authorize privileges beyond user administration. This role is effectively a MongoDB system superuser.

dbAdminAnyDatabase

Provides the same access to database administration operations as dbAdmin, except it applies to all databases in the cluster. The role also provides the listDatabases action on the cluster as a whole.

Superuser Roles

Several roles provide either indirect or direct system-wide superuser access.

The following roles provide the ability to assign any user any privilege on any database, which means that users with one of these roles can assign themselves any privilege on any database:

dbOwner role, when scoped to the admin database

userAdmin role, when scoped to the admin database

userAdminAnyDatabase role

The following role provides full privileges on all resources:

root

Provides access to the operations and all the resources of the readWriteAnyDatabase, dbAdminAnyDatabase, userAdminAnyDatabase and clusterAdmin roles combined.

root does not include any access to collections that begin with the system. prefix.

For example, without the ability to insert data directly into the:data:system.users <admin.system.users> and system.roles collections in the admin database. root is not suitable for writing or restoring data that have these collections (e.g. with mongorestore.) To perform these kinds of restore operations, provision users with the restore role.

Internal Role

__system

MongoDB assigns this role to user objects that represent cluster members, such as replica set members and mongos instances. The role entitles its holder to take any action against any object in the database.

Do not assign this role to user objects representing applications or human administrators, other than in exceptional circumstances.

If you need access to all actions on all resources, for example to run the eval or applyOps commands, do not assign this role. Instead, create a user-defined role that grants anyAction on anyResource and ensure that only the users who needs access to these operations has this access.

system.roles Collection

New in version 2.6.

The system.roles collection in the admin database stores the user-defined roles. To create and manage these user-defined roles, MongoDB provides role management commands.

system.roles Schema

The documents in the system.roles collection have the following schema:

{
  _id: <system-defined id>,
  role: "<role name>",
  db: "<database>",
  privileges:
      [
          {
              resource: { <resource> },
              actions: [ "<action>", ... ]
          },
          ...
      ],
  roles:
      [
          { role: "<role name>", db: "<database>" },
          ...
      ]
}

A system.roles document has the following fields:

admin.system.roles.role

The role field is a string that specifies the name of the role.

admin.system.roles.db

The db field is a string that specifies the database to which the role belongs. MongoDB uniquely identifies each role by the pairing of its name (i.e. role) and its database.

admin.system.roles.privileges

The privileges array contains the privilege documents that define the privileges for the role.

A privilege document has the following syntax:

{
  resource: { <resource> },
  actions: [ "<action>", ... ]
}

Each privilege document has the following fields:

admin.system.roles.privileges[n].resource

A document that specifies the resources upon which the privilege actions apply. The document has one of the following form:

{ db: <database>, collection: <collection> }

or

{ cluster : true }

See Resource Document for more details.

admin.system.roles.privileges[n].actions

An array of actions permitted on the resource. For a list of actions, see Privilege Actions.

admin.system.roles.roles

The roles array contains role documents that specify the roles from which this role inherits privileges.

A role document has the following syntax:

{ role: "<role name>", db: "<database>" }

A role document has the following fields:

admin.system.roles.roles[n].role

The name of the role. A role can be a built-in role provided by MongoDB or a user-defined role.

admin.system.roles.roles[n].db

The name of the database where the role is defined.

Examples

Consider the following sample documents found in system.roles collection of the admin database.

A User-Defined Role Specifies Privileges

The following is a sample document for a user-defined role appUser defined for the myApp database:

{
  _id: "myApp.appUser",
  role: "appUser",
  db: "myApp",
  privileges: [
       { resource: { db: "myApp" , collection: "" },
         actions: [ "find", "createCollection", "dbStats", "collStats" ] },
       { resource: { db: "myApp", collection: "logs" },
         actions: [ "insert" ] },
       { resource: { db: "myApp", collection: "data" },
         actions: [ "insert", "update", "remove", "compact" ] },
       { resource: { db: "myApp", collection: "system.indexes" },
         actions: [ "find" ] },
       { resource: { db: "myApp", collection: "system.namespaces" },
         actions: [ "find" ] },
  ],
  roles: []
}

The privileges array lists the five privileges that the appUser role specifies:

The first privilege permits its actions ( "find", "createCollection", "dbStats", "collStats") on all the collections in the myApp database excluding its system collections. See Specify a Database as Resource.

The next two privileges permits additional actions on specific collections, logs and data, in the myApp database. See Specify a Collection of a Database as Resource.

The last two privileges permits actions on two system collections in the myApp database. While the first privilege gives database-wide permission for the find action, the action does not apply to myApp‘s system collections. To give access to a system collection, a privilege must explicitly specify the collection. See Resource Document.

As indicated by the empty roles array, appUser inherits no additional privileges from other roles.

User-Defined Role Inherits from Other Roles

The following is a sample document for a user-defined role appAdmin defined for the myApp database: The document shows that the appAdmin role specifies privileges as well as inherits privileges from other roles:

{
  _id: "myApp.appAdmin",
  role: "appAdmin",
  db: "myApp",
  privileges: [
                {
                  resource: { db: "myApp", collection: "" },
                  actions: [ "insert", "dbStats", "collStats", "compact", "repairDatabase" ]
                }
              ],
  roles: [
           { role: "appUser", db: "myApp" }
         ]
}

The privileges array lists the privileges that the appAdmin role specifies. This role has a single privilege that permits its actions ( "insert", "dbStats", "collStats", "compact", "repairDatabase") on all the collections in the myApp database excluding its system collections. See Specify a Database as Resource.

The roles array lists the roles, identified by the role names and databases, from which the role appAdmin inherits privileges.

system.users Collection

Changed in version 2.6.

The system.users collection in the admin database stores user authentication and authorization information. To manage data in this collection, MongoDB provides user management commands.

system.users Schema

The documents in the system.users collection have the following schema:

{
  _id: <system defined id>,
  user: "<name>",
  db: "<database>",
  credentials: { <authentication credentials> },
  roles: [
           { role: "<role name>", db: "<database>" },
           ...
         ],
  customData: <custom information>
 }

Each system.users document has the following fields:

admin.system.users.user

The user field is a string that identifies the user. A user exists in the context of a single logical database but can have access to other databases through roles specified in the roles array.

admin.system.users.db

The db field specifies the database associated with the user. The user’s privileges are not necessarily limited to this database. The user can have privileges in additional databases through the roles array.

admin.system.users.credentials

The credentials field contains the user’s authentication information. For users with externally stored authentication credentials, such as users that use Kerberos or x.509 certificates for authentication, the system.users document for that user does not contain the credentials field.

admin.system.users.roles

The roles array contains role documents that specify the roles granted to the user. The array contains both built-in roles and user-defined role.

A role document has the following syntax:

{ role: "<role name>", db: "<database>" }

A role document has the following fields:

admin.system.users.roles[n].role

The name of a role. A role can be a built-in role provided by MongoDB or a custom user-defined role.

admin.system.users.roles[n].db

The name of the database where role is defined.

When specifying a role using the role management or user management commands, you can specify the role name alone (e.g. "readWrite") if the role that exists on the database on which the command is run.

admin.system.users.customData

The customData field contains optional custom information about the user.

Example

Consider the following document in the system.users collection:

{
  _id: "home.Kari",
  user: "Kari",
  db: "home",
  credentials: { "MONGODB-CR" :"<hashed password>" },
  roles : [
            { role: "read", db: "home" },
            { role: "readWrite", db: "test" },
            { role: "appUser", db: "myApp" }
          ],
  customData: { zipCode: "64157" }
}

The document shows that a user Kari is associated with the home database. Kari has the read role in the home database, the readWrite role in the test database, and the appUser role in the myApp database.

Resource Document

The resource document specifies the resources upon which a privilege permits actions.

Database and/or Collection Resource

To specify databases and/or collections, use the following syntax:

{ db: <database>, collection: <collection> }

Specify a Collection of a Database as Resource

If the resource document species both the db and collection fields as non-empty strings, the resource is the specified collection in the specified database. For example, the following document specifies a resource of the inventory collection in the products database:

{ db: "products", collection: "inventory" }

For a user-defined role scoped for a non-admin database, the resource specification for its privileges must specify the same database as the role. User-defined roles scoped for the admin database can specify other databases.

Specify a Database as Resource

If only the collection field is an empty string (""), the resource is the specified database, excluding the system collections. For example, the following resource document specifies the resource of the test database, excluding the system collections:

{ db: "test", collection: "" }

For a user-defined role scoped for a non-admin database, the resource specification for its privileges must specify the same database as the role. User-defined roles scoped for the admin database can specify other databases.

Note

When you specify a database as the resource, the system collections are excluded, unless you name them explicitly, as in the following:

{ db: "test", collection: "system.namespaces" }

System collections include but are not limited to the following:

<database>.system.profile

<database>.system.namespaces

<database>.system.indexes

<database>.system.js

local.system.replset

system.users Collection in the admin database

system.roles Collection in the admin database

Specify Collections Across Databases as Resource

If only the db field is an empty string (""), the resource is all collections with the specified name across all databases. For example, the following document specifies the resource of all the accounts collections across all the databases:

{ db: "", collection: "accounts" }

For user-defined roles, only roles scoped for the admin database can have this resource specification for their privileges.

Specify All Non-System Collections in All Databases

If both the db and collection fields are empty strings (""), the resource is all collections, excluding the system collections, in all the databases:

{ db: "", collection: "" }

For user-defined roles, only roles scoped for the admin database can have this resource specification for their privileges.

Cluster Resource

To specify the cluster as the resource, use the following syntax:

{ cluster : true }

Use the cluster resource for actions that affect the state of the system rather than act on specific set of databases or collections. Examples of such actions are shutdown, replSetReconfig, and addShard. For example, the following document grants the action shutdown on the cluster.

{ resource: { cluster : true }, actions: [ "shutdown" ] }

For user-defined roles, only roles scoped for the admin database can have this resource specification for their privileges.

anyResource

The internal resource anyResource gives access to every resource in the system and is intended for internal use. Do not use this resource, other than in exceptional circumstances. The syntax for this resource is { anyResource: true }.

Privilege Actions

New in version 2.6.

Privilege actions define the operations a user can perform on a resource. A MongoDB privilege comprises a resource and the permitted actions. This page lists available actions grouped by common purpose.

MongoDB provides built-in roles with pre-defined pairings of resources and permitted actions. For lists of the actions granted, see Built-In Roles. To define custom roles, see Create a Role.

Query and Write Actions

find

User can perform the db.collection.find() method. Apply this action to database or collection resources.

insert

User can perform the insert command. Apply this action to database or collection resources.

remove

User can perform the db.collection.remove() method. Apply this action to database or collection resources.

update

User can perform the update command. Apply this action to database or collection resources.

Database Management Actions

changeCustomData

User can change the custom information of any user in the given database. Apply this action to database resources.

changeOwnCustomData

Users can change their own custom information. Apply this action to database resources.

changeOwnPassword

Users can change their own passwords. Apply this action to database resources.

changePassword

User can change the password of any user in the given database. Apply this action to database resources.

createCollection

User can perform the db.createCollection() method. Apply this action to database or collection resources.

createIndex

Provides access to the db.collection.createIndex() method and the createIndexes command. Apply this action to database or collection resources.

createRole

User can create new roles in the given database. Apply this action to database resources.

createUser

User can create new users in the given database. Apply this action to database resources.

dropCollection

User can perform the db.collection.drop() method. Apply this action to database or collection resources.

dropRole

User can delete any role from the given database. Apply this action to database resources.

dropUser

User can remove any user from the given database. Apply this action to database resources.

emptycapped

User can perform the emptycapped command. Apply this action to database or collection resources.

enableProfiler

User can perform the db.setProfilingLevel() method. Apply this action to database resources.

grantRole

User can grant any role in the database to any user from any database in the system. Apply this action to database resources.

killCursors

User can kill cursors on the target collection.

revokeRole

User can remove any role from any user from any database in the system. Apply this action to database resources.

unlock

User can perform the db.fsyncUnlock() method. Apply this action to the cluster resource.

viewRole

User can view information about any role in the given database. Apply this action to database resources.

viewUser

User can view the information of any user in the given database. Apply this action to database resources.

Deployment Management Actions

authSchemaUpgrade

User can perform the authSchemaUpgrade command. Apply this action to the cluster resource.

cleanupOrphaned

User can perform the cleanupOrphaned command. Apply this action to the cluster resource.

cpuProfiler

User can enable and use the CPU profiler. Apply this action to the cluster resource.

inprog

User can use the db.currentOp() method to return pending and active operations. Apply this action to the cluster resource.

invalidateUserCache

Provides access to the invalidateUserCache command. Apply this action to the cluster resource.

killop

User can perform the db.killOp() method. Apply this action to the cluster resource.

planCacheRead

User can perform the planCacheListPlans and planCacheListQueryShapes commands and the PlanCache.getPlansByQuery() and PlanCache.listQueryShapes() methods. Apply this action to database or collection resources.

planCacheWrite

User can perform the planCacheClear command and the PlanCache.clear() and PlanCache.clearPlansByQuery() methods. Apply this action to database or collection resources.

storageDetails

User can perform the storageDetails command. Apply this action to database or collection resources.

Replication Actions

appendOplogNote

User can append notes to the oplog. Apply this action to the cluster resource.

replSetConfigure

User can configure a replica set. Apply this action to the cluster resource.

replSetGetStatus

User can perform the replSetGetStatus command. Apply this action to the cluster resource.

replSetHeartbeat

User can perform the replSetHeartbeat command. Apply this action to the cluster resource.

replSetStateChange

User can change the state of a replica set through the replSetFreeze, replSetMaintenance, replSetStepDown, and replSetSyncFrom commands. Apply this action to the cluster resource.

resync

User can perform the resync command. Apply this action to the cluster resource.

Sharding Actions

addShard

User can perform the addShard command. Apply this action to the cluster resource.

enableSharding

User can enable sharding on a database using the enableSharding command and can shard a collection using the shardCollection command. Apply this action to database or collection resources.

flushRouterConfig

User can perform the flushRouterConfig command. Apply this action to the cluster resource.

getShardMap

User can perform the getShardMap command. Apply this action to the cluster resource.

getShardVersion

User can perform the getShardVersion command. Apply this action to database resources.

listShards

User can perform the listShards command. Apply this action to the cluster resource.

moveChunk

User can perform the moveChunk command. In addition, user can perform the movePrimary command provided that the privilege is applied to an appropriate database resource. Apply this action to database or collection resources.

removeShard

User can perform the removeShard command. Apply this action to the cluster resource.

shardingState

User can perform the shardingState command. Apply this action to the cluster resource.

splitChunk

User can perform the splitChunk command. Apply this action to database or collection resources.

splitVector

User can perform the splitVector command. Apply this action to database or collection resources.

Server Administration Actions

applicationMessage

User can perform the logApplicationMessage command. Apply this action to the cluster resource.

closeAllDatabases

User can perform the closeAllDatabases command. Apply this action to the cluster resource.

collMod

User can perform the collMod command. Apply this action to database or collection resources.

compact

User can perform the compact command. Apply this action to database or collection resources.

connPoolSync

User can perform the connPoolSync command. Apply this action to the cluster resource.

convertToCapped

User can perform the convertToCapped command. Apply this action to database or collection resources.

dropDatabase

User can perform the dropDatabase command. Apply this action to database resources.

dropIndex

User can perform the dropIndexes command. Apply this action to database or collection resources.

fsync

User can perform the fsync command. Apply this action to the cluster resource.

getParameter

User can perform the getParameter command. Apply this action to the cluster resource.

hostInfo

Provides information about the server the MongoDB instance runs on. Apply this action to the cluster resource.

logRotate

User can perform the logRotate command. Apply this action to the cluster resource.

reIndex

User can perform the reIndex command. Apply this action to database or collection resources.

renameCollectionSameDB

Allows the user to rename collections on the current database using the renameCollection command. Apply this action to database resources.

Additionally, the user must either have find on the source collection or not have find on the destination collection.

If a collection with the new name already exists, the user must also have the dropCollection action on the destination collection.

repairDatabase

User can perform the repairDatabase command. Apply this action to database resources.

setParameter

User can perform the setParameter command. Apply this action to the cluster resource.

shutdown

User can perform the shutdown command. Apply this action to the cluster resource.

touch

User can perform the touch command. Apply this action to the cluster resource.

Diagnostic Actions

collStats

User can perform the collStats command. Apply this action to database or collection resources.

connPoolStats

User can perform the connPoolStats and shardConnPoolStats commands. Apply this action to the cluster resource.

cursorInfo

User can perform the cursorInfo command. Apply this action to the cluster resource.

dbHash

User can perform the dbHash command. Apply this action to database or collection resources.

dbStats

User can perform the dbStats command. Apply this action to database resources.

diagLogging

User can perform the diagLogging command. Apply this action to the cluster resource.

getCmdLineOpts

User can perform the getCmdLineOpts command. Apply this action to the cluster resource.

getLog

User can perform the getLog command. Apply this action to the cluster resource.

indexStats

User can perform the indexStats command. Apply this action to database or collection resources.

listDatabases

User can perform the listDatabases command. Apply this action to the cluster resource.

netstat

User can perform the netstat command. Apply this action to the cluster resource.

serverStatus

User can perform the serverStatus command. Apply this action to the cluster resource.

validate

User can perform the validate command. Apply this action to database or collection resources.

top

User can perform the top command. Apply this action to the cluster resource.

Internal Actions

anyAction

Allows any action on a resource. Do not assign this action except for exceptional circumstances.

internal

Allows internal actions. Do not assign this action except for exceptional circumstances.

Default MongoDB Port

The following table lists the default ports used by MongoDB:

Default Port | Description
27017 | The default port for mongod and mongos instances. You can change this port with port or --port.
27018 | The default port when running with --shardsvr runtime operation or the shardsvr value for the clusterRole setting in a configuration file.
27019 | The default port when running with --configsvr runtime operation or the configsvr value for the clusterRole setting in a configuration file.
28017 | The default port for the web status page. The web status page is always accessible at a port number that is 1000 greater than the port determined by port.

System Event Audit Messages

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

Audit Message

The event auditing feature can record events in JSON format. To configure auditing output, see Configure System Events Auditing

The recorded JSON messages have the following syntax:

{
  atype: <String>,
  ts : { "$date": <timestamp> },
  local: { ip: <String>, port: <int> },
  remote: { ip: <String>, port: <int> },
  users : [ { user: <String>, db: <String> }, ... ],
  roles: [ { role: <String>, db: <String> }, ... ],
  param: <document>,
  result: <int>
}

Field | Description
atype | Action type. See Audit Event Actions, Details, and Results.
ts | Document that contains the date and UTC time of the event, in ISO 8601 format.
local | Document that contains the local ip address and the port number of the running instance.
remote | Document that contains the remote ip address and the port number of the incoming connection associated with the event.
users | Array of user identification documents. Because MongoDB allows a session to log in with different user per database, this array can have more than one user. Each document contains a user field for the username and a db field for the authentication database for that user.
roles | Array of documents that specify the roles granted to the user. Each document contains a role field for the name of the role and a db field for the database associated with the role.
param | Specific details for the event. See Audit Event Actions, Details, and Results.
result | Error code. See Audit Event Actions, Details, and Results.

field String atype:
| Action type. See Audit Event Actions, Details, and Results.
field document ts:
| Document that contains the date and UTC time of the event, in ISO 8601 format.
field document local:
| Document that contains the local ip address and the port number of the running instance.
field document remote:
| Document that contains the remote ip address and the port number of the incoming connection associated with the event.
field array users:
| Array of user identification documents. Because MongoDB allows a session to log in with different user per database, this array can have more than one user. Each document contains a user field for the username and a db field for the authentication database for that user.
field array roles:
| Array of documents that specify the roles granted to the user. Each document contains a role field for the name of the role and a db field for the database associated with the role.
field document param:
| Specific details for the event. See Audit Event Actions, Details, and Results.
field integer result:
| Error code. See Audit Event Actions, Details, and Results.

Audit Event Actions, Details, and Results

The following table lists for each atype or action type, the associated param details and the result values, if any.

atype
param
result

authenticate

{
  user: <user name>,
  db: <database>,
  mechanism: <mechanism>
}

0 - Success

18 - Authentication Failed

authCheck

{
  command: <name>,
  ns: <database>.<collection>,
  args: <command object>
}

ns field is optional.

args field may be redacted.

0 - Success

13 - Unauthorized to perform the operation.

By default, the auditing system logs only the authorization failures. To enable the system to log authorization successes, use the auditAuthorizationSuccess parameter. [1]

createCollection

{ ns: <database>.<collection> }

0 - Success

createDatabase

{ ns: <database> }

0 - Success

createIndex

{
  ns: <database>.<collection>,
  indexName: <index name>,
  indexSpec: <index specification>
}

0 - Success

renameCollection

{
  old: <database>.<collection>,
  new: <database>.<collection>
}

0 - Success

dropCollection

{ ns: <database>.<collection> }

0 - Success

dropDatabase

{ ns: <database> }

0 - Success

dropIndex

{
  ns: <database>.<collection>,
  indexName: <index name>
}

0 - Success

createUser

{
  user: <user name>,
  db: <database>,
  customData: <document>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

The customData field is optional.

0 - Success

dropUser

{
  user: <user name>,
  db: <database>
}

0 - Success

dropAllUsersFromDatabase

{ db: <database> }

0 - Success

updateUser

{
  user: <user name>,
  db: <database>,
  passwordChanged: <boolean>,
  customData: <document>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

The customData field is optional.

0 - Success

grantRolesToUser

{
  user: <user name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

0 - Success

revokeRolesFromUser

{
  user: <user name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

0 - Success

createRole

{
  role: <role name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ],
  privileges: [
    {
      resource: <resource document>,
      actions: [ <action>, ... ]
    },
    ...
  ]
}

The roles and the privileges fields are optional.

For details on the resource document, see Resource Document. For a list of actions, see Privilege Actions.

0 - Success

updateRole

{
  role: <role name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ],
  privileges: [
    {
      resource: <resource document>,
      actions: [ <action>, ... ]
    },
    ...
  ]
}

The roles and the privileges fields are optional.

For details on the resource document, see Resource Document. For a list of actions, see Privilege Actions.

0 - Success

dropRole

{
  role: <role name>,
  db: <database>
}

0 - Success

dropAllRolesFromDatabase

{ db: <database> }

0 - Success

grantRolesToRole

{
  role: <role name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

0 - Success

revokeRolesFromRole

{
  role: <role name>,
  db: <database>,
  roles: [
     {
       role: <role name>,
       db: <database>
     },
     ...
  ]
}

0 - Success

grantPrivilegesToRole

{
  role: <role name>,
  db: <database>,
  privileges: [
    {
      resource: <resource document>,
      actions: [ <action>, ... ]
    },
    ...
  ]
}

For details on the resource document, see Resource Document. For a list of actions, see Privilege Actions.

0 - Success

revokePrivilegesFromRole

{
  role: <role name>,
  db: <database name>,
  privileges: [
    {
      resource: <resource document>,
      actions: [ <action>, ... ]
    },
    ...
  ]
}

For details on the resource document, see Resource Document. For a list of actions, see Privilege Actions.

0 - Success

replSetReconfig

{
  old: <configuration>,
  new: <configuration>
}

Indicates membership change in the replica set.

The old field is optional.

0 - Success

enableSharding

{ ns: <database> }

0 - Success

shardCollection

{
  ns: <database>.<collection>,
  key: <shard key pattern>,
  options: { unique: <boolean> }
}

0 - Success

addShard

{
  shard: <shard name>,
  connectionString: <hostname>:<port>,
  maxSize: <maxSize>
}

When a shard is a replica set, the connectionString includes the replica set name and can include other members of the replica set.

0 - Success

removeShard

{ shard: <shard name> }

0 - Success

shutdown

{ }

Indicates commencement of database shutdown.

0 - Success

applicationMessage

{ msg: <custom message string> }

See logApplicationMessage.

0 - Success

[1]
Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

Security Release Notes

Access to system.users Collection

Changed in version 2.4.

In 2.4, only users with the userAdmin role have access to the system.users collection.

In version 2.2 and earlier, the read-write users of a database all have access to the system.users collection, which contains the user names and user password hashes. [1]

[1]
Read-only users do not have access to the system.users collection.

Password Hashing Insecurity

If a user has the same password for multiple databases, the hash will be the same. A malicious user could exploit this to gain access on a second database using a different user’s credentials.

As a result, always use unique username and password combinations for each database.

Thanks to Will Urbanski, from Dell SecureWorks, for identifying this issue.

Aggregation

Aggregations operations process data records and return computed results. Aggregation operations group values from multiple documents together, and can perform a variety of operations on the grouped data to return a single result. MongoDB provides three ways to perform aggregation: the aggregation pipeline, the map-reduce function, and single purpose aggregation methods and commands.

Aggregation Introduction

A high-level introduction to aggregation.

Aggregation Concepts

Introduces the use and operation of the data aggregation modalities available in MongoDB.

Aggregation Pipeline

The aggregation pipeline is a framework for performing aggregation tasks, modeled on the concept of data processing pipelines. Using this framework, MongoDB passes the documents of a single collection through a pipeline. The pipeline transforms the documents into aggregated results, and is accessed through the aggregate database command.

Map-Reduce

Map-reduce is a generic multi-phase data aggregation modality for processing quantities of data. MongoDB provides map-reduce with the mapReduce database command.

Single Purpose Aggregation Operations

MongoDB provides a collection of specific data aggregation operations to support a number of common data aggregation functions. These operations include returning counts of documents, distinct values of a field, and simple grouping operations.

Aggregation Mechanics

Details internal optimization operations, limits, support for sharded collections, and concurrency concerns.

Aggregation Examples

Examples and tutorials for data aggregation operations in MongoDB.

Aggregation Reference

References for all aggregation operations material for all data aggregation methods in MongoDB.

Aggregation Introduction

Aggregation Concepts

Aggregation Pipeline

Map-Reduce

Single Purpose Aggregation Operations

Aggregation Mechanics

Aggregation Pipeline Optimization

Aggregation Pipeline Limits

Aggregation Pipeline and Sharded Collections

Map-Reduce and Sharded Collections

Map Reduce Concurrency

Aggregation Examples

Aggregation with the Zip Code Data Set

Aggregation with User Preference Data

Map-Reduce Examples

Perform Incremental Map-Reduce

Troubleshoot the Map Function

Troubleshoot the Reduce Function

Aggregation Reference

Aggregation Pipeline Quick Reference

Aggregation Commands Comparison

SQL to Aggregation Mapping Chart

Aggregation Commands

Variables in Aggregation Expressions

Aggregation Introduction

Aggregations are operations that process data records and return computed results. MongoDB provides a rich set of aggregation operations that examine and perform calculations on the data sets. Running data aggregation on the mongod instance simplifies application code and limits resource requirements.

Like queries, aggregation operations in MongoDB use collections of documents as an input and return results in the form of one or more documents.

Aggregation Modalities

Aggregation Pipelines

MongoDB 2.2 introduced a new aggregation framework, modeled on the concept of data processing pipelines. Documents enter a multi-stage pipeline that transforms the documents into an aggregated result.

The most basic pipeline stages provide filters that operate like queries and document transformations that modify the form of the output document.

Other pipeline operations provide tools for grouping and sorting documents by specific field or fields as well as tools for aggregating the contents of arrays, including arrays of documents. In addition, pipeline stages can use operators for tasks such as calculating the average or concatenating a string.

The pipeline provides efficient data aggregation using native operations within MongoDB, and is the preferred method for data aggregation in MongoDB.

Map-Reduce

MongoDB also provides map-reduce operations to perform aggregation. In general, map-reduce operations have two phases: a map stage that processes each document and emits one or more objects for each input document, and reduce phase that combines the output of the map operation. Optionally, map-reduce can have a finalize stage to make final modifications to the result. Like other aggregation operations, map-reduce can specify a query condition to select the input documents as well as sort and limit the results.

Map-reduce uses custom JavaScript functions to perform the map and reduce operations, as well as the optional finalize operation. While the custom JavaScript provide great flexibility compared to the aggregation pipeline, in general, map-reduce is less efficient and more complex than the aggregation pipeline.

Note

Starting in MongoDB 2.4, certain mongo shell functions and properties are inaccessible in map-reduce operations. MongoDB 2.4 also provides support for multiple JavaScript operations to run at the same time. Before MongoDB 2.4, JavaScript code executed in a single thread, raising concurrency issues for map-reduce.

Single Purpose Aggregation Operations

For a number of common single purpose aggregation operations, MongoDB provides special purpose database commands. These common aggregation operations are: returning a count of matching documents, returning the distinct values for a field, and grouping data based on the values of a field. All of these operations aggregate documents from a single collection. While these operations provide simple access to common aggregation processes, they lack the flexibility and capabilities of the aggregation pipeline and map-reduce.

Additional Features and Behaviors

Both the aggregation pipeline and map-reduce can operate on a sharded collection. Map-reduce operations can also output to a sharded collection. See Aggregation Pipeline and Sharded Collections and Map-Reduce and Sharded Collections for details.

The aggregation pipeline can use indexes to improve its performance during some of its stages. In addition, the aggregation pipeline has an internal optimization phase. See Pipeline Operators and Indexes and Aggregation Pipeline Optimization for details.

For a feature comparison of the aggregation pipeline, map-reduce, and the special group functionality, see Aggregation Commands Comparison.

Additional Resources

MongoDB Analytics: Learn Aggregation by Example: Exploratory Analytics and Visualization Using Flight Data [http://www.mongodb.com/presentations/mongodb-analytics-learn-aggregation-example-exploratory-analytics-and-visualization]

MongoDB for Time Series Data: Analyzing Time Series Data Using the Aggregation Framework and Hadoop [http://www.mongodb.com/presentations/mongodb-time-series-data-part-2-analyzing-time-series-data-using-aggregation-framework]

The Aggregation Framework [https://www.mongodb.com/presentations/aggregation-framework-0]

Aggregation Concepts

MongoDB provides the three approaches to aggregation, each with its own strengths and purposes for a given situation. This section describes these approaches and also describes behaviors and limitations specific to each approach. See also the chart that compares the approaches.

Aggregation Pipeline

The aggregation pipeline is a framework for performing aggregation tasks, modeled on the concept of data processing pipelines. Using this framework, MongoDB passes the documents of a single collection through a pipeline. The pipeline transforms the documents into aggregated results, and is accessed through the aggregate database command.

Map-Reduce

Map-reduce is a generic multi-phase data aggregation modality for processing quantities of data. MongoDB provides map-reduce with the mapReduce database command.

Single Purpose Aggregation Operations

MongoDB provides a collection of specific data aggregation operations to support a number of common data aggregation functions. These operations include returning counts of documents, distinct values of a field, and simple grouping operations.

Aggregation Mechanics

Details internal optimization operations, limits, support for sharded collections, and concurrency concerns.

Aggregation Pipeline

Map-Reduce

Single Purpose Aggregation Operations

Aggregation Mechanics

Aggregation Pipeline Optimization

Aggregation Pipeline Limits

Aggregation Pipeline and Sharded Collections

Map-Reduce and Sharded Collections

Map Reduce Concurrency

Aggregation Pipeline

New in version 2.2.

The aggregation pipeline is a framework for data aggregation modeled on the concept of data processing pipelines. Documents enter a multi-stage pipeline that transforms the documents into an aggregated results.

The aggregation pipeline provides an alternative to map-reduce and may be the preferred solution for aggregation tasks where the complexity of map-reduce may be unwarranted.

Aggregation pipeline have some limitations on value types and result size. See Aggregation Pipeline Limits for details on limits and restrictions on the aggregation pipeline.

Pipeline

The MongoDB aggregation pipeline consists of stages. Each stage transforms the documents as they pass through the pipeline. Pipeline stages do not need to produce one output document for every input document; e.g., some stages may generate new documents or filter out documents. Pipeline stages can appear multiple times in the pipeline.

MongoDB provides the db.collection.aggregate() method in the mongo shell and the aggregate command for aggregation pipeline. See Stage Operators for the available stages.

For example usage of the aggregation pipeline, consider Aggregation with User Preference Data and Aggregation with the Zip Code Data Set.

Pipeline Expressions

Some pipeline stages takes a pipeline expression as its operand. Pipeline expressions specify the transformation to apply to the input documents. Expressions have a document structure and can contain other expression.

Pipeline expressions can only operate on the current document in the pipeline and cannot refer to data from other documents: expression operations provide in-memory transformation of documents.

Generally, expressions are stateless and are only evaluated when seen by the aggregation process with one exception: accumulator expressions.

The accumulators, used with the $group pipeline operator, maintain their state (e.g. totals, maximums, minimums, and related data) as documents progress through the pipeline.

For more information on expressions, see Expressions.

Aggregation Pipeline Behavior

In MongoDB, the aggregate command operates on a single collection, logically passing the entire collection into the aggregation pipeline. To optimize the operation, wherever possible, use the following strategies to avoid scanning the entire collection.

Pipeline Operators and Indexes

The $match and $sort pipeline operators can take advantage of an index when they occur at the beginning of the pipeline.

New in version 2.4: The $geoNear pipeline operator takes advantage of a geospatial index. When using $geoNear, the $geoNear pipeline operation must appear as the first stage in an aggregation pipeline.

Even when the pipeline uses an index, aggregation still requires access to the actual documents; i.e. indexes cannot fully cover an aggregation pipeline.

Changed in version 2.6: In previous versions, for very select use cases, an index could cover a pipeline.

Early Filtering

If your aggregation operation requires only a subset of the data in a collection, use the $match, $limit, and $skip stages to restrict the documents that enter at the beginning of the pipeline. When placed at the beginning of a pipeline, $match operations use suitable indexes to scan only the matching documents in a collection.

Placing a $match pipeline stage followed by a $sort stage at the start of the pipeline is logically equivalent to a single query with a sort and can use an index. When possible, place $match operators at the beginning of the pipeline.

Additional Features

The aggregation pipeline has an internal optimization phase that provides improved performance for certain sequences of operators. For details, see Aggregation Pipeline Optimization.

The aggregation pipeline supports operations on sharded collections. See Aggregation Pipeline and Sharded Collections.

Map-Reduce

Map-reduce is a data processing paradigm for condensing large volumes of data into useful aggregated results. For map-reduce operations, MongoDB provides the mapReduce database command.

Consider the following map-reduce operation:

In this map-reduce operation, MongoDB applies the map phase to each input document (i.e. the documents in the collection that match the query condition). The map function emits key-value pairs. For those keys that have multiple values, MongoDB applies the reduce phase, which collects and condenses the aggregated data. MongoDB then stores the results in a collection. Optionally, the output of the reduce function may pass through a finalize function to further condense or process the results of the aggregation.

All map-reduce functions in MongoDB are JavaScript and run within the mongod process. Map-reduce operations take the documents of a single collection as the input and can perform any arbitrary sorting and limiting before beginning the map stage. mapReduce can return the results of a map-reduce operation as a document, or may write the results to collections. The input and the output collections may be sharded.

Note

For most aggregation operations, the Aggregation Pipeline provides better performance and more coherent interface. However, map-reduce operations provide some flexibility that is not presently available in the aggregation pipeline.

Map-Reduce JavaScript Functions

In MongoDB, map-reduce operations use custom JavaScript functions to map, or associate, values to a key. If a key has multiple values mapped to it, the operation reduces the values for the key to a single object.

The use of custom JavaScript functions provide flexibility to map-reduce operations. For instance, when processing a document, the map function can create more than one key and value mapping or no mapping. Map-reduce operations can also use a custom JavaScript function to make final modifications to the results at the end of the map and reduce operation, such as perform additional calculations.

Map-Reduce Behavior

In MongoDB, the map-reduce operation can write results to a collection or return the results inline. If you write map-reduce output to a collection, you can perform subsequent map-reduce operations on the same input collection that merge replace, merge, or reduce new results with previous results. See mapReduce and Perform Incremental Map-Reduce for details and examples.

When returning the results of a map reduce operation inline, the result documents must be within the BSON Document Size limit, which is currently 16 megabytes. For additional information on limits and restrictions on map-reduce operations, see the mapReduce reference page.

MongoDB supports map-reduce operations on sharded collections. Map-reduce operations can also output the results to a sharded collection. See Map-Reduce and Sharded Collections.

Single Purpose Aggregation Operations

Aggregation refers to a broad class of data manipulation operations that compute a result based on an input and a specific procedure. MongoDB provides a number of aggregation operations that perform specific aggregation operations on a set of data.

Although limited in scope, particularly compared to the aggregation pipeline and map-reduce, these operations provide straightforward semantics for common data processing options.

Count

MongoDB can return a count of the number of documents that match a query. The count command as well as the count() and cursor.count() methods provide access to counts in the mongo shell.

Example

Given a collection named records with only the following documents:

{ a: 1, b: 0 }
{ a: 1, b: 1 }
{ a: 1, b: 4 }
{ a: 2, b: 2 }

The following operation would count all documents in the collection and return the number 4:

db.records.count()

The following operation will count only the documents where the value of the field a is 1 and return 3:

db.records.count( { a: 1 } )

Distinct

The distinct operation takes a number of documents that match a query and returns all of the unique values for a field in the matching documents. The distinct command and db.collection.distinct() method provide this operation in the mongo shell. Consider the following examples of a distinct operation:

Example

Given a collection named records with only the following documents:

{ a: 1, b: 0 }
{ a: 1, b: 1 }
{ a: 1, b: 1 }
{ a: 1, b: 4 }
{ a: 2, b: 2 }
{ a: 2, b: 2 }

Consider the following db.collection.distinct() operation which returns the distinct values of the field b:

db.records.distinct( "b" )

The results of this operation would resemble:

[ 0, 1, 4, 2 ]

Group

The group operation takes a number of documents that match a query, and then collects groups of documents based on the value of a field or fields. It returns an array of documents with computed results for each group of documents.

Access the grouping functionality via the group command or the db.collection.group() method in the mongo shell.

Warning

group does not support data in sharded collections. In addition, the results of the group operation must be no larger than 16 megabytes.

Consider the following group operation:

Example

Given a collection named records with the following documents:

{ a: 1, count: 4 }
{ a: 1, count: 2 }
{ a: 1, count: 4 }
{ a: 2, count: 3 }
{ a: 2, count: 1 }
{ a: 1, count: 5 }
{ a: 4, count: 4 }

Consider the following group operation which groups documents by the field a, where a is less than 3, and sums the field count for each group:

db.records.group( {
   key: { a: 1 },
   cond: { a: { $lt: 3 } },
   reduce: function(cur, result) { result.count += cur.count },
   initial: { count: 0 }
} )

The results of this group operation would resemble the following:

[
  { a: 1, count: 15 },
  { a: 2, count: 4 }
]

See also

The $group for related functionality in the aggregation pipeline.

Aggregation Mechanics

This section describes behaviors and limitations for the various aggregation modalities.

Aggregation Pipeline Optimization

Details the internal optimization of certain pipeline sequence.

Aggregation Pipeline Limits

Presents limitations on aggregation pipeline operations.

Aggregation Pipeline and Sharded Collections

Mechanics of aggregation pipeline operations on sharded collections.

Map-Reduce and Sharded Collections

Mechanics of map-reduce operation with sharded collections.

Map Reduce Concurrency

Details the locks taken during map-reduce operations.

Aggregation Pipeline Optimization

Aggregation Pipeline Limits

Aggregation Pipeline and Sharded Collections

Map-Reduce and Sharded Collections

Map Reduce Concurrency

Aggregation Pipeline Optimization

Aggregation pipeline operations have an optimization phase which attempts to reshape the pipeline for improved performance.

To see how the optimizer transforms a particular aggregation pipeline, include the explain option in the db.collection.aggregate() method.

Optimizations are subject to change between releases.

Projection Optimization

The aggregation pipeline can determine if it requires only a subset of the fields in the documents to obtain the results. If so, the pipeline will only use those required fields, reducing the amount of data passing through the pipeline.

Pipeline Sequence Optimization

$sort + $match Sequence Optimization

When you have a sequence with $sort followed by a $match, the $match moves before the $sort to minimize the number of objects to sort. For example, if the pipeline consists of the following stages:

{ $sort: { age : -1 } },
{ $match: { status: 'A' } }

During the optimization phase, the optimizer transforms the sequence to the following:

{ $match: { status: 'A' } },
{ $sort: { age : -1 } }

$skip + $limit Sequence Optimization

When you have a sequence with $skip followed by a $limit, the $limit moves before the $skip. With the reordering, the $limit value increases by the $skip amount.

For example, if the pipeline consists of the following stages:

{ $skip: 10 },
{ $limit: 5 }

During the optimization phase, the optimizer transforms the sequence to the following:

{ $limit: 15 },
{ $skip: 10 }

This optimization allows for more opportunities for $sort + $limit Coalescence, such as with $sort + $skip + $limit sequences. See $sort + $limit Coalescence for details on the coalescence and $sort + $skip + $limit Sequence for an example.

For aggregation operations on sharded collections, this optimization reduces the results returned from each shard.

$redact + $match Sequence Optimization

When possible, when the pipeline has the $redact stage immediately followed by the $match stage, the aggregation can sometimes add a portion of the $match stage before the $redact stage. If the added $match stage is at the start of a pipeline, the aggregation can use an index as well as query the collection to limit the number of documents that enter the pipeline. See Pipeline Operators and Indexes for more information.

For example, if the pipeline consists of the following stages:

{ $redact: { $cond: { if: { $eq: [ "$level", 5 ] }, then: "$$PRUNE", else: "$$DESCEND" } } },
{ $match: { year: 2014, category: { $ne: "Z" } } }

The optimizer can add the same $match stage before the $redact stage:

{ $match: { year: 2014 } },
{ $redact: { $cond: { if: { $eq: [ "$level", 5 ] }, then: "$$PRUNE", else: "$$DESCEND" } } },
{ $match: { year: 2014, category: { $ne: "Z" } } }

Pipeline Coalescence Optimization

When possible, the optimization phase coalesces a pipeline stage into its predecessor. Generally, coalescence occurs after any sequence reordering optimization.

$sort + $limit Coalescence

When a $sort immediately precedes a $limit, the optimizer can coalesce the $limit into the $sort. This allows the sort operation to only maintain the top n results as it progresses, where n is the specified limit, and MongoDB only needs to store n items in memory [1]. See $sort Operator and Memory for more information.

[1]
The optimization will still apply when allowDiskUse is true and the n items exceed the aggregation memory limit.

$limit + $limit Coalescence

When a $limit immediately follows another $limit, the two stages can coalesce into a single $limit where the limit amount is the smaller of the two initial limit amounts. For example, a pipeline contains the following sequence:

{ $limit: 100 },
{ $limit: 10 }

Then the second $limit stage can coalesce into the first $limit stage and result in a single $limit stage where the limit amount 10 is the minimum of the two initial limits 100 and 10.

{ $limit: 10 }

$skip + $skip Coalescence

When a $skip immediately follows another $skip, the two stages can coalesce into a single $skip where the skip amount is the sum of the two initial skip amounts. For example, a pipeline contains the following sequence:

{ $skip: 5 },
{ $skip: 2 }

Then the second $skip stage can coalesce into the first $skip stage and result in a single $skip stage where the skip amount 7 is the sum of the two initial limits 5 and 2.

{ $skip: 7 }

$match + $match Coalescence

When a $match immediately follows another $match, the two stages can coalesce into a single $match combining the conditions with an $and. For example, a pipeline contains the following sequence:

{ $match: { year: 2014 } },
{ $match: { status: "A" } }

Then the second $match stage can coalesce into the first $match stage and result in a single $match stage

{ $match: { $and: [ { "year" : 2014 }, { "status" : "A" } ] } }

Examples

The following examples are some sequences that can take advantage of both sequence reordering and coalescence. Generally, coalescence occurs after any sequence reordering optimization.

$sort + $skip + $limit Sequence

A pipeline contains a sequence of $sort followed by a $skip followed by a $limit:

{ $sort: { age : -1 } },
{ $skip: 10 },
{ $limit: 5 }

First, the optimizer performs the $skip + $limit Sequence Optimization to transforms the sequence to the following:

{ $sort: { age : -1 } },
{ $limit: 15 }
{ $skip: 10 }

The $skip + $limit Sequence Optimization increases the $limit amount with the reordering. See $skip + $limit Sequence Optimization for details.

The reordered sequence now has $sort immediately preceding the $limit, and the pipeline can coalesce the two stages to decrease memory usage during the sort operation. See $sort + $limit Coalescence for more information.

$limit + $skip + $limit + $skip Sequence

A pipeline contains a sequence of alternating $limit and $skip stages:

{ $limit: 100 },
{ $skip: 5 },
{ $limit: 10 },
{ $skip: 2 }

The $skip + $limit Sequence Optimization reverses the position of the { $skip: 5 } and { $limit: 10 } stages and increases the limit amount:

{ $limit: 100 },
{ $limit: 15},
{ $skip: 5 },
{ $skip: 2 }

The optimizer then coalesces the two $limit stages into a single $limit stage and the two $skip stages into a single $skip stage. The resulting sequence is the following:

{ $limit: 15 },
{ $skip: 7 }

See $limit + $limit Coalescence and $skip + $skip Coalescence for details.

See also

explain option in the db.collection.aggregate()

Aggregation Pipeline Limits

Aggregation operations with the aggregate command have the following limitations.

Result Size Restrictions

If the aggregate command returns a single document that contains the complete result set, the command will produce an error if the result set exceeds the BSON Document Size limit, which is currently 16 megabytes. To manage result sets that exceed this limit, the aggregate command can return result sets of any size if the command return a cursor or store the results to a collection.

Changed in version 2.6: The aggregate command can return results as a cursor or store the results in a collection, which are not subject to the size limit. The db.collection.aggregate() returns a cursor and can return result sets of any size.

Memory Restrictions

Changed in version 2.6.

Pipeline stages have a limit of 100 megabytes of RAM. If a stage exceeds this limit, MongoDB will produce an error. To allow for the handling of large datasets, use the allowDiskUse option to enable aggregation pipeline stages to write data to temporary files.

See also

$sort and Memory Restrictions and $group Operator and Memory.

Aggregation Pipeline and Sharded Collections

The aggregation pipeline supports operations on sharded collections. This section describes behaviors specific to the aggregation pipeline and sharded collections.

Behavior

Changed in version 2.6.

When operating on a sharded collection, the aggregation pipeline is split into two parts. The first pipeline runs on each shard, or if an early $match can exclude shards through the use of the shard key in the predicate, the pipeline runs on only the relevant shards.

The second pipeline consists of the remaining pipeline stages and runs on the primary shard. The primary shard merges the cursors from the other shards and runs the second pipeline on these results. The primary shard forwards the final results to the mongos. In previous versions, the second pipeline would run on the mongos. [1]

Optimization

When splitting the aggregation pipeline into two parts, the pipeline is split to ensure that the shards perform as many stages as possible with consideration for optimization.

To see how the pipeline was split, include the explain option in the db.collection.aggregate() method.

Optimizations are subject to change between releases.

[1]
Until all shards upgrade to v2.6, the second pipeline runs on the mongos if any shards are still running v2.4.

Map-Reduce and Sharded Collections

Map-reduce supports operations on sharded collections, both as an input and as an output. This section describes the behaviors of mapReduce specific to sharded collections.

Sharded Collection as Input

When using sharded collection as the input for a map-reduce operation, mongos will automatically dispatch the map-reduce job to each shard in parallel. There is no special option required. mongos will wait for jobs on all shards to finish.

Sharded Collection as Output

Changed in version 2.2.

If the out field for mapReduce has the sharded value, MongoDB shards the output collection using the _id field as the shard key.

To output to a sharded collection:

If the output collection does not exist, MongoDB creates and shards the collection on the _id field.

For a new or an empty sharded collection, MongoDB uses the results of the first stage of the map-reduce operation to create the initial chunks distributed among the shards.

mongos dispatches, in parallel, a map-reduce post-processing job to every shard that owns a chunk. During the post-processing, each shard will pull the results for its own chunks from the other shards, run the final reduce/finalize, and write locally to the output collection.

Note

During later map-reduce jobs, MongoDB splits chunks as needed.

Balancing of chunks for the output collection is automatically prevented during post-processing to avoid concurrency issues.

In MongoDB 2.0:

mongos retrieves the results from each shard, performs a merge sort to order the results, and proceeds to the reduce/finalize phase as needed. mongos then writes the result to the output collection in sharded mode.

This model requires only a small amount of memory, even for large data sets.

Shard chunks are not automatically split during insertion. This requires manual intervention until the chunks are granular and balanced.

Important

For best results, only use the sharded output options for mapReduce in version 2.2 or later.

Map Reduce Concurrency

The map-reduce operation is composed of many tasks, including reads from the input collection, executions of the map function, executions of the reduce function, writes to a temporary collection during processing, and writes to the output collection.

During the operation, map-reduce takes the following locks:

The read phase takes a read lock. It yields every 100 documents.

The insert into the temporary collection takes a write lock for a single write.

If the output collection does not exist, the creation of the output collection takes a write lock.

If the output collection exists, then the output actions (i.e. merge, replace, reduce) take a write lock. This write lock is global, and blocks all operations on the mongod instance.

Changed in version 2.4: The V8 JavaScript engine, which became the default in 2.4, allows multiple JavaScript operations to execute at the same time. Prior to 2.4, JavaScript code (i.e. map, reduce, finalize functions) executed in a single thread.

Note

The final write lock during post-processing makes the results appear atomically. However, output actions merge and reduce may take minutes to process. For the merge and reduce, the nonAtomic flag is available, which releases the lock between writing each output document. See the db.collection.mapReduce() reference for more information.

Aggregation Examples

This document provides the practical examples that display the capabilities of aggregation.

Aggregation with the Zip Code Data Set

Use the aggregation pipeline to group values and to calculate aggregated sums and averages for a collection of United States zip codes.

Aggregation with User Preference Data

Use the pipeline to sort, normalize, and sum data on a collection of user data.

Map-Reduce Examples

Define map-reduce operations that select ranges, group data, and calculate sums and averages.

Perform Incremental Map-Reduce

Run a map-reduce operations over one collection and output results to another collection.

Troubleshoot the Map Function

Steps to troubleshoot the map function.

Troubleshoot the Reduce Function

Steps to troubleshoot the reduce function.

Aggregation with the Zip Code Data Set

Aggregation with User Preference Data

Map-Reduce Examples

Perform Incremental Map-Reduce

Troubleshoot the Map Function

Troubleshoot the Reduce Function

Aggregation with the Zip Code Data Set

The examples in this document use the zipcodes collection. This collection is available at: media.mongodb.org/zips.json [http://media.mongodb.org/zips.json]. Use mongoimport to load this data set into your mongod instance.

Data Model

Each document in the zipcodes collection has the following form:

{
  "_id": "10280",
  "city": "NEW YORK",
  "state": "NY",
  "pop": 5574,
  "loc": [
    -74.016323,
    40.710537
  ]
}

The _id field holds the zip code as a string.

The city field holds the city name. A city can have more than one zip code associated with it as different sections of the city can each have a different zip code.

The state field holds the two letter state abbreviation.

The pop field holds the population.

The loc field holds the location as a latitude longitude pair.

aggregate() Method

All of the following examples use the aggregate() helper in the mongo shell.

The aggregate() method uses the aggregation pipeline to processes documents into aggregated results. An aggregation pipeline consists of stages with each stage processing the documents as they pass along the pipeline. Documents pass through the stages in sequence.

The aggregate() method in the mongo shell provides a wrapper around the aggregate database command. See the documentation for your driver for a more idiomatic interface for data aggregation operations.

Return States with Populations above 10 Million

The following aggregation operation returns all states with total population greater than 10 million:

db.zipcodes.aggregate( [
   { $group: { _id: "$state", totalPop: { $sum: "$pop" } } },
   { $match: { totalPop: { $gte: 10*1000*1000 } } }
] )

In this example, the aggregation pipeline consists of the $group stage followed by the $match stage:

The $group stage groups the documents of the zipcode collection by the state field, calculates the totalPop field for each state, and outputs a document for each unique state.

The new per-state documents have two fields: the _id field and the totalPop field. The _id field contains the value of the state; i.e. the group by field. The totalPop field is a calculated field that contains the total population of each state. To calculate the value, $group uses the $sum operator to add the population field (pop) for each state.

After the $group stage, the documents in the pipeline resemble the following:

{
  "_id" : "AK",
  "totalPop" : 550043
}

The $match stage filters these grouped documents to output only those documents whose totalPop value is greater than or equal to 10 million. The $match stage does not alter the matching documents but outputs the matching documents unmodified.

The equivalent SQL for this aggregation operation is:

SELECT state, SUM(pop) AS totalPop
FROM zipcodes
GROUP BY state
HAVING totalPop >= (10*1000*1000)

See also

$group, $match, $sum

Return Average City Population by State

The following aggregation operation returns the average populations for cities in each state:

db.zipcodes.aggregate( [
   { $group: { _id: { state: "$state", city: "$city" }, pop: { $sum: "$pop" } } },
   { $group: { _id: "$_id.state", avgCityPop: { $avg: "$pop" } } }
] )

In this example, the aggregation pipeline consists of the $group stage followed by another $group stage:

The first $group stage groups the documents by the combination of city and state, uses the $sum expression to calculate the population for each combination, and outputs a document for each city and state combination. [1]

After this stage in the pipeline, the documents resemble the following:

{
  "_id" : {
    "state" : "CO",
    "city" : "EDGEWATER"
  },
  "pop" : 13154
}

A second $group stage groups the documents in the pipeline by the _id.state field (i.e. the state field inside the _id document), uses the $avg expression to calculate the average city population (avgCityPop) for each state, and outputs a document for each state.

The documents that result from this aggregation operation resembles the following:

{
  "_id" : "MN",
  "avgCityPop" : 5335
}

See also

$group, $sum, $avg

Return Largest and Smallest Cities by State

The following aggregation operation returns the smallest and largest cities by population for each state:

db.zipcodes.aggregate( [
   { $group:
      {
        _id: { state: "$state", city: "$city" },
        pop: { $sum: "$pop" }
      }
   },
   { $sort: { pop: 1 } },
   { $group:
      {
        _id : "$_id.state",
        biggestCity:  { $last: "$_id.city" },
        biggestPop:   { $last: "$pop" },
        smallestCity: { $first: "$_id.city" },
        smallestPop:  { $first: "$pop" }
      }
   },

  // the following $project is optional, and
  // modifies the output format.

  { $project:
    { _id: 0,
      state: "$_id",
      biggestCity:  { name: "$biggestCity",  pop: "$biggestPop" },
      smallestCity: { name: "$smallestCity", pop: "$smallestPop" }
    }
  }
] )

In this example, the aggregation pipeline consists of a $group stage, a $sort stage, another $group stage, and a $project stage:

The first $group stage groups the documents by the combination of the city and state, calculates the sum of the pop values for each combination, and outputs a document for each city and state combination.

At this stage in the pipeline, the documents resemble the following:

{
  "_id" : {
    "state" : "CO",
    "city" : "EDGEWATER"
  },
  "pop" : 13154
}

The $sort stage orders the documents in the pipeline by the pop field value, from smallest to largest; i.e. by increasing order. This operation does not alter the documents.

The next $group stage groups the now-sorted documents by the _id.state field (i.e. the state field inside the _id document) and outputs a document for each state.

The stage also calculates the following four fields for each state. Using the $last expression, the $group operator creates the biggestCity and biggestPop fields that store the city with the largest population and that population. Using the $first expression, the $group operator creates the smallestCity and smallestPop fields that store the city with the smallest population and that population.

The documents, at this stage in the pipeline, resemble the following:

{
  "_id" : "WA",
  "biggestCity" : "SEATTLE",
  "biggestPop" : 520096,
  "smallestCity" : "BENGE",
  "smallestPop" : 2
}

The final $project stage renames the _id field to state and moves the biggestCity, biggestPop, smallestCity, and smallestPop into biggestCity and smallestCity embedded documents.

The output documents of this aggregation operation resemble the following:

{
  "state" : "RI",
  "biggestCity" : {
    "name" : "CRANSTON",
    "pop" : 176404
  },
  "smallestCity" : {
    "name" : "CLAYVILLE",
    "pop" : 45
  }
}

[1]
A city can have more than one zip code associated with it as different sections of the city can each have a different zip code.

Aggregation with User Preference Data

Data Model

Consider a hypothetical sports club with a database that contains a users collection that tracks the user’s join dates, sport preferences, and stores these data in documents that resemble the following:

{
  _id : "jane",
  joined : ISODate("2011-03-02"),
  likes : ["golf", "racquetball"]
}
{
  _id : "joe",
  joined : ISODate("2012-07-02"),
  likes : ["tennis", "golf", "swimming"]
}

Normalize and Sort Documents

The following operation returns user names in upper case and in alphabetical order. The aggregation includes user names for all documents in the users collection. You might do this to normalize user names for processing.

db.users.aggregate(
  [
    { $project : { name:{$toUpper:"$_id"} , _id:0 } },
    { $sort : { name : 1 } }
  ]
)

All documents from the users collection pass through the pipeline, which consists of the following operations:

The $project operator:

creates a new field called name.

converts the value of the _id to upper case, with the $toUpper operator. Then the $project creates a new field, named name to hold this value.

suppresses the id field. $project will pass the _id field by default, unless explicitly suppressed.

The $sort operator orders the results by the name field.

The results of the aggregation would resemble the following:

{
  "name" : "JANE"
},
{
  "name" : "JILL"
},
{
  "name" : "JOE"
}

Return Usernames Ordered by Join Month

The following aggregation operation returns user names sorted by the month they joined. This kind of aggregation could help generate membership renewal notices.

db.users.aggregate(
  [
    { $project :
       {
         month_joined : { $month : "$joined" },
         name : "$_id",
         _id : 0
       }
    },
    { $sort : { month_joined : 1 } }
  ]
)

The pipeline passes all documents in the users collection through the following operations:

The $project operator:

Creates two new fields: month_joined and name.

Suppresses the id from the results. The aggregate() method includes the _id, unless explicitly suppressed.

The $month operator converts the values of the joined field to integer representations of the month. Then the $project operator assigns those values to the month_joined field.

The $sort operator sorts the results by the month_joined field.

The operation returns results that resemble the following:

{
  "month_joined" : 1,
  "name" : "ruth"
},
{
  "month_joined" : 1,
  "name" : "harold"
},
{
  "month_joined" : 1,
  "name" : "kate"
}
{
  "month_joined" : 2,
  "name" : "jill"
}

Return Total Number of Joins per Month

The following operation shows how many people joined each month of the year. You might use this aggregated data for recruiting and marketing strategies.

db.users.aggregate(
  [
    { $project : { month_joined : { $month : "$joined" } } } ,
    { $group : { _id : {month_joined:"$month_joined"} , number : { $sum : 1 } } },
    { $sort : { "_id.month_joined" : 1 } }
  ]
)

The pipeline passes all documents in the users collection through the following operations:

The $project operator creates a new field called month_joined.

The $month operator converts the values of the joined field to integer representations of the month. Then the $project operator assigns the values to the month_joined field.

The $group operator collects all documents with a given month_joined value and counts how many documents there are for that value. Specifically, for each unique value, $group creates a new “per-month” document with two fields:

_id, which contains a nested document with the month_joined field and its value.

number, which is a generated field. The $sum operator increments this field by 1 for every document containing the given month_joined value.

The $sort operator sorts the documents created by $group according to the contents of the month_joined field.

The result of this aggregation operation would resemble the following:

{
  "_id" : {
    "month_joined" : 1
  },
  "number" : 3
},
{
  "_id" : {
    "month_joined" : 2
  },
  "number" : 9
},
{
  "_id" : {
    "month_joined" : 3
  },
  "number" : 5
}

Return the Five Most Common “Likes”

The following aggregation collects top five most “liked” activities in the data set. This type of analysis could help inform planning and future development.

db.users.aggregate(
  [
    { $unwind : "$likes" },
    { $group : { _id : "$likes" , number : { $sum : 1 } } },
    { $sort : { number : -1 } },
    { $limit : 5 }
  ]
)

The pipeline begins with all documents in the users collection, and passes these documents through the following operations:

The $unwind operator separates each value in the likes array, and creates a new version of the source document for every element in the array.

Example

Given the following document from the users collection:

{
  _id : "jane",
  joined : ISODate("2011-03-02"),
  likes : ["golf", "racquetball"]
}

The $unwind operator would create the following documents:

{
  _id : "jane",
  joined : ISODate("2011-03-02"),
  likes : "golf"
}
{
  _id : "jane",
  joined : ISODate("2011-03-02"),
  likes : "racquetball"
}

The $group operator collects all documents the same value for the likes field and counts each grouping. With this information, $group creates a new document with two fields:

_id, which contains the likes value.

number, which is a generated field. The $sum operator increments this field by 1 for every document containing the given likes value.

The $sort operator sorts these documents by the number field in reverse order.

The $limit operator only includes the first 5 result documents.

The results of aggregation would resemble the following:

{
  "_id" : "golf",
  "number" : 33
},
{
  "_id" : "racquetball",
  "number" : 31
},
{
  "_id" : "swimming",
  "number" : 24
},
{
  "_id" : "handball",
  "number" : 19
},
{
  "_id" : "tennis",
  "number" : 18
}

Map-Reduce Examples

In the mongo shell, the db.collection.mapReduce() method is a wrapper around the mapReduce command. The following examples use the db.collection.mapReduce() method:

Consider the following map-reduce operations on a collection orders that contains documents of the following prototype:

{
     _id: ObjectId("50a8240b927d5d8b5891743c"),
     cust_id: "abc123",
     ord_date: new Date("Oct 04, 2012"),
     status: 'A',
     price: 25,
     items: [ { sku: "mmm", qty: 5, price: 2.5 },
              { sku: "nnn", qty: 5, price: 2.5 } ]
}

Return the Total Price Per Customer

Perform the map-reduce operation on the orders collection to group by the cust_id, and calculate the sum of the price for each cust_id:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

The function maps the price to the cust_id for each document and emits the cust_id and price pair.

var mapFunction1 = function() {
                       emit(this.cust_id, this.price);
                   };

Define the corresponding reduce function with two arguments keyCustId and valuesPrices:

The valuesPrices is an array whose elements are the price values emitted by the map function and grouped by keyCustId.

The function reduces the valuesPrice array to the sum of its elements.

var reduceFunction1 = function(keyCustId, valuesPrices) {
                          return Array.sum(valuesPrices);
                      };

Perform the map-reduce on all documents in the orders collection using the mapFunction1 map function and the reduceFunction1 reduce function.

db.orders.mapReduce(
                     mapFunction1,
                     reduceFunction1,
                     { out: "map_reduce_example" }
                   )

This operation outputs the results to a collection named map_reduce_example. If the map_reduce_example collection already exists, the operation will replace the contents with the results of this map-reduce operation:

Calculate Order and Total Quantity with Average Quantity Per Item

In this example, you will perform a map-reduce operation on the orders collection for all documents that have an ord_date value greater than 01/01/2012. The operation groups by the item.sku field, and calculates the number of orders and the total quantity ordered for each sku. The operation concludes by calculating the average quantity per order for each sku value:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

For each item, the function associates the sku with a new object value that contains the count of 1 and the item qty for the order and emits the sku and value pair.

var mapFunction2 = function() {
                       for (var idx = 0; idx < this.items.length; idx++) {
                           var key = this.items[idx].sku;
                           var value = {
                                         count: 1,
                                         qty: this.items[idx].qty
                                       };
                           emit(key, value);
                       }
                    };

Define the corresponding reduce function with two arguments keySKU and countObjVals:

countObjVals is an array whose elements are the objects mapped to the grouped keySKU values passed by map function to the reducer function.

The function reduces the countObjVals array to a single object reducedValue that contains the count and the qty fields.

In reducedVal, the count field contains the sum of the count fields from the individual array elements, and the qty field contains the sum of the qty fields from the individual array elements.

var reduceFunction2 = function(keySKU, countObjVals) {
                     reducedVal = { count: 0, qty: 0 };

                     for (var idx = 0; idx < countObjVals.length; idx++) {
                         reducedVal.count += countObjVals[idx].count;
                         reducedVal.qty += countObjVals[idx].qty;
                     }

                     return reducedVal;
                  };

Define a finalize function with two arguments key and reducedVal. The function modifies the reducedVal object to add a computed field named avg and returns the modified object:

var finalizeFunction2 = function (key, reducedVal) {

                       reducedVal.avg = reducedVal.qty/reducedVal.count;

                       return reducedVal;

                    };

Perform the map-reduce operation on the orders collection using the mapFunction2, reduceFunction2, and finalizeFunction2 functions.

db.orders.mapReduce( mapFunction2,
                     reduceFunction2,
                     {
                       out: { merge: "map_reduce_example" },
                       query: { ord_date:
                                  { $gt: new Date('01/01/2012') }
                              },
                       finalize: finalizeFunction2
                     }
                   )

This operation uses the query field to select only those documents with ord_date greater than new Date(01/01/2012). Then it output the results to a collection map_reduce_example. If the map_reduce_example collection already exists, the operation will merge the existing contents with the results of this map-reduce operation.

Perform Incremental Map-Reduce

Map-reduce operations can handle complex aggregation tasks. To perform map-reduce operations, MongoDB provides the mapReduce command and, in the mongo shell, the db.collection.mapReduce() wrapper method.

If the map-reduce data set is constantly growing, you may want to perform an incremental map-reduce rather than performing the map-reduce operation over the entire data set each time.

To perform incremental map-reduce:

Run a map-reduce job over the current collection and output the result to a separate collection.

When you have more data to process, run subsequent map-reduce job with:

the query parameter that specifies conditions that match only the new documents.

the out parameter that specifies the reduce action to merge the new results into the existing output collection.

Consider the following example where you schedule a map-reduce operation on a sessions collection to run at the end of each day.

Data Setup

The sessions collection contains documents that log users’ sessions each day, for example:

db.sessions.save( { userid: "a", ts: ISODate('2011-11-03 14:17:00'), length: 95 } );
db.sessions.save( { userid: "b", ts: ISODate('2011-11-03 14:23:00'), length: 110 } );
db.sessions.save( { userid: "c", ts: ISODate('2011-11-03 15:02:00'), length: 120 } );
db.sessions.save( { userid: "d", ts: ISODate('2011-11-03 16:45:00'), length: 45 } );

db.sessions.save( { userid: "a", ts: ISODate('2011-11-04 11:05:00'), length: 105 } );
db.sessions.save( { userid: "b", ts: ISODate('2011-11-04 13:14:00'), length: 120 } );
db.sessions.save( { userid: "c", ts: ISODate('2011-11-04 17:00:00'), length: 130 } );
db.sessions.save( { userid: "d", ts: ISODate('2011-11-04 15:37:00'), length: 65 } );

Initial Map-Reduce of Current Collection

Run the first map-reduce operation as follows:

Define the map function that maps the userid to an object that contains the fields userid, total_time, count, and avg_time:

var mapFunction = function() {
                      var key = this.userid;
                      var value = {
                                    userid: this.userid,
                                    total_time: this.length,
                                    count: 1,
                                    avg_time: 0
                                   };

                      emit( key, value );
                  };

Define the corresponding reduce function with two arguments key and values to calculate the total time and the count. The key corresponds to the userid, and the values is an array whose elements corresponds to the individual objects mapped to the userid in the mapFunction.

var reduceFunction = function(key, values) {

                        var reducedObject = {
                                              userid: key,
                                              total_time: 0,
                                              count:0,
                                              avg_time:0
                                            };

                        values.forEach( function(value) {
                                              reducedObject.total_time += value.total_time;
                                              reducedObject.count += value.count;
                                        }
                                      );
                        return reducedObject;
                     };

Define the finalize function with two arguments key and reducedValue. The function modifies the reducedValue document to add another field average and returns the modified document.

var finalizeFunction = function (key, reducedValue) {

                          if (reducedValue.count > 0)
                              reducedValue.avg_time = reducedValue.total_time / reducedValue.count;

                          return reducedValue;
                       };

Perform map-reduce on the session collection using the mapFunction, the reduceFunction, and the finalizeFunction functions. Output the results to a collection session_stat. If the session_stat collection already exists, the operation will replace the contents:

db.sessions.mapReduce( mapFunction,
                       reduceFunction,
                       {
                         out: "session_stat",
                         finalize: finalizeFunction
                       }
                     )

Subsequent Incremental Map-Reduce

Later, as the sessions collection grows, you can run additional map-reduce operations. For example, add new documents to the sessions collection:

db.sessions.save( { userid: "a", ts: ISODate('2011-11-05 14:17:00'), length: 100 } );
db.sessions.save( { userid: "b", ts: ISODate('2011-11-05 14:23:00'), length: 115 } );
db.sessions.save( { userid: "c", ts: ISODate('2011-11-05 15:02:00'), length: 125 } );
db.sessions.save( { userid: "d", ts: ISODate('2011-11-05 16:45:00'), length: 55 } );

At the end of the day, perform incremental map-reduce on the sessions collection, but use the query field to select only the new documents. Output the results to the collection session_stat, but reduce the contents with the results of the incremental map-reduce:

db.sessions.mapReduce( mapFunction,
                       reduceFunction,
                       {
                         query: { ts: { $gt: ISODate('2011-11-05 00:00:00') } },
                         out: { reduce: "session_stat" },
                         finalize: finalizeFunction
                       }
                     );

Troubleshoot the Map Function

The map function is a JavaScript function that associates or “maps” a value with a key and emits the key and value pair during a map-reduce operation.

To verify the key and value pairs emitted by the map function, write your own emit function.

Consider a collection orders that contains documents of the following prototype:

{
     _id: ObjectId("50a8240b927d5d8b5891743c"),
     cust_id: "abc123",
     ord_date: new Date("Oct 04, 2012"),
     status: 'A',
     price: 250,
     items: [ { sku: "mmm", qty: 5, price: 2.5 },
              { sku: "nnn", qty: 5, price: 2.5 } ]
}

Define the map function that maps the price to the cust_id for each document and emits the cust_id and price pair:

var map = function() {
    emit(this.cust_id, this.price);
};

Define the emit function to print the key and value:

var emit = function(key, value) {
    print("emit");
    print("key: " + key + "  value: " + tojson(value));
}

Invoke the map function with a single document from the orders collection:

var myDoc = db.orders.findOne( { _id: ObjectId("50a8240b927d5d8b5891743c") } );
map.apply(myDoc);

Verify the key and value pair is as you expected.

emit
key: abc123 value:250

Invoke the map function with multiple documents from the orders collection:

var myCursor = db.orders.find( { cust_id: "abc123" } );

while (myCursor.hasNext()) {
    var doc = myCursor.next();
    print ("document _id= " + tojson(doc._id));
    map.apply(doc);
    print();
}

Verify the key and value pairs are as you expected.

See also

The map function must meet various requirements. For a list of all the requirements for the map function, see mapReduce, or the mongo shell helper method db.collection.mapReduce().

Troubleshoot the Reduce Function

The reduce function is a JavaScript function that “reduces” to a single object all the values associated with a particular key during a map-reduce operation. The reduce function must meet various requirements. This tutorial helps verify that the reduce function meets the following criteria:

The reduce function must return an object whose type must be identical to the type of the value emitted by the map function.

The order of the elements in the valuesArray should not affect the output of the reduce function.

The reduce function must be idempotent.

For a list of all the requirements for the reduce function, see mapReduce, or the mongo shell helper method db.collection.mapReduce().

Confirm Output Type

You can test that the reduce function returns a value that is the same type as the value emitted from the map function.

Define a reduceFunction1 function that takes the arguments keyCustId and valuesPrices. valuesPrices is an array of integers:

var reduceFunction1 = function(keyCustId, valuesPrices) {
                          return Array.sum(valuesPrices);
                      };

Define a sample array of integers:

var myTestValues = [ 5, 5, 10 ];

Invoke the reduceFunction1 with myTestValues:

reduceFunction1('myKey', myTestValues);

Verify the reduceFunction1 returned an integer:

20

Define a reduceFunction2 function that takes the arguments keySKU and valuesCountObjects. valuesCountObjects is an array of documents that contain two fields count and qty:

var reduceFunction2 = function(keySKU, valuesCountObjects) {
                          reducedValue = { count: 0, qty: 0 };

                          for (var idx = 0; idx < valuesCountObjects.length; idx++) {
                              reducedValue.count += valuesCountObjects[idx].count;
                              reducedValue.qty += valuesCountObjects[idx].qty;
                          }

                          return reducedValue;
                      };

Define a sample array of documents:

var myTestObjects = [
                      { count: 1, qty: 5 },
                      { count: 2, qty: 10 },
                      { count: 3, qty: 15 }
                    ];

Invoke the reduceFunction2 with myTestObjects:

reduceFunction2('myKey', myTestObjects);

Verify the reduceFunction2 returned a document with exactly the count and the qty field:

{ "count" : 6, "qty" : 30 }

Ensure Insensitivity to the Order of Mapped Values

The reduce function takes a key and a values array as its argument. You can test that the result of the reduce function does not depend on the order of the elements in the values array.

Define a sample values1 array and a sample values2 array that only differ in the order of the array elements:

var values1 = [
                { count: 1, qty: 5 },
                { count: 2, qty: 10 },
                { count: 3, qty: 15 }
              ];

var values2 = [
                { count: 3, qty: 15 },
                { count: 1, qty: 5 },
                { count: 2, qty: 10 }
              ];

Define a reduceFunction2 function that takes the arguments keySKU and valuesCountObjects. valuesCountObjects is an array of documents that contain two fields count and qty:

var reduceFunction2 = function(keySKU, valuesCountObjects) {
                          reducedValue = { count: 0, qty: 0 };

                          for (var idx = 0; idx < valuesCountObjects.length; idx++) {
                              reducedValue.count += valuesCountObjects[idx].count;
                              reducedValue.qty += valuesCountObjects[idx].qty;
                          }

                          return reducedValue;
                      };

Invoke the reduceFunction2 first with values1 and then with values2:

reduceFunction2('myKey', values1);
reduceFunction2('myKey', values2);

Verify the reduceFunction2 returned the same result:

{ "count" : 6, "qty" : 30 }

Ensure Reduce Function Idempotence

Because the map-reduce operation may call a reduce multiple times for the same key, and won’t call a reduce for single instances of a key in the working set, the reduce function must return a value of the same type as the value emitted from the map function. You can test that the reduce function process “reduced” values without affecting the final value.

Define a reduceFunction2 function that takes the arguments keySKU and valuesCountObjects. valuesCountObjects is an array of documents that contain two fields count and qty:

var reduceFunction2 = function(keySKU, valuesCountObjects) {
                          reducedValue = { count: 0, qty: 0 };

                          for (var idx = 0; idx < valuesCountObjects.length; idx++) {
                              reducedValue.count += valuesCountObjects[idx].count;
                              reducedValue.qty += valuesCountObjects[idx].qty;
                          }

                          return reducedValue;
                      };

Define a sample key:

var myKey = 'myKey';

Define a sample valuesIdempotent array that contains an element that is a call to the reduceFunction2 function:

var valuesIdempotent = [
                         { count: 1, qty: 5 },
                         { count: 2, qty: 10 },
                         reduceFunction2(myKey, [ { count:3, qty: 15 } ] )
                       ];

Define a sample values1 array that combines the values passed to reduceFunction2:

var values1 = [
                { count: 1, qty: 5 },
                { count: 2, qty: 10 },
                { count: 3, qty: 15 }
              ];

Invoke the reduceFunction2 first with myKey and valuesIdempotent and then with myKey and values1:

reduceFunction2(myKey, valuesIdempotent);
reduceFunction2(myKey, values1);

Verify the reduceFunction2 returned the same result:

{ "count" : 6, "qty" : 30 }

Aggregation Reference

Aggregation Pipeline Quick Reference

Quick reference card for aggregation pipeline.

Aggregation Pipeline Operators

Aggregation pipeline operations have a collection of operators available to define and manipulate documents in pipeline stages.

Aggregation Commands Comparison

A comparison of group, mapReduce and aggregate that explores the strengths and limitations of each aggregation modality.

SQL to Aggregation Mapping Chart

An overview common aggregation operations in SQL and MongoDB using the aggregation pipeline and operators in MongoDB and common SQL statements.

Aggregation Commands

The reference for the data aggregation commands, which provide the interfaces to MongoDB’s aggregation capability.

Variables in Aggregation Expressions

Use of variables in aggregation pipeline expressions.

Aggregation Pipeline Quick Reference

Aggregation Commands Comparison

SQL to Aggregation Mapping Chart

Aggregation Commands

Variables in Aggregation Expressions

Aggregation Pipeline Quick Reference

Stages

Pipeline stages appear in an array. Documents pass through the stages in sequence. All except the $out and $geoNear stages can appear multiple times in a pipeline.

db.collection.aggregate( [ { <stage> }, ... ] )

Name
Description

$project
Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document.

$match
Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).

$redact
Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero document.

$limit
Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).

$skip
Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).

$unwind
Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array.

$group
Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields.

$sort
Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.

$geoNear
Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field.

$out
Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline.

Expressions

Expressions can include field paths and system variables, literals, expression objects, and expression operators. Expressions can be nested.

Field Path and System Variables

Aggregation expressions use field path to access fields in the input documents. To specify a field path, use a string that prefixes with a dollar sign $ the field name or the dotted field name, if the field is in embedded document. For example, "$user" to specify the field path for the user field or "$user.name" to specify the field path to "user.name" field.

"$<field>" is equivalent to "$$CURRENT.<field>" where the CURRENT is a system variable that defaults to the root of the current object in the most stages, unless stated otherwise in specific stages. CURRENT can be rebound.

Along with the CURRENT system variable, other system variables are also available for use in expressions. To use user-defined variables, use $let and $map expressions. To access variables in expressions, use a string that prefixes the variable name with $$.

Literals

Literals can be of any type. However, MongoDB parses string literals that start with a dollar sign $ as a path to a field and numeric/boolean literals in expression objects as projection flags. To avoid parsing literals, use the $literal expression.

Expression Objects

Expression objects have the following form:

{ <field1>: <expression1>, ... }

If the expressions are numeric or boolean literals, MongoDB treats the literals as projection flags (e.g. 1 or true to include the field), valid only in the $project stage. To avoid treating numeric or boolean literals as projection flags, use the $literal expression to wrap the numeric or boolean literals.

Operator Expressions

Operator expressions are similar to functions that take arguments. In general, these expressions take an array of arguments and have the following form:

{ <operator>: [ <argument1>, <argument2> ... ] }

If operator accepts a single argument, you can omit the outer array designating the argument list:

{ <operator>: <argument> }

To avoid parsing ambiguity if the argument is a literal array, you must wrap the literal array in a $literal expression or keep the outer array that designates the argument list.

Boolean Expressions

Boolean expressions evaluate their argument expressions as booleans and return a boolean as the result.

In addition to the false boolean value, Boolean expression evaluates as false the following: null, 0, and undefined values. The Boolean expression evaluates all other values as true, including non-zero numeric values and arrays.

Name | Description
$and | Returns true only when all its expressions evaluate to true. Accepts any number of argument expressions.
$or | Returns true when any of its expressions evaluates to true. Accepts any number of argument expressions.
$not | Returns the boolean value that is the opposite of its argument expression. Accepts a single argument expression.

Set Expressions

Set expressions performs set operation on arrays, treating arrays as sets. Set expressions ignores the duplicate entries in each input array and the order of the elements.

If the set operation returns a set, the operation filters out duplicates in the result to output an array that contains only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, the set expression does not descend into the nested array but evaluates the array at top-level.

Name | Description
$setEquals | Returns true if the input sets have the same distinct elements. Accepts two or more argument expressions.
$setIntersection | Returns a set with elements that appear in all of the input sets. Accepts any number of argument expressions.
$setUnion | Returns a set with elements that appear in any of the input sets. Accepts any number of argument expressions.
$setDifference | Returns a set with elements that appear in the first set but not in the second set; i.e. performs a relative complement [http://en.wikipedia.org/wiki/Complement_(set_theory)] of the second set relative to the first. Accepts exactly two argument expressions.
$setIsSubset | Returns true if all elements of the first set appear in the second set, including when the first set equals the second set; i.e. not a strict subset [http://en.wikipedia.org/wiki/Subset]. Accepts exactly two argument expressions.
$anyElementTrue | Returns true if any elements of a set evaluate to true; otherwise, returns false. Accepts a single argument expression.
$allElementsTrue | Returns true if no element of a set evaluates to false, otherwise, returns false. Accepts a single argument expression.

Comparison Expressions

Comparison expressions return a boolean except for $cmp which returns a number.

The comparison expressions take two argument expressions and compare both value and type, using the specified BSON comparison order for values of different types.

Name | Description
$cmp | Returns: 0 if the two values are equivalent, 1 if the first value is greater than the second, and -1 if the first value is less than the second.
$eq | Returns true if the values are equivalent.
$gt | Returns true if the first value is greater than the second.
$gte | Returns true if the first value is greater than or equal to the second.
$lt | Returns true if the first value is less than the second.
$lte | Returns true if the first value is less than or equal to the second.
$ne | Returns true if the values are not equivalent.

Arithmetic Expressions

Arithmetic expressions perform mathematic operations on numbers. Some arithmetic expressions can also support date arithmetic.

Name
Description

$add
Adds numbers to return the sum, or adds numbers and a date to return a new date. If adding numbers and a date, treats the numbers as milliseconds. Accepts any number of argument expressions, but at most, one expression can resolve to a date.

$subtract
Returns the result of subtracting the second value from the first. If the two values are numbers, return the difference. If the two values are dates, return the difference in milliseconds. If the two values are a date and a number in milliseconds, return the resulting date. Accepts two argument expressions. If the two values are a date and a number, specify the date argument first as it is not meaningful to subtract a date from a number.

$multiply
Multiplies numbers to return the product. Accepts any number of argument expressions.

$divide
Returns the result of dividing the first number by the second. Accepts two argument expressions.

$mod
Returns the remainder of the first number divided by the second. Accepts two argument expressions.

String Expressions

String expressions, with the exception of $concat, only have a well-defined behavior for strings of ASCII characters.

$concat behavior is well-defined regardless of the characters used.

Name | Description
$concat | Concatenates any number of strings.
$substr | Returns a substring of a string, starting at a specified index position up to a specified length. Accepts three expressions as arguments: the first argument must resolve to a string, and the second and third arguments must resolve to integers.
$toLower | Converts a string to lowercase. Accepts a single argument expression.
$toUpper | Converts a string to uppercase. Accepts a single argument expression.
$strcasecmp | Performs case-insensitive string comparison and returns: 0 if two strings are equivalent, 1 if the first string is greater than the second, and -1 if the first string is less than the second.

Text Search Expressions

Name | Description
$meta | Access text search metadata.

Array Expressions

Name | Description
$size | Returns the number of elements in the array. Accepts a single expression as argument.

Variable Expressions

Name | Description
$map | Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters.
$let | Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters.

Literal Expressions

Name | Description
$literal | Return a value without parsing. Use for values that the aggregation pipeline may interpret as an expression. For example, use a $literal expression to a string that starts with a $ to avoid parsing as a field path.

Date Expressions

Name | Description
$dayOfYear | Returns the day of the year for a date as a number between 1 and 366 (leap year).
$dayOfMonth | Returns the day of the month for a date as a number between 1 and 31.
$dayOfWeek | Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday).
$year | Returns the year for a date as a number (e.g. 2014).
$month | Returns the month for a date as a number between 1 (January) and 12 (December).
$week | Returns the week number for a date as a number between 0 (the partial week that precedes the first Sunday of the year) and 53 (leap year).
$hour | Returns the hour for a date as a number between 0 and 23.
$minute | Returns the minute for a date as a number between 0 and 59.
$second | Returns the seconds for a date as a number between 0 and 60 (leap seconds).
$millisecond | Returns the milliseconds of a date as a number between 0 and 999.

Conditional Expressions

Name
Description

$cond
A ternary operator that evaluates one expression, and depending on the result, returns the value of one of the other two expressions. Accepts either three expressions in an ordered list or three named parameters.

$ifNull
Returns either the non-null result of the first expression or the result of the second expression if the first expression results in a null result. Null result encompasses instances of undefined values or missing fields. Accepts two expressions as arguments. The result of the second expression can be null.

Accumulators

Accumulators, available only for the $group stage, compute values by combining documents that share the same group key. Accumulators take as input a single expression, evaluating the expression once for each input document, and maintain their state for the group of documents.

Name | Description
$sum | Returns a sum for each group. Ignores non-numeric values.
$avg | Returns an average for each group. Ignores non-numeric values.
$first | Returns a value from the first document for each group. Order is only defined if the documents are in a defined order.
$last | Returns a value from the last document for each group. Order is only defined if the documents are in a defined order.
$max | Returns the highest expression value for each group.
$min | Returns the lowest expression value for each group.
$push | Returns an array of expression values for each group.
$addToSet | Returns an array of unique expression values for each group. Order of the array elements is undefined.

Aggregation Commands Comparison

The following table provides a brief overview of the features of the MongoDB aggregation commands.

aggregate
mapReduce
group

Description

New in version 2.2.

Designed with specific goals of improving performance and usability for aggregation tasks.

Uses a “pipeline” approach where objects are transformed as they pass through a series of pipeline operators such as $group, $match, and $sort.

See Aggregation Pipeline Operators for more information on the pipeline operators.

Implements the Map-Reduce aggregation for processing large data sets.

Provides grouping functionality.

Is slower than the aggregate command and has less functionality than the mapReduce command.

Key Features

Pipeline operators can be repeated as needed.

Pipeline operators need not produce one output document for every input document.

Can also generate new documents or filter out documents.

In addition to grouping operations, can perform complex aggregation tasks as well as perform incremental aggregation on continuously growing datasets.

See Map-Reduce Examples and Perform Incremental Map-Reduce.

Can either group by existing fields or with a custom keyf JavaScript function, can group by calculated fields.

See group for information and example using the keyf function.

Flexibility

Limited to the operators and expressions supported by the aggregation pipeline.

However, can add computed fields, create new virtual sub-objects, and extract sub-fields into the top-level of results by using the $project pipeline operator.

See $project for more information as well as Aggregation Pipeline Operators for more information on all the available pipeline operators.

Custom map, reduce and finalize JavaScript functions offer flexibility to aggregation logic.

See mapReduce for details and restrictions on the functions.

Custom reduce and finalize JavaScript functions offer flexibility to grouping logic.

See group for details and restrictions on these functions.

Output Results

Returns results in various options (inline as a document that contains the result set, a cursor to the result set) or stores the results in a collection.

The result is subject to the BSON Document size limit if returned inline as a document that contains the result set.

Changed in version 2.6: Can return results as a cursor or store the results to a collection.

Returns results in various options (inline, new collection, merge, replace, reduce). See mapReduce for details on the output options.

Changed in version 2.2: Provides much better support for sharded map-reduce output than previous versions.

Returns results inline as an array of grouped items.

The result set must fit within the maximum BSON document size limit.

Changed in version 2.2: The returned array can contain at most 20,000 elements; i.e. at most 20,000 unique groupings. Previous versions had a limit of 10,000 elements.

Sharding
Supports non-sharded and sharded input collections.
Supports non-sharded and sharded input collections.
Does not support sharded collection.

Notes

Prior to 2.4, JavaScript code executed in a single thread.
Prior to 2.4, JavaScript code executed in a single thread.

More Information
See Aggregation Pipeline and aggregate.
See Map-Reduce and mapReduce.
See group.

SQL to Aggregation Mapping Chart

The aggregation pipeline allows MongoDB to provide native aggregation capabilities that corresponds to many common data aggregation operations in SQL.

The following table provides an overview of common SQL aggregation terms, functions, and concepts and the corresponding MongoDB aggregation operators:

SQL Terms, Functions, and Concepts | MongoDB Aggregation Operators
WHERE | $match
GROUP BY | $group
HAVING | $match
SELECT | $project
ORDER BY | $sort
LIMIT | $limit
SUM() | $sum
COUNT() | $sum
join | No direct corresponding operator; however, the $unwind operator allows for somewhat similar functionality, but with fields embedded within the document.

Examples

The following table presents a quick reference of SQL aggregation statements and the corresponding MongoDB statements. The examples in the table assume the following conditions:

The SQL examples assume two tables, orders and order_lineitem that join by the order_lineitem.order_id and the orders.id columns.

The MongoDB examples assume one collection orders that contain documents of the following prototype:

{
  cust_id: "abc123",
  ord_date: ISODate("2012-11-02T17:04:11.102Z"),
  status: 'A',
  price: 50,
  items: [ { sku: "xxx", qty: 25, price: 1 },
           { sku: "yyy", qty: 25, price: 1 } ]
}

SQL Example
MongoDB Example
Description

SELECT COUNT(*) AS count
FROM orders

db.orders.aggregate( [
   {
     $group: {
        _id: null,
        count: { $sum: 1 }
     }
   }
] )

Count all records from orders

SELECT SUM(price) AS total
FROM orders

db.orders.aggregate( [
   {
     $group: {
        _id: null,
        total: { $sum: "$price" }
     }
   }
] )

Sum the price field from orders

SELECT cust_id,
       SUM(price) AS total
FROM orders
GROUP BY cust_id

db.orders.aggregate( [
   {
     $group: {
        _id: "$cust_id",
        total: { $sum: "$price" }
     }
   }
] )

For each unique cust_id, sum the price field.

SELECT cust_id,
       SUM(price) AS total
FROM orders
GROUP BY cust_id
ORDER BY total

db.orders.aggregate( [
   {
     $group: {
        _id: "$cust_id",
        total: { $sum: "$price" }
     }
   },
   { $sort: { total: 1 } }
] )

For each unique cust_id, sum the price field, results sorted by sum.

SELECT cust_id,
       ord_date,
       SUM(price) AS total
FROM orders
GROUP BY cust_id,
         ord_date

db.orders.aggregate( [
   {
     $group: {
        _id: {
           cust_id: "$cust_id",
           ord_date: {
               month: { $month: "$ord_date" },
               day: { $dayOfMonth: "$ord_date" },
               year: { $year: "$ord_date"}
           }
        },
        total: { $sum: "$price" }
     }
   }
] )

For each unique cust_id, ord_date grouping, sum the price field. Excludes the time portion of the date.

SELECT cust_id,
       count(*)
FROM orders
GROUP BY cust_id
HAVING count(*) > 1

db.orders.aggregate( [
   {
     $group: {
        _id: "$cust_id",
        count: { $sum: 1 }
     }
   },
   { $match: { count: { $gt: 1 } } }
] )

For cust_id with multiple records, return the cust_id and the corresponding record count.

SELECT cust_id,
       ord_date,
       SUM(price) AS total
FROM orders
GROUP BY cust_id,
         ord_date
HAVING total > 250

db.orders.aggregate( [
   {
     $group: {
        _id: {
           cust_id: "$cust_id",
           ord_date: {
               month: { $month: "$ord_date" },
               day: { $dayOfMonth: "$ord_date" },
               year: { $year: "$ord_date"}
           }
        },
        total: { $sum: "$price" }
     }
   },
   { $match: { total: { $gt: 250 } } }
] )

For each unique cust_id, ord_date grouping, sum the price field and return only where the sum is greater than 250. Excludes the time portion of the date.

SELECT cust_id,
       SUM(price) as total
FROM orders
WHERE status = 'A'
GROUP BY cust_id

db.orders.aggregate( [
   { $match: { status: 'A' } },
   {
     $group: {
        _id: "$cust_id",
        total: { $sum: "$price" }
     }
   }
] )

For each unique cust_id with status A, sum the price field.

SELECT cust_id,
       SUM(price) as total
FROM orders
WHERE status = 'A'
GROUP BY cust_id
HAVING total > 250

db.orders.aggregate( [
   { $match: { status: 'A' } },
   {
     $group: {
        _id: "$cust_id",
        total: { $sum: "$price" }
     }
   },
   { $match: { total: { $gt: 250 } } }
] )

For each unique cust_id with status A, sum the price field and return only where the sum is greater than 250.

SELECT cust_id,
       SUM(li.qty) as qty
FROM orders o,
     order_lineitem li
WHERE li.order_id = o.id
GROUP BY cust_id

db.orders.aggregate( [
   { $unwind: "$items" },
   {
     $group: {
        _id: "$cust_id",
        qty: { $sum: "$items.qty" }
     }
   }
] )

For each unique cust_id, sum the corresponding line item qty fields associated with the orders.

SELECT COUNT(*)
FROM (SELECT cust_id,
             ord_date
      FROM orders
      GROUP BY cust_id,
               ord_date)
      as DerivedTable

db.orders.aggregate( [
   {
     $group: {
        _id: {
           cust_id: "$cust_id",
           ord_date: {
               month: { $month: "$ord_date" },
               day: { $dayOfMonth: "$ord_date" },
               year: { $year: "$ord_date"}
           }
        }
     }
   },
   {
     $group: {
        _id: null,
        count: { $sum: 1 }
     }
   }
] )

Count the number of distinct cust_id, ord_date groupings. Excludes the time portion of the date.

Aggregation Commands

Aggregation Commands

Name | Description
aggregate | Performs aggregation tasks such as group using the aggregation framework.
count | Counts the number of documents in a collection.
distinct | Displays the distinct values found for a specified key in a collection.
group | Groups documents in a collection by the specified key and performs simple aggregation.
mapReduce | Performs map-reduce aggregation for large data sets.

Aggregation Methods

Name | Description
db.collection.aggregate() | Provides access to the aggregation pipeline.
db.collection.group() | Groups documents in a collection by the specified key and performs simple aggregation.
db.collection.mapReduce() | Performs map-reduce aggregation for large data sets.

Variables in Aggregation Expressions

Aggregation expressions can use both user-defined and system variables.

Variables can hold any BSON type data. To access the value of the variable, use a string with the variable name prefixed with double dollar signs ($$).

If the variable references an object, to access a specific field in the object, use the dot notation; i.e. "$$<variable>.<field>".

User Variables

User variable names can contain the ascii characters [_a-zA-Z0-9] and any non-ascii character.

User variable names must begin with a lowercase ascii letter [a-z] or a non-ascii character.

System Variables

MongoDB offers the following system variables:

Variable
Description

ROOT

References the root document, i.e. the top-level document, currently being processed in the aggregation pipeline stage.

CURRENT

References the start of the field path being processed in the aggregation pipeline stage. Unless documented otherwise, all stages start with CURRENT the same as ROOT.

CURRENT is modifiable. However, since $<field> is equivalent to $$CURRENT.<field>, rebinding CURRENT changes the meaning of $ accesses.

DESCEND

One of the allowed results of a $redact expression.

PRUNE

One of the allowed results of a $redact expression.

KEEP

One of the allowed results of a $redact expression.

See also

$let, $redact

Indexes

Indexes provide high performance read operations for frequently used queries.

This section introduces indexes in MongoDB, describes the types and configuration options for indexes, and describes special types of indexing MongoDB supports. The section also provides tutorials detailing procedures and operational concerns, and providing information on how applications may use indexes.

Index Introduction

An introduction to indexes in MongoDB.

Index Concepts

The core documentation of indexes in MongoDB, including geospatial and text indexes.

Index Types

MongoDB provides different types of indexes for different purposes and different types of content.

Index Properties

The properties you can specify when building indexes.

Index Creation

The options available when creating indexes.

Index Intersection

The use of index intersection to fulfill a query.

Indexing Tutorials

Examples of operations involving indexes, including index creation and querying indexes.

Indexing Reference

Reference material for indexes in MongoDB.

Index Introduction

Index Concepts

Index Types

Single Field Indexes

Compound Indexes

Multikey Indexes

Geospatial Indexes and Queries

2dsphere Indexes

2d Indexes

geoHaystack Indexes

2d Index Internals

Text Indexes

Hashed Index

Index Properties

TTL Indexes

Unique Indexes

Sparse Indexes

Index Creation

Index Intersection

Multikey Index Bounds

Indexing Tutorials

Index Creation Tutorials

Create an Index

Create a Compound Index

Create a Unique Index

Create a Sparse Index

Create a Hashed Index

Build Indexes on Replica Sets

Build Indexes in the Background

Build Old Style Indexes

Index Management Tutorials

Remove Indexes

Modify an Index

Rebuild Indexes

Manage In-Progress Index Creation

Return a List of All Indexes

Measure Index Use

Geospatial Index Tutorials

Create a 2dsphere Index

Query a 2dsphere Index

Create a 2d Index

Query a 2d Index

Create a Haystack Index

Query a Haystack Index

Calculate Distance Using Spherical Geometry

Text Search Tutorials

Create a text Index

Specify a Language for Text Index

Specify Name for text Index

Control Search Results with Weights

Limit the Number of Entries Scanned

Text Search in the Aggregation Pipeline

Indexing Strategies

Create Indexes to Support Your Queries

Use Indexes to Sort Query Results

Ensure Indexes Fit in RAM

Create Queries that Ensure Selectivity

Indexing Reference

Text Search Languages

Index Introduction

Indexes support the efficient execution of queries in MongoDB. Without indexes, MongoDB must scan every document in a collection to select those documents that match the query statement. These collection scans are inefficient because they require mongod to process a larger volume of data than an index for each operation.

Indexes are special data structures [1] that store a small portion of the collection’s data set in an easy to traverse form. The index stores the value of a specific field or set of fields, ordered by the value of the field.

Fundamentally, indexes in MongoDB are similar to indexes in other database systems. MongoDB defines indexes at the collection level and supports indexes on any field or sub-field of the documents in a MongoDB collection.

If an appropriate index exists for a query, MongoDB can use the index to limit the number of documents it must inspect. In some cases, MongoDB can use the data from the index to determine which documents match a query. The following diagram illustrates a query that selects documents using an index.

[1]
MongoDB indexes use a B-tree data structure.

Optimization

Consider the documentation of the query optimizer for more information on the relationship between queries and indexes.

Create indexes to support common and user-facing queries. Having these indexes will ensure that MongoDB only scans the smallest possible number of documents.

Indexes can also optimize the performance of other operations in specific situations:

Sorted Results

MongoDB can use indexes to return documents sorted by the index key directly from the index without requiring an additional sort phase.

An index is traversable for sorting in either direction. For details, see Use Indexes to Sort Query Results.

Covered Results

When the query criteria and the projection of a query include only the indexed fields, MongoDB will return results directly from the index without scanning any documents or bringing documents into memory. These covered queries can be very efficient.

Index Types

MongoDB provides a number of different index types to support specific types of data and queries.

Default _id

All MongoDB collections have an index on the _id field that exists by default. If applications do not specify a value for _id the driver or the mongod will create an _id field with an ObjectId value.

The _id index is unique, and prevents clients from inserting two documents with the same value for the _id field.

Single Field

In addition to the MongoDB-defined _id index, MongoDB supports user-defined indexes on a single field of a document. Consider the following illustration of a single-field index:

Compound Index

MongoDB also supports user-defined indexes on multiple fields. These compound indexes behave like single-field indexes; however, the query can select documents based on additional fields. The order of fields listed in a compound index has significance. For instance, if a compound index consists of { userid: 1, score: -1 }, the index sorts first by userid and then, within each userid value, sort by score. Consider the following illustration of this compound index:

Multikey Index

MongoDB uses multikey indexes to index the content stored in arrays. If you index a field that holds an array value, MongoDB creates separate index entries for every element of the array. These multikey indexes allow queries to select documents that contain arrays by matching on element or elements of the arrays. MongoDB automatically determines whether to create a multikey index if the indexed field contains an array value; you do not need to explicitly specify the multikey type.

Consider the following illustration of a multikey index:

Geospatial Index

To support efficient queries of geospatial coordinate data, MongoDB provides two special indexes: 2d indexes that uses planar geometry when returning results and 2sphere indexes that use spherical geometry to return results.

See 2d Index Internals for a high level introduction to geospatial indexes.

Text Indexes

MongoDB provides a text index type that supports searching for string content in a collection. These text indexes do not store language-specific stop words (e.g. “the”, “a”, “or”) and stem the words in a collection to only store root words.

See Text Indexes for more information on text indexes and search.

Hashed Indexes

To support hash based sharding, MongoDB provides a hashed index type, which indexes the hash of the value of a field. These indexes have a more random distribution of values along their range, but only support equality matches and cannot support range-based queries.

Index Properties

Unique Indexes

The unique property for an index causes MongoDB to reject duplicate values for the indexed field. To create a unique index on a field that already has duplicate values, see Drop Duplicates for index creation options. Other than the unique constraint, unique indexes are functionally interchangeable with other MongoDB indexes.

Sparse Indexes

The sparse property of an index ensures that the index only contain entries for documents that have the indexed field. The index skips documents that do not have the indexed field.

You can combine the sparse index option with the unique index option to reject documents that have duplicate values for a field but ignore documents that do not have the indexed key.

TTL Indexes

TTL indexes are special indexes that MongoDB can use to automatically remove documents from a collection after a certain amount of time. This is ideal for certain types of information like machine generated event data, logs, and session information that only need to persist in a database for a finite amount of time.

See: Expire Data from Collections by Setting TTL for implementation instructions.

Index Intersection

New in version 2.6.

MongoDB can use the intersection of indexes to fulfill queries. For queries that specify compound query conditions, if one index can fulfill a part of a query condition, and another index can fulfill another part of the query condition, then MongoDB can use the intersection of the two indexes to fulfill the query. Whether the use of a compound index or the use of an index intersection is more efficient depends on the particular query and the system.

For details on index intersection, see Index Intersection.

Index Concepts

These documents describe and provide examples of the types, configuration options, and behavior of indexes in MongoDB. For an over view of indexing, see Index Introduction. For operational instructions, see Indexing Tutorials. The Indexing Reference documents the commands and operations specific to index construction, maintenance, and querying in MongoDB, including index types and creation options.

Index Types

MongoDB provides different types of indexes for different purposes and different types of content.

Single Field Indexes

A single field index only includes data from a single field of the documents in a collection. MongoDB supports single field indexes on fields at the top level of a document and on fields in sub-documents.

Compound Indexes

A compound index includes more than one field of the documents in a collection.

Multikey Indexes

A multikey index is an index on an array field, adding an index key for each value in the array.

Geospatial Indexes and Queries

Geospatial indexes support location-based searches on data that is stored as either GeoJSON objects or legacy coordinate pairs.

Text Indexes

Text indexes support search of string content in documents.

Hashed Index

Hashed indexes maintain entries with hashes of the values of the indexed field and are primarily used with sharded clusters to support hashed shard keys.

Index Properties

The properties you can specify when building indexes.

TTL Indexes

The TTL index is used for TTL collections, which expire data after a period of time.

Unique Indexes

A unique index causes MongoDB to reject all documents that contain a duplicate value for the indexed field.

Sparse Indexes

A sparse index does not index documents that do not have the indexed field.

Index Creation

The options available when creating indexes.

Index Intersection

The use of index intersection to fulfill a query.

Multikey Index Bounds

The computation of bounds on a multikey index scan.

Index Types

Single Field Indexes

Compound Indexes

Multikey Indexes

Geospatial Indexes and Queries

2dsphere Indexes

2d Indexes

geoHaystack Indexes

2d Index Internals

Text Indexes

Hashed Index

Index Properties

TTL Indexes

Unique Indexes

Sparse Indexes

Index Creation

Index Intersection

Multikey Index Bounds

Index Types

MongoDB provides a number of different index types. You can create indexes on any field or embedded field within a document or embedded document. You can create single field indexes or compound indexes. MongoDB also supports indexes of arrays, called multi-key indexes, as well as indexes on geospatial data. For a list of the supported index types, see Index Type Documentation.

In general, you should create indexes that support your common and user-facing queries. Having these indexes will ensure that MongoDB scans the smallest possible number of documents.

In the mongo shell, you can create an index by calling the ensureIndex() method. For more detailed instructions about building indexes, see the Indexing Tutorials page.

Behavior of Indexes

All indexes in MongoDB are B-tree indexes, which can efficiently support equality matches and range queries. The index stores items internally in order sorted by the value of the index field. The ordering of index entries supports efficient range-based operations and allows MongoDB to return sorted results using the order of documents in the index.

Ordering of Indexes

MongoDB indexes may be ascending, (i.e. 1) or descending (i.e. -1) in their ordering. Nevertheless, MongoDB may traverse the index in either direction. As a result, for single-field indexes, ascending and descending indexes are interchangeable. This is not the case for compound indexes: in compound indexes, the direction of the sort order can have a greater impact on the results.

See Sort Order for more information on the impact of index order on results in compound indexes.

Index Intersection

MongoDB can use the intersection of indexes to fulfill queries with compound conditions. See Index Intersection for details.

Limits

Certain restrictions apply to indexes, such as the length of the index keys or the number of indexes per collection. See Index Limitations for details.

Index Type Documentation

Single Field Indexes

A single field index only includes data from a single field of the documents in a collection. MongoDB supports single field indexes on fields at the top level of a document and on fields in sub-documents.

Compound Indexes

A compound index includes more than one field of the documents in a collection.

Multikey Indexes

A multikey index is an index on an array field, adding an index key for each value in the array.

Geospatial Indexes and Queries

Geospatial indexes support location-based searches on data that is stored as either GeoJSON objects or legacy coordinate pairs.

Text Indexes

Text indexes support search of string content in documents.

Hashed Index

Hashed indexes maintain entries with hashes of the values of the indexed field and are primarily used with sharded clusters to support hashed shard keys.

Single Field Indexes

Compound Indexes

Multikey Indexes

Geospatial Indexes and Queries

2dsphere Indexes

2d Indexes

geoHaystack Indexes

2d Index Internals

Text Indexes

Hashed Index

Single Field Indexes

MongoDB provides complete support for indexes on any field in a collection of documents. By default, all collections have an index on the _id field, and applications and users may add additional indexes to support important queries and operations.

MongoDB supports indexes that contain either a single field or multiple fields depending on the operations that this index-type supports. This document describes indexes that contain a single field. Consider the following illustration of a single field index.

See also

Compound Indexes for information about indexes that include multiple fields, and Index Introduction for a higher level introduction to indexing in MongoDB.

Example

Given the following document in the friends collection:

{ "_id" : ObjectId(...),
  "name" : "Alice",
  "age" : 27
}

The following command creates an index on the name field:

db.friends.ensureIndex( { "name" : 1 } )

Cases

_id Field Index

MongoDB creates the _id index, which is an ascending unique index on the _id field, for all collections when the collection is created. You cannot remove the index on the _id field.

Think of the _id field as the primary key for a collection. Every document must have a unique _id field. You may store any unique value in the _id field. The default value of _id is an ObjectId which is generated when the client inserts the document. An ObjectId is a 12-byte unique identifier suitable for use as the value of an _id field.

Note

In sharded clusters, if you do not use the _id field as the shard key, then your application must ensure the uniqueness of the values in the _id field to prevent errors. This is most-often done by using a standard auto-generated ObjectId.

Before version 2.2, capped collections did not have an _id field. In version 2.2 and newer, capped collections do have an _id field, except those in the local database. See Capped Collections Recommendations and Restrictions for more information.

Indexes on Embedded Fields

You can create indexes on fields within embedded documents, just as you can index top-level fields in documents. Indexes on embedded fields differ from indexes on embedded documents, which include the full content up to the maximum index size of the embedded document in the index. Instead, indexes on embedded fields allow you to use a “dot notation,” to introspect into embedded documents.

Consider a collection named people that holds documents that resemble the following example document:

{"_id": ObjectId(...),
 "name": "John Doe",
 "address": {
        "street": "Main",
        "zipcode": "53511",
        "state": "WI"
        }
}

You can create an index on the address.zipcode field, using the following specification:

db.people.ensureIndex( { "address.zipcode": 1 } )

Indexes on Embedded Documents

You can also create indexes on embedded documents.

For example, the factories collection contains documents that contain a metro field, such as:

{
  _id: ObjectId(...),
  metro: {
           city: "New York",
           state: "NY"
         },
  name: "Giant Factory"
}

The metro field is an embedded document, containing the embedded fields city and state. The following command creates an index on the metro field as a whole:

db.factories.ensureIndex( { metro: 1 } )

The following query can use the index on the metro field:

db.factories.find( { metro: { city: "New York", state: "NY" } } )

This query returns the above document. When performing equality matches on embedded documents, field order matters and the embedded documents must match exactly. For example, the following query does not match the above document:

db.factories.find( { metro: { state: "NY", city: "New York" } } )

See Query Embedded Documents for more information regarding querying on embedded documents.

Compound Indexes

MongoDB supports compound indexes, where a single index structure holds references to multiple fields [1] within a collection’s documents. The following diagram illustrates an example of a compound index on two fields:

[1]
MongoDB imposes a limit of 31 fields for any compound index.

Compound indexes can support queries that match on multiple fields.

Example

Consider a collection named products that holds documents that resemble the following document:

{
 "_id": ObjectId(...),
 "item": "Banana",
 "category": ["food", "produce", "grocery"],
 "location": "4th Street Store",
 "stock": 4,
 "type": "cases",
 "arrival": Date(...)
}

If applications query on the item field as well as query on both the item field and the stock field, you can specify a single compound index to support both of these queries:

db.products.ensureIndex( { "item": 1, "stock": 1 } )

Important

You may not create compound indexes that have hashed index fields. You will receive an error if you attempt to create a compound index that includes a hashed index.

The order of the fields in a compound index is very important. In the previous example, the index will contain references to documents sorted first by the values of the item field and, within each value of the item field, sorted by values of the stock field. See Sort Order for more information.

In addition to supporting queries that match on all the index fields, compound indexes can support queries that match on the prefix of the index fields. For details, see Prefixes.

Sort Order

Indexes store references to fields in either ascending (1) or descending (-1) sort order. For single-field indexes, the sort order of keys doesn’t matter because MongoDB can traverse the index in either direction. However, for compound indexes, sort order can matter in determining whether the index can support a sort operation.

Consider a collection events that contains documents with the fields username and date. Applications can issue queries that return results sorted first by ascending username values and then by descending (i.e. more recent to last) date values, such as:

db.events.find().sort( { username: 1, date: -1 } )

or queries that return results sorted first by descending username values and then by ascending date values, such as:

db.events.find().sort( { username: -1, date: 1 } )

The following index can support both these sort operations:

db.events.ensureIndex( { "username" : 1, "date" : -1 } )

However, the above index cannot support sorting by ascending username values and then by ascending date values, such as the following:

db.events.find().sort( { username: 1, date: 1 } )

Prefixes

Index prefixes are the beginning subsets of indexed fields. For example, consider the following compound index:

{ "item": 1, "location": 1, "stock": 1 }

The index has the following index prefixes:

{ item: 1 }

{ item: 1, location: 1 }

For a compound index, MongoDB can use the index to support queries on the index prefixes. As such, MongoDB can use the index for queries on the following fields:

the item field,

the item field and the location field,

the item field and the location field and the stock field.

MongoDB can also use the index to support a query on item and stock fields since item field corresponds to a prefix. However, the index would not be as efficient in supporting the query as would be an index on only item and stock.

However, MongoDB cannot use the index to support queries that include the following fields since without the item field, none of the listed fields correspond to a prefix index:

the location field,

the stock field, or

the location and stock fields.

If you have a collection that has both a compound index and an index on its prefix (e.g. { a: 1, b: 1 } and { a: 1 }), if neither index has a sparse or unique constraint, then you can remove the index on the prefix (e.g. { a: 1 }). MongoDB will use the compound index in all of the situations that it would have used the prefix index.

Index Intersection

Starting in version 2.6, MongoDB can use index intersection to fulfill queries. The choice between creating compound indexes that support your queries or relying on index intersection depends on the specifics of your system. See Index Intersection and Compound Indexes for more details.

Multikey Indexes

To index a field that holds an array value, MongoDB adds index items for each item in the array. These multikey indexes allow MongoDB to return documents from queries using the value of an array. MongoDB automatically determines whether to create a multikey index if the indexed field contains an array value; you do not need to explicitly specify the multikey type.

Consider the following illustration of a multikey index:

Multikey indexes support all operations supported by other MongoDB indexes; however, applications may use multikey indexes to select documents based on ranges of values for the value of an array. Multikey indexes support arrays that hold both values (e.g. strings, numbers) and nested documents.

Limitations

Interactions between Compound and Multikey Indexes

While you can create multikey compound indexes, at most one field in a compound index may hold an array. For example, given an index on { a: 1, b: 1 }, the following documents are permissible:

{a: [1, 2], b: 1}

{a: 1, b: [1, 2]}

However, the following document is impermissible, and MongoDB cannot insert such a document into a collection with the {a: 1, b: 1 } index:

{a: [1, 2], b: [1, 2]}

If you attempt to insert such a document, MongoDB will reject the insertion, and produce an error that says cannot index parallel arrays. MongoDB does not index parallel arrays because they require the index to include each value in the Cartesian product of the compound keys, which could quickly result in incredibly large and difficult to maintain indexes.

Shard Keys

Important

The index of a shard key cannot be a multi-key index.

Hashed Indexes

hashed indexes are not compatible with multi-key indexes.

To compute the hash for a hashed index, MongoDB collapses embedded documents and computes the hash for the entire value. For fields that hold arrays or embedded documents, you cannot use the index to support queries that introspect the embedded document.

Examples

Index Basic Arrays

Given the following document:

{
  "_id" : ObjectId("..."),
  "name" : "Warm Weather",
  "author" : "Steve",
  "tags" : [ "weather", "hot", "record", "april" ]
}

Then an index on the tags field, { tags: 1 }, would be a multikey index and would include these four separate entries for that document:

"weather",

"hot",

"record", and

"april".

Queries could use the multikey index to return queries for any of the above values.

Index Arrays with Embedded Documents

You can create multikey indexes on fields in objects embedded in arrays, as in the following example:

Consider a feedback collection with documents in the following form:

{
 "_id": ObjectId(...),
 "title": "Grocery Quality",
 "comments": [
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the cheddar selection." },
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the mustard selection." },
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the olive selection." }
 ]
}

An index on the comments.text field would be a multikey index and would add items to the index for all embedded documents in the array.

With the index { "comments.text": 1 } on the feedback collection, consider the following query:

db.feedback.find( { "comments.text": "Please expand the olive selection." } )

The query would select the documents in the collection that contain the following embedded document in the comments array:

{ author_id: ObjectId(...),
  date: Date(...),
  text: "Please expand the olive selection." }

Geospatial Indexes and Queries

MongoDB offers a number of indexes and query mechanisms to handle geospatial information. This section introduces MongoDB’s geospatial features. For complete examples of geospatial queries in MongoDB, see Geospatial Index Tutorials.

Surfaces

Before storing your location data and writing queries, you must decide the type of surface to use to perform calculations. The type you choose affects how you store data, what type of index to build, and the syntax of your queries.

MongoDB offers two surface types:

Spherical

To calculate geometry over an Earth-like sphere, store your location data on a spherical surface and use 2dsphere index.

Store your location data as GeoJSON objects with this coordinate-axis order: longitude, latitude. The coordinate reference system for GeoJSON uses the WGS84 datum.

Flat

To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a 2d index.

Location Data

If you choose spherical surface calculations, you store location data as either:

GeoJSON Objects

Queries on GeoJSON objects always calculate on a sphere. The default coordinate reference system for GeoJSON uses the WGS84 datum.

New in version 2.4: Support for GeoJSON storage and queries is new in version 2.4. Prior to version 2.4, all geospatial data used coordinate pairs.

Changed in version 2.6: Support for additional GeoJSON types: MultiPoint, MultiLineString, MultiPolygon, GeometryCollection.

MongoDB supports the following GeoJSON objects:

Point

LineString

Polygon

MultiPoint

MultiLineString

MultiPolygon

GeometryCollection

Legacy Coordinate Pairs

MongoDB supports spherical surface calculations on legacy coordinate pairs using a 2dsphere index by converting the data to the GeoJSON Point type.

If you choose flat surface calculations via a 2d index, you can store data only as legacy coordinate pairs.

Query Operations

MongoDB’s geospatial query operators let you query for:

Inclusion

MongoDB can query for locations contained entirely within a specified polygon. Inclusion queries use the $geoWithin operator.

Both 2d and 2dsphere indexes can support inclusion queries. MongoDB does not require an index for inclusion queries; however, such indexes will improve query performance.

Intersection

MongoDB can query for locations that intersect with a specified geometry. These queries apply only to data on a spherical surface. These queries use the $geoIntersects operator.

Only 2dsphere indexes support intersection.

Proximity

MongoDB can query for the points nearest to another point. Proximity queries use the $near operator. The $near operator requires a 2d or 2dsphere index.

Geospatial Indexes

MongoDB provides the following geospatial index types to support the geospatial queries.

2dsphere

2dsphere indexes support:

Calculations on a sphere

GeoJSON objects and include backwards compatibility for legacy coordinate pairs

Compound indexes with scalar index fields (i.e. ascending or descending) as a prefix or suffix of the 2dsphere index field

New in version 2.4: 2dsphere indexes are not available before version 2.4.

See also

Query a 2dsphere Index

2d

2d indexes support:

Calculations using flat geometry

Legacy coordinate pairs (i.e., geospatial points on a flat coordinate system)

Compound indexes with only one additional field, as a suffix of the 2d index field

See also

Query a 2d Index

Geospatial Indexes and Sharding

You cannot use a geospatial index as the shard key index.

You can create and maintain a geospatial index on a sharded collection if it uses fields other than the shard key fields.

For sharded collections, queries using $near are not supported. You can instead use either the geoNear command or the $geoNear aggregation stage.

You also can query for geospatial data using $geoWithin.

Additional Resources

The following pages provide complete documentation for geospatial indexes and queries:

2dsphere Indexes

A 2dsphere index supports queries that calculate geometries on an earth-like sphere. The index supports data stored as both GeoJSON objects and as legacy coordinate pairs.

2d Indexes

The 2d index supports data stored as legacy coordinate pairs and is intended for use in MongoDB 2.2 and earlier.

geoHaystack Indexes

A haystack index is a special index optimized to return results over small areas. For queries that use spherical geometry, a 2dsphere index is a better option than a haystack index.

2d Index Internals

Provides a more in-depth explanation of the internals of geospatial indexes. This material is not necessary for normal operations but may be useful for troubleshooting and for further understanding.

2dsphere Indexes

2d Indexes

geoHaystack Indexes

2d Index Internals

See also

Geospatial Query Compatibility

2dsphere Indexes

New in version 2.4.

A 2dsphere index supports queries that calculate geometries on an earth-like sphere. The index supports data stored as both GeoJSON objects and as legacy coordinate pairs. The index supports legacy coordinate pairs by converting the data to the GeoJSON Point type. The default datum for an earth-like sphere in MongoDB 2.4 is WGS84. Coordinate-axis order is longitude, latitude.

The 2dsphere index supports all MongoDB geospatial queries: queries for inclusion, intersection and proximity. See the Geospatial Query Operators for the query operators that support geospatial queries.

To create a 2dsphere index, use the db.collection.ensureIndex method. A compound 2dsphere index can reference multiple location and non-location fields within a collection’s documents. See Create a 2dsphere Index for more information.

2dsphere Version 2

Changed in version 2.6.

MongoDB 2.6 introduces a version 2 of 2dsphere indexes. Version 2 is the default version of 2dsphere indexes created in MongoDB 2.6. To create a 2dsphere index as a version 1, include the option { "2dsphereIndexVersion": 1 } when creating the index.

Additional GeoJSON Objects

Changed in version 2.6.

Version 2 adds support for additional GeoJSON object: MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

sparse Property

Changed in version 2.6.

Version 2 2dsphere indexes are sparse by default and ignores the sparse: true option. If a document lacks a 2dsphere index field (or the field is null or an empty array), MongoDB does not add an entry for the document to the 2dsphere index. For inserts, MongoDB inserts the document but does not add to the 2dsphere index.

For a compound index that includes a 2dsphere index key along with keys of other types, only the 2dsphere index field determines whether the index references a document.

Earlier versions of MongoDB only support Version 1 2dsphere indexes. Version 1 2dsphere indexes are not sparse by default and will reject documents with null location fields.

Considerations

geoNear and $geoNear Restrictions

The geoNear command and the $geoNear pipeline stage require that a collection have at most only one 2dsphere index and/or only one 2d index whereas geospatial query operators (e.g. $near and $geoWithin) permit collections to have multiple geospatial indexes.

The geospatial index restriction for the geoNear command and the $geoNear pipeline stage exists because neither the geoNear command nor the $geoNear pipeline stage syntax includes the location field. As such, index selection among multiple 2d indexes or 2dsphere indexes is ambiguous.

No such restriction applies for geospatial query operators since these operators take a location field, eliminating the ambiguity.

Shard Key Restrictions

You cannot use a 2dsphere index as a shard key when sharding a collection. However, you can create and maintain a geospatial index on a sharded collection by using a different field as the shard key.

Data Restrictions

Fields with 2dsphere indexes must hold geometry data in the form of coordinate pairs or GeoJSON data. If you attempt to insert a document with non-geometry data in a 2dsphere indexed field, or build a 2dsphere index on a collection where the indexed field has non-geometry data, the operation will fail.

GeoJSON Objects

MongoDB supports the following GeoJSON objects:

Point

LineString

Polygon

MultiPoint

MultiLineString

MultiPolygon

GeometryCollection

The MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection require 2dsphere index version 2.

In order to index GeoJSON data, you must store the data in a location field that you name. The location field contains an embedded document with a type field specifying the GeoJSON object type and a coordinates field specifying the object’s coordinates. Always store coordinates in longitude, latitude order.

Use the following syntax:

{ <location field>: { type: "<GeoJSON type>" , coordinates: <coordinates> } }

Point

New in version 2.4.

The following example stores a GeoJSON Point:

{ loc: { type: "Point", coordinates: [ 40, 5 ] } }

LineString

New in version 2.4.

The following example stores a GeoJSON LineString:

{ loc: { type: "LineString", coordinates: [ [ 40, 5 ], [ 41, 6 ] ] } }

Polygon

New in version 2.4.

Polygons consist of an array of GeoJSON LinearRing coordinate arrays. These LinearRings are closed LineStrings. Closed LineStrings have at least four coordinate pairs and specify the same position as the first and last coordinates.

The line that joins two points on a curved surface may or may not contain the same set of co-ordinates that joins those two points on a flat surface. The line that joins two points on a curved surface will be a geodesic. Carefully check points to avoid errors with shared edges, as well as overlaps and other types of intersections.

Polygons with a Single Ring

The following example stores a GeoJSON Polygon with an exterior ring and no interior rings (or holes). Note the first and last coordinate pair with the [ 0 , 0 ] coordinate:

{
  loc :
    {
      type: "Polygon",
      coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0  ] ] ]
    }
}

For Polygons with a single ring, the ring cannot self-intersect.

Polygons with Multiple Rings

For Polygons with multiple rings:

The first described ring must be the exterior ring.

The exterior ring cannot self-intersect.

Any interior ring must be entirely contained by the outer ring.

Interior rings cannot intersect or overlap each other. Interior rings cannot share an edge.

The following document represents a polygon with an interior ring as GeoJSON:

{ loc : {
     type : "Polygon",
     coordinates : [
         [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ],
         [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ]
     ]
  }
}

MultiPoint

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiPoint [http://geojson.org/geojson-spec.html#id5]:

{ loc: {
    type: "MultiPoint",
    coordinates: [
       [ -73.9580, 40.8003 ],
       [ -73.9498, 40.7968 ],
       [ -73.9737, 40.7648 ],
       [ -73.9814, 40.7681 ]
    ]
  }
}

MultiLineString

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiLineString [http://geojson.org/geojson-spec.html#id6]:

{ loc:
    {
      type: "MultiLineString",
      coordinates: [
         [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ],
         [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ],
         [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ],
         [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ]
      ]
    }
}

MultiPolygon

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiPolygon [http://geojson.org/geojson-spec.html#id7]:

{ loc:
    {
      type: "MultiPolygon",
      coordinates: [
         [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ], [ -73.958, 40.8003 ] ] ],
         [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.958, 40.8003 ] ] ]
      ]
    }
}

GeometryCollection

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type GeometryCollection [http://geojson.org/geojson-spec.html#geometrycollection]:

{ loc:
    {
      type: "GeometryCollection",
      geometries: [
         {
            type: "MultiPoint",
            coordinates: [
               [ -73.9580, 40.8003 ],
               [ -73.9498, 40.7968 ],
               [ -73.9737, 40.7648 ],
               [ -73.9814, 40.7681 ]
            ]
         },
         {
            type: "MultiLineString",
            coordinates: [
               [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ],
               [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ],
               [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ],
               [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ]
            ]
         }
      ]
    }
}

2d Indexes

Use a 2d index for data stored as points on a two-dimensional plane. The 2d index is intended for legacy coordinate pairs used in MongoDB 2.2 and earlier.

Use a 2d index if:

your database has legacy location data from MongoDB 2.2 or earlier, and

you do not intend to store any location data as GeoJSON objects.

See the Geospatial Query Operators for the query operators that support geospatial queries.

Considerations

The geoNear command and the $geoNear pipeline stage require that a collection have at most only one 2d index and/or only one 2dsphere index whereas geospatial query operators (e.g. $near and $geoWithin) permit collections to have multiple geospatial indexes.

The geospatial index restriction for the geoNear command and the $geoNear pipeline stage exists because neither the geoNear command nor the $geoNear pipeline stage syntax includes the location field. As such, index selection among multiple 2d indexes or 2dsphere indexes is ambiguous.

No such restriction applies for geospatial query operators since these operators take a location field, eliminating the ambiguity.

Do not use a 2d index if your location data includes GeoJSON objects. To index on both legacy coordinate pairs and GeoJSON objects, use a 2dsphere index.

You cannot use a 2d index as a shard key when sharding a collection. However, you can create and maintain a geospatial index on a sharded collection by using a different field as the shard key.

Behavior

The 2d index supports calculations on a flat, Euclidean plane. The 2d index also supports distance-only calculations on a sphere, but for geometric calculations (e.g. $geoWithin) on a sphere, store data as GeoJSON objects and use the 2dsphere index type.

A 2d index can reference two fields. The first must be the location field. A 2d compound index constructs queries that select first on the location field, and then filters those results by the additional criteria. A compound 2d index can cover queries.

Points on a 2D Plane

To store location data as legacy coordinate pairs, use an array or an embedded document. When possible, use the array format:

loc : [ <longitude> , <latitude> ]

Consider the embedded document form:

loc : { lng : <longitude> , lat : <latitude> }

Arrays are preferred as certain languages do not guarantee associative map ordering.

For all points, if you use longitude and latitude, store coordinates in longitude, latitude order.

sparse Property

2d indexes are sparse by default and ignores the sparse: true option. If a document lacks a 2d index field (or the field is null or an empty array), MongoDB does not add an entry for the document to the 2d index. For inserts, MongoDB inserts the document but does not add to the 2d index.

For a compound index that includes a 2d index key along with keys of other types, only the 2d index field determines whether the index references a document.

geoHaystack Indexes

A geoHaystack index is a special index that is optimized to return results over small areas. geoHaystack indexes improve performance on queries that use flat geometry.

For queries that use spherical geometry, a 2dsphere index is a better option than a haystack index. 2dsphere indexes allow field reordering; geoHaystack indexes require the first field to be the location field. Also, geoHaystack indexes are only usable via commands and so always return all results at once.

Behavior

geoHaystack indexes create “buckets” of documents from the same geographic area in order to improve performance for queries limited to that area. Each bucket in a geoHaystack index contains all the documents within a specified proximity to a given longitude and latitude.

sparse Property

geoHaystack indexes are sparse by default and ignore the sparse: true option. If a document lacks a geoHaystack index field (or the field is null or an empty array), MongoDB does not add an entry for the document to the geoHaystack index. For inserts, MongoDB inserts the document but does not add to the geoHaystack index.

geoHaystack indexes include one geoHaystack index key and one non-geospatial index key; however, only the geoHaystack index field determines whether the index references a document.

Create geoHaystack Index

To create a geoHaystack index, see Create a Haystack Index. For information and example on querying a haystack index, see Query a Haystack Index.

2d Index Internals

This document provides a more in-depth explanation of the internals of MongoDB’s 2d geospatial indexes. This material is not necessary for normal operations or application development but may be useful for troubleshooting and for further understanding.

Calculation of Geohash Values for 2d Indexes

When you create a geospatial index on legacy coordinate pairs, MongoDB computes geohash values for the coordinate pairs within the specified location range and then indexes the geohash values.

To calculate a geohash value, recursively divide a two-dimensional map into quadrants. Then assign each quadrant a two-bit value. For example, a two-bit representation of four quadrants would be:

01  11

00  10

These two-bit values (00, 01, 10, and 11) represent each of the quadrants and all points within each quadrant. For a geohash with two bits of resolution, all points in the bottom left quadrant would have a geohash of 00. The top left quadrant would have the geohash of 01. The bottom right and top right would have a geohash of 10 and 11, respectively.

To provide additional precision, continue dividing each quadrant into sub-quadrants. Each sub-quadrant would have the geohash value of the containing quadrant concatenated with the value of the sub-quadrant. The geohash for the upper-right quadrant is 11, and the geohash for the sub-quadrants would be (clockwise from the top left): 1101, 1111, 1110, and 1100, respectively.

Multi-location Documents for 2d Indexes

New in version 2.0: Support for multiple locations in a document.

While 2d geospatial indexes do not support more than one set of coordinates in a document, you can use a multi-key index to index multiple coordinate pairs in a single document. In the simplest example you may have a field (e.g. locs) that holds an array of coordinates, as in the following example:

{ _id : ObjectId(...),
  locs : [ [ 55.5 , 42.3 ] ,
           [ -74 , 44.74 ] ,
           { lng : 55.5 , lat : 42.3 } ]
}

The values of the array may be either arrays, as in [ 55.5, 42.3 ], or embedded documents, as in { lng : 55.5 , lat : 42.3 }.

You could then create a geospatial index on the locs field, as in the following:

db.places.ensureIndex( { "locs": "2d" } )

You may also model the location data as a field inside of an embedded document. In this case, the document would contain a field (e.g. addresses) that holds an array of documents where each document has a field (e.g. loc:) that holds location coordinates. For example:

{ _id : ObjectId(...),
  name : "...",
  addresses : [ {
                 context : "home" ,
                 loc : [ 55.5, 42.3 ]
                } ,
                {
                 context : "home",
                 loc : [ -74 , 44.74 ]
                }
              ]
}

You could then create the geospatial index on the addresses.loc field as in the following example:

db.records.ensureIndex( { "addresses.loc": "2d" } )

To include the location field with the distance field in multi-location document queries, specify includeLocs: true in the geoNear command.

Text Indexes

New in version 2.4.

MongoDB provides text indexes to support text search of string content in documents of a collection.

text indexes can include any field whose value is a string or an array of string elements. To perform queries that access the text index, use the $text query operator.

Changed in version 2.6: MongoDB enables the text search feature by default. In MongoDB 2.4, you need to enable the text search feature manually to create text indexes and perform text search.

Create Text Index

To create a text index, use the db.collection.ensureIndex() method. To index a field that contains a string or an array of string elements, include the field and specify the string literal "text" in the index document, as in the following example:

db.reviews.ensureIndex( { comments: "text" } )

A collection can have at most one text index.

For examples of creating text indexes on multiple fields, see Create a text Index.

Supported Languages and Stop Words

MongoDB supports text search for various languages. text indexes drop language-specific stop words (e.g. in English, “the”, “an”, “a”, “and”, etc.) and uses simple language-specific suffix stemming. For a list of the supported languages, see Text Search Languages.

If you specify a language value of "none", then the text index uses simple tokenization with no list of stop words and no stemming.

If the index language is English, text indexes are case-insensitive for non-diacritics; i.e. case insensitive for [A-z].

To specify a language for the text index, see Specify a Language for Text Index.

sparse Property

text indexes are sparse by default and ignores the sparse: true option. If a document lacks a text index field (or the field is null or an empty array), MongoDB does not add an entry for the document to the text index. For inserts, MongoDB inserts the document but does not add to the text index.

For a compound index that includes a text index key along with keys of other types, only the text index field determine whether the index references a document. The other keys do not determine whether the index references the documents or not.

Restrictions

Text Search and Hints

You cannot use hint() if the query includes a $text query expression.

Text Index and Sort

Sort operations cannot obtain sort order from a text index, even from a compound text index; i.e. sort operations cannot use the ordering in the text index.

Compound Index

A compound index can include a text index key in combination with ascending/descending index keys. However, these compound indexes have the following restrictions:

A compound text index cannot include any other special index types, such as multi-key or geospatial index fields.

If the compound text index includes keys preceding the text index key, to perform a $text search, the query predicate must include equality match conditions on the preceding keys.

See also Text Index and Sort for additional limitations.

For an example of a compound text index, see Limit the Number of Entries Scanned.

Drop a Text Index

To drop a text index, pass the name of the index to the db.collection.dropIndex() method. To get the name of the index, run the getIndexes() method.

For information on the default naming scheme for text indexes as well as overriding the default name, see Specify Name for text Index.

Storage Requirements and Performance Costs

text indexes have the following storage requirements and performance costs:

text indexes change the space allocation method for all future record allocations in a collection to usePowerOf2Sizes.

text indexes can be large. They contain one index entry for each unique post-stemmed word in each indexed field for each document inserted.

Building a text index is very similar to building a large multi-key index and will take longer than building a simple ordered (scalar) index on the same data.

When building a large text index on an existing collection, ensure that you have a sufficiently high limit on open file descriptors. See the recommended settings.

text indexes will impact insertion throughput because MongoDB must add an index entry for each unique post-stemmed word in each indexed field of each new source document.

Additionally, text indexes do not store phrases or information about the proximity of words in the documents. As a result, phrase queries will run much more effectively when the entire collection fits in RAM.

Text Search

Text search supports the search of string content in documents of a collection. MongoDB provides the $text operator to perform text search in queries and in aggregation pipelines.

The text search process:

tokenizes and stems the search term(s) during both the index creation and the text command execution.

assigns a score to each document that contains the search term in the indexed fields. The score determines the relevance of a document to a given search query.

The $text operator can search for words and phrases. The query matches on the complete stemmed words. For example, if a document field contains the word blueberry, a search on the term blue will not match the document. However, a search on either blueberry or blueberries will match.

For information and examples on various text search patterns, see the $text query operator. For examples of text search in aggregation pipeline, see Text Search in the Aggregation Pipeline.

Hashed Index

New in version 2.4.

Hashed indexes maintain entries with hashes of the values of the indexed field. The hashing function collapses embedded documents and computes the hash for the entire value but does not support multi-key (i.e. arrays) indexes.

Hashed indexes support sharding a collection using a hashed shard key. Using a hashed shard key to shard a collection ensures a more even distribution of data. See Shard a Collection Using a Hashed Shard Key for more details.

MongoDB can use the hashed index to support equality queries, but hashed indexes do not support range queries.

You may not create compound indexes that have hashed index fields or specify a unique constraint on a hashed index; however, you can create both a hashed index and an ascending/descending (i.e. non-hashed) index on the same field: MongoDB will use the scalar index for range queries.

Warning

MongoDB hashed indexes truncate floating point numbers to 64-bit integers before hashing. For example, a hashed index would store the same value for a field that held a value of 2.3, 2.2, and 2.9. To prevent collisions, do not use a hashed index for floating point numbers that cannot be reliably converted to 64-bit integers (and then back to floating point). MongoDB hashed indexes do not support floating point values larger than 2⁵³.

Create a hashed index using an operation that resembles the following:

db.active.ensureIndex( { a: "hashed" } )

This operation creates a hashed index for the active collection on the a field.

Index Properties

In addition to the numerous index types MongoDB supports, indexes can also have various properties. The following documents detail the index properties that you can select when building an index.

TTL Indexes

The TTL index is used for TTL collections, which expire data after a period of time.

Unique Indexes

A unique index causes MongoDB to reject all documents that contain a duplicate value for the indexed field.

Sparse Indexes

A sparse index does not index documents that do not have the indexed field.

TTL Indexes

Unique Indexes

Sparse Indexes

TTL Indexes

TTL indexes are special single-field indexes that MongoDB can use to automatically remove documents from a collection after a certain amount of time. Data expiration is useful for certain types of information like machine generated event data, logs, and session information that only need to persist in a database for a finite amount of time.

To create a TTL index, use the db.collection.ensureIndex() method with the expireAfterSeconds option on a field whose value is either a date or an array that contains date values.

For example, to create a TTL index on the lastModifiedDate field of the eventlog collection, use the following operation in the mongo shell:

db.eventlog.ensureIndex( { "lastModifiedDate": 1 }, { expireAfterSeconds: 3600 } )

Behavior

Expiration of Data

TTL indexes expire documents after the specified number of seconds has passed since the indexed field value; i.e. the expiration threshold is the indexed field value plus the specified number of seconds.

If the field is an array, and there are multiple date values in the index, MongoDB uses lowest (i.e. earliest) date value in the array to calculate the expiration threshold.

If the indexed field in a document is not a date or an array that holds a date value(s), the document will not expire.

If a document does not contain the indexed field, the document will not expire.

Delete Operations

A background thread in mongod reads the values in the index and removes expired documents from the collection.

When the TTL thread is active, you will see delete operations in the output of db.currentOp() or in the data collected by the database profiler.

Timing of the Delete Operation

When you build a TTL index in the background, the TTL thread can begin deleting documents while the index is building. If you build a TTL index in the foreground, MongoDB begins removing expired documents as soon as the index finishes building.

The TTL index does not guarantee that expired data will be deleted immediately upon expiration. There may be a delay between the time a document expires and the time that MongoDB removes the document from the database.

The background task that removes expired documents runs every 60 seconds. As a result, documents may remain in a collection during the period between the expiration of the document and the running of the background task.

Because the duration of the removal operation depends on the workload of your mongod instance, expired data may exist for some time beyond the 60 second period between runs of the background task.

Replica Sets

On replica sets, the TTL background thread only deletes documents on the primary. However, the TTL background thread does run on secondaries. Secondary members replicate deletion operations from the primary.

Support for Queries

A TTL index supports queries in the same way non-TTL indexes do.

Record Allocation

A collection with a TTL index has usePowerOf2Sizes enabled, and you cannot modify this setting for the collection. As a result of enabling usePowerOf2Sizes, MongoDB must allocate more disk space relative to data size. This approach helps mitigate the possibility of storage fragmentation caused by frequent delete operations and leads to more predictable storage use patterns.

Restrictions

TTL indexes are a single-field indexes. Compound indexes do not support TTL and ignores the expireAfterSeconds option.

The _id field does not support TTL indexes.

You cannot create a TTL index on a capped collection because MongoDB cannot remove documents from a capped collection.

You cannot use ensureIndex() to change the value of expireAfterSeconds of an existing index. Instead use the collMod database command in conjunction with the index collection flag. Otherwise, to change the value of the option of an existing index, you must drop the index first and recreate.

If a non-TTL single-field index already exists for a field, you cannot create a TTL index on the same field since you cannot create indexes that have the same key specification and differ only by the options. To change a non-TTL single-field index to a TTL index, you must drop the index first and recreate with the expireAfterSeconds option.

Additional Information

For examples, see Expire Data from Collections by Setting TTL.

Unique Indexes

A unique index causes MongoDB to reject all documents that contain a duplicate value for the indexed field.

To create a unique index, use the db.collection.ensureIndex() method with the unique option set to true. For example, to create a unique index on the user_id field of the members collection, use the following operation in the mongo shell:

db.members.ensureIndex( { "user_id": 1 }, { unique: true } )

By default, unique is false on MongoDB indexes.

If you use the unique constraint on a compound index, then MongoDB will enforce uniqueness on the combination of values rather than the individual value for any or all values of the key.

Behavior

Unique Constraint Across Separate Documents

The unique constraint applies to separate documents in the collection. That is, the unique index prevents separate documents from having the same value for the indexed key, but the index does not prevent a document from having multiple elements or embedded documents in an indexed array from having the same value. In the case of a single document with repeating values, the repeated value is inserted into the index only once.

For example, a collection has a unique index on a.b:

db.collection.ensureIndex( { "a.b": 1 }, { unique: true } )

The unique index permits the insertion of the following document into the collection if no other document in the collection has the a.b value of 5:

db.collection.insert( { a: [ { b: 5 }, { b: 5 } ] } )

Unique Index and Missing Field

If a document does not have a value for the indexed field in a unique index, the index will store a null value for this document. Because of the unique constraint, MongoDB will only permit one document that lacks the indexed field. If there is more than one document without a value for the indexed field or is missing the indexed field, the index build will fail with a duplicate key error.

You can combine the unique constraint with the sparse index to filter these null values from the unique index and avoid the error.

Restrictions

You may not specify a unique constraint on a hashed index.

See also

Create a Unique Index

Sparse Indexes

Sparse indexes only contain entries for documents that have the indexed field, even if the index field contains a null value. The index skips over any document that is missing the indexed field. The index is “sparse” because it does not include all documents of a collection. By contrast, non-sparse indexes contain all documents in a collection, storing null values for those documents that do not contain the indexed field.

To create a sparse index, use the db.collection.ensureIndex() method with the sparse option set to true. For example, the following operation in the mongo shell creates a sparse index on the xmpp_id field of the addresses collection:

db.addresses.ensureIndex( { "xmpp_id": 1 }, { sparse: true } )

Note

Do not confuse sparse indexes in MongoDB with block-level [http://en.wikipedia.org/wiki/Database_index#Sparse_index] indexes in other databases. Think of them as dense indexes with a specific filter.

Behavior

sparse Index and Incomplete Results

Changed in version 2.6.

If a sparse index would result in an incomplete result set for queries and sort operations, MongoDB will not use that index unless a hint() explicitly specifies the index.

For example, the query { x: { $exists: false } } will not use a sparse index on the x field unless explicitly hinted. See Sparse Index On A Collection Cannot Return Complete Results for an example that details the behavior.

Indexes that are sparse by Default

2dsphere (version 2), 2d, geoHaystack, and text indexes are always sparse.

sparse Compound Indexes

Sparse compound indexes that only contain ascending/descending index keys will index a document as long as the document contains at least one of the keys.

For sparse compound indexes that contain a geospatial key (i.e. 2dsphere, 2d, or geoHaystack index keys) along with ascending/descending index key(s), only the existence of the geospatial field(s) in a document determine whether the index references the document.

For sparse compound indexes that contain text index keys along with ascending/descending index keys, only the existence of the text index field(s) determine whether the index references a document.

sparse and unique Properties

An index that is both sparse and unique prevents collection from having documents with duplicate values for a field but allows multiple documents that omit the key.

Examples

Create a Sparse Index On A Collection

Consider a collection scores that contains the following documents:

{ "_id" : ObjectId("523b6e32fb408eea0eec2647"), "userid" : "newbie" }
{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }
{ "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 }

The collection has a sparse index on the field score:

db.scores.ensureIndex( { score: 1 } , { sparse: true } )

Then, the following query on the scores collection uses the sparse index to return the documents that have the score field less than ($lt) 90:

db.scores.find( { score: { $lt: 90 } } )

Because the document for the userid "newbie" does not contain the score field and thus does not meet the query criteria, the query can use the sparse index to return the results:

{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }

Sparse Index On A Collection Cannot Return Complete Results

Consider a collection scores that contains the following documents:

{ "_id" : ObjectId("523b6e32fb408eea0eec2647"), "userid" : "newbie" }
{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }
{ "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 }

The collection has a sparse index on the field score:

db.scores.ensureIndex( { score: 1 } , { sparse: true } )

Because the document for the userid "newbie" does not contain the score field, the sparse index does not contain an entry for that document.

Consider the following query to return all documents in the scores collection, sorted by the score field:

db.scores.find().sort( { score: -1 } )

Even though the sort is by the indexed field, MongoDB will not select the sparse index to fulfill the query in order to return complete results:

{ "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 }
{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }
{ "_id" : ObjectId("523b6e32fb408eea0eec2647"), "userid" : "newbie" }

To use the sparse index, explicitly specify the index with hint():

db.scores.find().sort( { score: -1 } ).hint( { score: 1 } )

The use of the index results in the return of only those documents with the score field:

{ "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 }
{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }

See also

explain() and Analyze Query Performance

Sparse Index with Unique Constraint

Consider a collection scores that contains the following documents:

{ "_id" : ObjectId("523b6e32fb408eea0eec2647"), "userid" : "newbie" }
{ "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 }
{ "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 }

You could create an index with a unique constraint and sparse filter on the score field using the following operation:

db.scores.ensureIndex( { score: 1 } , { sparse: true, unique: true } )

This index would permit the insertion of documents that had unique values for the score field or did not include a score field. Consider the following insert operation:

db.scores.insert( { "userid": "AAAAAAA", "score": 43 } )
db.scores.insert( { "userid": "BBBBBBB", "score": 34 } )
db.scores.insert( { "userid": "CCCCCCC" } )
db.scores.insert( { "userid": "DDDDDDD" } )

However, the index would not permit the addition of the following documents since documents already exists with score value of 82 and 90:

db.scores.insert( { "userid": "AAAAAAA", "score": 82 } )
db.scores.insert( { "userid": "BBBBBBB", "score": 90 } )

Index Creation

MongoDB provides several options that only affect the creation of the index. Specify these options in a document as the second argument to the db.collection.ensureIndex() method. This section describes the uses of these creation options and their behavior.

Related

Some options that you can specify to ensureIndex() options control the properties of the index, which are not index creation options. For example, the unique option affects the behavior of the index after creation.

For a detailed description of MongoDB’s index types, see Index Types and Index Properties for related documentation.

Background Construction

By default, creating an index blocks all other operations on a database. When building an index on a collection, the database that holds the collection is unavailable for read or write operations until the index build completes. Any operation that requires a read or write lock on all databases (e.g. listDatabases) will wait for the foreground index build to complete.

For potentially long running index building operations, consider the background operation so that the MongoDB database remains available during the index building operation. For example, to create an index in the background of the zipcode field of the people collection, issue the following:

db.people.ensureIndex( { zipcode: 1}, {background: true} )

By default, background is false for building MongoDB indexes.

You can combine the background option with other options, as in the following:

db.people.ensureIndex( { zipcode: 1}, {background: true, sparse: true } )

Behavior

As of MongoDB version 2.4, a mongod instance can build more than one index in the background concurrently.

Changed in version 2.4: Before 2.4, a mongod instance could only build one background index per database at a time.

Changed in version 2.2: Before 2.2, a single mongod instance could only build one index at a time.

Background indexing operations run in the background so that other database operations can run while creating the index. However, the mongo shell session or connection where you are creating the index will block until the index build is complete. To continue issuing commands to the database, open another connection or mongo instance.

Queries will not use partially-built indexes: the index will only be usable once the index build is complete.

Note

If MongoDB is building an index in the background, you cannot perform other administrative operations involving that collection, including running repairDatabase, dropping the collection (i.e. db.collection.drop()), and running compact. These operations will return an error during background index builds.

Performance

The background index operation uses an incremental approach that is slower than the normal “foreground” index builds. If the index is larger than the available RAM, then the incremental process can take much longer than the foreground build.

If your application includes ensureIndex() operations, and an index doesn’t exist for other operational concerns, building the index can have a severe impact on the performance of the database.

To avoid performance issues, make sure that your application checks for the indexes at start up using the getIndexes() method or the equivalent method for your driver [http://api.mongodb.org/] and terminates if the proper indexes do not exist. Always build indexes in production instances using separate application code, during designated maintenance windows.

Building Indexes on Secondaries

Changed in version 2.6: Secondary members can now build indexes in the background. Previously all index builds on secondaries were in the foreground.

Background index operations on a replica set secondaries begin after the primary completes building the index. If MongoDB builds an index in the background on the primary, the secondaries will then build that index in the background.

To build large indexes on secondaries the best approach is to restart one secondary at a time in standalone mode and build the index. After building the index, restart as a member of the replica set, allow it to catch up with the other members of the set, and then build the index on the next secondary. When all the secondaries have the new index, step down the primary, restart it as a standalone, and build the index on the former primary.

The amount of time required to build the index on a secondary must be within the window of the oplog, so that the secondary can catch up with the primary.

Indexes on secondary members in “recovering” mode are always built in the foreground to allow them to catch up as soon as possible.

See Build Indexes on Replica Sets for a complete procedure for building indexes on secondaries.

Drop Duplicates

MongoDB cannot create a unique index on a field that has duplicate values. To force the creation of a unique index, you can specify the dropDups option, which will only index the first occurrence of a value for the key, and delete all subsequent values.

Important

As in all unique indexes, if a document does not have the indexed field, MongoDB will include it in the index with a “null” value.

If subsequent fields do not have the indexed field, and you have set {dropDups: true}, MongoDB will remove these documents from the collection when creating the index. If you combine dropDups with the sparse option, this index will only include documents in the index that have the value, and the documents without the field will remain in the database.

To create a unique index that drops duplicates on the username field of the accounts collection, use a command in the following form:

db.accounts.ensureIndex( { username: 1 }, { unique: true, dropDups: true } )

Warning

Specifying { dropDups: true } will delete data from your database. Use with extreme caution.

By default, dropDups is false.

Index Names

The default name for an index is the concatenation of the indexed keys and each key’s direction in the index, 1 or -1.

Example

Issue the following command to create an index on item and quantity:

db.products.ensureIndex( { item: 1, quantity: -1 } )

The resulting index is named: item_1_quantity_-1.

Optionally, you can specify a name for an index instead of using the default name.

Example

Issue the following command to create an index on item and quantity and specify inventory as the index name:

db.products.ensureIndex( { item: 1, quantity: -1 } , { name: "inventory" } )

The resulting index has the name inventory.

To view the name of an index, use the getIndexes() method.

Index Intersection

New in version 2.6.

MongoDB can use the intersection of multiple indexes to fulfill queries. [1] In general, each index intersection involves two indexes; however, MongoDB can employ multiple/nested index intersections to resolve a query.

To illustrate index intersection, consider a collection orders that has the following indexes:

{ qty: 1 }
{ item: 1 }

MongoDB can use the intersection of the two indexes to support the following query:

db.orders.find( { item: "abc123", qty: { $gt: 15 } } )

For query plans that use index intersection, the explain() returns the value Complex Plan in the cursor field.

[1]
In previous versions, MongoDB could use only a single index to fulfill most queries. The exception to this is queries with $or clauses, which could use a single index for each $or clause.

Index Prefix Intersection

With index intersection, MongoDB can use an intersection of either the entire index or the index prefix. An index prefix is a subset of a compound index, consisting of one or more keys starting from the beginning of the index.

Consider a collection orders with the following indexes:

{ qty: 1 }
{ status: 1, ord_date: -1 }

To fulfill the following query which specifies a condition on both the qty field and the status field, MongoDB can use the intersection of the two indexes:

db.orders.find( { qty: { $gt: 10 } , status: "A" } )

Index Intersection and Compound Indexes

Index intersection does not eliminate the need for creating compound indexes. However, because both the list order (i.e. the order in which the keys are listed in the index) and the sort order (i.e. ascending or descending), matter in compound indexes, a compound index may not support a query condition that does not include the index prefix keys or that specifies a different sort order.

For example, if a collection orders has the following compound index, with the status field listed before the ord_date field:

{ status: 1, ord_date: -1 }

The compound index can support the following queries:

db.orders.find( { status: { $in: ["A", "P" ] } } )
db.orders.find(
   {
     ord_date: { $gt: new Date("2014-02-01") },
     status: {$in:[ "P", "A" ] }
   }
)

But not the following two queries:

db.orders.find( { ord_date: { $gt: new Date("2014-02-01") } } )
db.orders.find( { } ).sort( { ord_date: 1 } )

However, if the collection has two separate indexes:

{ status: 1 }
{ ord_date: -1 }

The two indexes can, either individually or through index intersection, support all four aforementioned queries.

The choice between creating compound indexes that support your queries or relying on index intersection depends on the specifics of your system.

See also

compound indexes, Create Compound Indexes to Support Several Different Queries

Index Intersection and Sort

Index intersection does not apply when the sort() operation requires an index completely separate from the query predicate.

For example, the orders collection has the following indexes:

{ qty: 1 }
{ status: 1, ord_date: -1 }
{ status: 1 }
{ ord_date: -1 }

MongoDB cannot use index intersection for the following query with sort:

db.orders.find( { qty: { $gt: 10 } } ).sort( { status: 1 } )

That is, MongoDB does not use the { qty: 1 } index for the query, and the separate { status: 1 } or the { status: 1, ord_date: -1 } index for the sort.

However, MongoDB can use index intersection for the following query with sort since the index { status: 1, ord_date: -1 } can fulfill part of the query predicate.

db.orders.find( { qty: { $gt: 10 } , status: "A" } ).sort( { ord_date: -1 } )

Multikey Index Bounds

The bounds of an index scan define the portions of an index to search during a query. When multiple predicates over an index exist, MongoDB will attempt to combine the bounds for these predicates by either intersection or compounding in order to produce a scan with smaller bounds.

Intersect Bounds for Multikey Index

Bounds intersection refers to a logical conjunction (i.e. AND) of multiple bounds. For instance, given two bounds [ [ 3, Infinity ] ] and [ [ -Infinity, 6 ] ], the intersection of the bounds results in [ [ 3, 6 ] ].

Given an indexed array field, consider a query that specifies multiple predicates on the array and can use a multikey index. MongoDB can intersect multikey index bounds if an $elemMatch joins the predicates.

For example, a collection survey contains documents with a field item and an array field ratings:

{ _id: 1, item: "ABC", ratings: [ 2, 9 ] }
{ _id: 2, item: "XYZ", ratings: [ 4, 3 ] }

Create a multikey index on the ratings array:

db.survey.ensureIndex( { ratings: 1 } )

The following query uses $elemMatch to require that the array contains at least one single element that matches both conditions:

db.survey.find( { ratings : { $elemMatch: { $gte: 3, $lte: 6 } } } )

Taking the predicates separately:

the bounds for the greater than or equal to 3 predicate (i.e. $gte: 3) are [ [ 3, Infinity ] ];

the bounds for the less than or equal to 6 predicate (i.e. $lte: 6) are [ [ -Infinity, 6 ] ].

Because the query uses $elemMatch to join these predicates, MongoDB can intersect the bounds to:

ratings: [ [ 3, 6 ] ]

If the query does not join the conditions on the array field with $elemMatch, MongoDB cannot intersect the multikey index bounds. Consider the following query:

db.survey.find( { ratings : { $gte: 3, $lte: 6 } } )

The query searches the ratings array for at least one element greater than or equal to 3 and at least one element less than or equal to 6. Because a single element does not need to meet both criteria, MongoDB does not intersect the bounds and uses either [ [ 3, Infinity ] ] or [ [ -Infinity, 6 ] ]. MongoDB makes no guarantee as to which of these two bounds it chooses.

Compound Bounds for Multikey Index

Compounding bounds refers to using bounds for multiple keys of compound index. For instance, given a compound index { a: 1, b: 1 } with bounds on field a of [ [ 3, Infinity ] ] and bounds on field b of [ [ -Infinity, 6 ] ], compounding the bounds results in the use of both bounds:

{ a: [ [ 3, Infinity ] ], b: [ [ -Infinity, 6 ] ] }

If MongoDB cannot compound the two bounds, MongoDB always constrains the index scan by the bound on its leading field, in this case, a: [ [ 3, Infinity ] ].

Compound Index on an Array Field

Consider a compound multikey index; i.e. a compound index where one of the indexed fields is an array. For example, a collection survey contains documents with a field item and an array field ratings:

{ _id: 1, item: "ABC", ratings: [ 2, 9 ] }
{ _id: 2, item: "XYZ", ratings: [ 4, 3 ] }

Create a compound index on the item field and the ratings field:

db.survey.ensureIndex( { item: 1, ratings: 1 } )

The following query specifies a condition on both keys of the index:

db.survey.find( { item: "XYZ", ratings: { $gte: 3 } } )

Taking the predicates separately:

the bounds for the item: "XYZ" predicate are [ [ "XYZ", "XYZ" ] ];

the bounds for the ratings: { $gte: 3 } predicate are [ [ 3, Infinity ] ].

MongoDB can compound the two bounds to use the combined bounds of:

{ item: [ [ "XYZ", "XYZ" ] ], ratings: [ [ 3, Infinity ] ] }

Compound Index on Fields from an Array of Embedded Documents

If an array contains embedded documents, to index on fields contained in the embedded documents, use the dotted field name in the index specification. For instance, given the following array of embedded documents:

ratings: [ { score: 2, by: "mn" }, { score: 9, by: "anon" } ]

The dotted field name for the score field is "ratings.score".

Compound Bounds of Non-array Field and Field from an Array

Consider a collection survey2 contains documents with a field item and an array field ratings:

{
  _id: 1,
  item: "ABC",
  ratings: [ { score: 2, by: "mn" }, { score: 9, by: "anon" } ]
}
{
  _id: 2,
  item: "XYZ",
  ratings: [ { score: 5, by: "anon" }, { score: 7, by: "wv" } ]
}

Create a compound index on the non-array field item as well as two fields from an array ratings.score and ratings.by:

db.survey2.ensureIndex( { "item": 1, "ratings.score": 1, "ratings.by": 1 } )

The following query specifies a condition on all three fields:

db.survey2.find( { item: "XYZ",  "ratings.score": { $lte: 5 }, "ratings.by": "anon" } )

Taking the predicates separately:

the bounds for the item: "XYZ" predicate are [ [ "XYZ", "XYZ" ] ];

the bounds for the score: { $lte: 5 } predicate are [ [ -Infinity, 5 ] ];

the bounds for the by: "anon" predicate are [ "anon", "anon" ].

MongoDB can compound the bounds for the item key with either the bounds for "ratings.score" or the bounds for "ratings.by", depending upon the query predicates and the index key values. MongoDB makes no guarantee as to which bounds it compounds with the item field. For instance, MongoDB will either choose to compound the item bounds with the "ratings.score" bounds:

{
  "item" : [ [ "XYZ", "XYZ" ] ],
  "ratings.score" : [ [ -Infinity, 5 ] ],
  "ratings.by" : [ [ MinKey, MaxKey ] ]
}

Or, MongoDB may choose to compound the item bounds with "ratings.by" bounds:

{
  "item" : [ [ "XYZ", "XYZ" ] ],
  "ratings.score" : [ [ MinKey, MaxKey ] ],
  "ratings.by" : [ [ "anon", "anon" ] ]
}

However, to compound the bounds for "ratings.score" with the bounds for "ratings.by", the query must use $elemMatch. See Compound Bounds of Index Fields from an Array for more information.

Compound Bounds of Index Fields from an Array

To compound together the bounds for index keys from the same array:

the index keys must share the same field path up to but excluding the field names, and

the query must specify predicates on the fields using $elemMatch on that path.

For a field in an embedded document, the dotted field name, such as "a.b.c.d", is the field path for d. To compound the bounds for index keys from the same array, the $elemMatch must be on the path up to but excluding the field name itself; i.e. "a.b.c".

For instance, create a compound index on the ratings.score and the ratings.by fields:

db.survey2.ensureIndex( { "ratings.score": 1, "ratings.by": 1 } )

The fields "ratings.score" and "ratings.by" share the field path ratings. The following query uses $elemMatch on the field ratings to require that the array contains at least one single element that matches both conditions:

db.survey2.find( { ratings: { $elemMatch: { score: { $lte: 5 }, by: "anon" } } } )

Taking the predicates separately:

the bounds for the score: { $lte: 5 } predicate is [ -Infinity, 5 ];

the bounds for the by: "anon" predicate is [ "anon", "anon" ].

MongoDB can compound the two bounds to use the combined bounds of:

{ "ratings.score" : [ [ -Infinity, 5 ] ], "ratings.by" : [ [ "anon", "anon" ] ] }

Query Without $elemMatch

If the query does not join the conditions on the indexed array fields with $elemMatch, MongoDB cannot compound their bounds. Consider the following query:

db.survey2.find( { "ratings.score": { $lte: 5 }, "ratings.by": "anon" } )

Because a single embedded document in the array does not need to meet both criteria, MongoDB does not compound the bounds. When using a compound index, if MongoDB cannot constrain all the fields of the index, MongoDB always constrains the leading field of the index, in this case "ratings.score":

{
  "ratings.score": [ [ -Infinity, 5 ] ],
  "ratings.by": [ [ MinKey, MaxKey ] ]
}

$elemMatch on Incomplete Path

If the query does not specify $elemMatch on the path of the embedded fields, up to but excluding the field names, MongoDB cannot compound the bounds of index keys from the same array.

For example, a collection survey3 contains documents with a field item and an array field ratings:

{
  _id: 1,
  item: "ABC",
  ratings: [ { score: { q1: 2, q2: 5 } }, { score: { q1: 8, q2: 4 } } ]
}
{
  _id: 2,
  item: "XYZ",
  ratings: [ { score: { q1: 7, q2: 8 } }, { score: { q1: 9, q2: 5 } } ]
}

Create a compound index on the ratings.score.q1 and the ratings.score.q2 fields:

db.survey3.ensureIndex( { "ratings.score.q1": 1, "ratings.score.q2": 1 } )

The fields "ratings.score.q1" and "ratings.score.q2" share the field path "ratings.score" and the $elemMatch must be on that path.

The following query, however, uses an $elemMatch but not on the required path:

db.survey3.find( { ratings: { $elemMatch: { 'score.q1': 2, 'score.q2': 8 } } } )

As such, MongoDB cannot compound the bounds, and the "ratings.score.q2" field will be unconstrained during the index scan. To compound the bounds, the query must use $elemMatch on the path "ratings.score":

db.survey3.find( { 'ratings.score': { $elemMatch: { 'q1': 2, 'q2': 8 } } } )

Compound $elemMatch Clauses

Consider a query that contains multiple $elemMatch clauses on different field paths, for instance, "a.b": { $elemMatch: ... }, "a.c": { $elemMatch: ... }. MongoDB cannot combine the bounds of the "a.b" with the bounds of "a.c" since "a.b" and "a.c" also require $elemMatch on the path a.

For example, a collection survey4 contains documents with a field item and an array field ratings:

{
  _id: 1,
  item: "ABC",
  ratings: [
    { score: { q1: 2, q2: 5 }, certainty: { q1: 2, q2: 3 } },
    { score: { q1: 8, q2: 4 }, certainty: { q1: 10, q2: 10 } }
  ]
}
{
  _id: 2,
  item: "XYZ",
  ratings: [
    { score: { q1: 7, q2: 8 }, certainty: { q1: 5, q2: 5 } },
    { score: { q1: 9, q2: 5 }, certainty: { q1: 7, q2: 7 } }
  ]
}

Create a compound index on the ratings.score.q1 and the ratings.score.q2 fields:

db.survey4.ensureIndex( {
   "ratings.score.q1": 1,
   "ratings.score.q2": 1,
   "ratings.certainty.q1": 1,
   "ratings.certainty.q2": 1
} )

Consider the following query with two $elemMatch clauses:

db.survey4.find(
  {
    "ratings.score": { $elemMatch: { q1: 5, q2: 5 } },
    "ratings.certainty": { $elemMatch: { q1: 7, q2: 7 } },
  }
)

Taking the predicates separately:

the bounds for the "ratings.score" predicate are the compound bounds:

{ "ratings.score.q1" : [ [ 5, 5 ] ], "ratings.score.q2" : [ [ 5, 5 ] ] }

the bounds for the "ratings.certainty" predicate are the compound bounds:

{ "ratings.certainty.q1" : [ [ 7, 7 ] ], "ratings.certainty.q2" : [ [ 7, 7 ] ] }

However, MongoDB cannot compound the bounds for "ratings.score" and "ratings.certainty" since $elemMatch does not join the two. Instead, MongoDB constrains the leading field of the index "ratings.score.q1" which can be compounded with the bounds for "ratings.score.q2":

{
  "ratings.score.q1" : [ [ 5, 5 ] ],
  "ratings.score.q2" : [ [ 5, 5 ] ],
  "ratings.certainty.q1" : [ [ MinKey, MaxKey ] ],
  "ratings.certainty.q2" : [ [ MinKey, MaxKey ] ]
}

Indexing Tutorials

Indexes allow MongoDB to process and fulfill queries quickly by creating small and efficient representations of the documents in a collection.

The documents in this section outline specific tasks related to building and maintaining indexes for data in MongoDB collections and discusses strategies and practical approaches. For a conceptual overview of MongoDB indexing, see the Index Concepts document.

Index Creation Tutorials

Create and configure different types of indexes for different purposes.

Index Management Tutorials

Monitor and assess index performance and rebuild indexes as needed.

Geospatial Index Tutorials

Create indexes that support data stored as GeoJSON objects and legacy coordinate pairs.

Text Search Tutorials

Build and configure indexes that support full-text searches.

Indexing Strategies

The factors that affect index performance and practical approaches to indexing in MongoDB

Index Creation Tutorials

Create an Index

Create a Compound Index

Create a Unique Index

Create a Sparse Index

Create a Hashed Index

Build Indexes on Replica Sets

Build Indexes in the Background

Build Old Style Indexes

Index Management Tutorials

Remove Indexes

Modify an Index

Rebuild Indexes

Manage In-Progress Index Creation

Return a List of All Indexes

Measure Index Use

Geospatial Index Tutorials

Create a 2dsphere Index

Query a 2dsphere Index

Create a 2d Index

Query a 2d Index

Create a Haystack Index

Query a Haystack Index

Calculate Distance Using Spherical Geometry

Text Search Tutorials

Create a text Index

Specify a Language for Text Index

Specify Name for text Index

Control Search Results with Weights

Limit the Number of Entries Scanned

Text Search in the Aggregation Pipeline

Indexing Strategies

Create Indexes to Support Your Queries

Use Indexes to Sort Query Results

Ensure Indexes Fit in RAM

Create Queries that Ensure Selectivity

Index Creation Tutorials

Instructions for creating and configuring indexes in MongoDB and building indexes on replica sets and sharded clusters.

Create an Index

Build an index for any field on a collection.

Create a Compound Index

Build an index of multiple fields on a collection.

Create a Unique Index

Build an index that enforces unique values for the indexed field or fields.

Create a Sparse Index

Build an index that omits references to documents that do not include the indexed field. This saves space when indexing fields that are present in only some documents.

Create a Hashed Index

Compute a hash of the value of a field in a collection and index the hashed value. These indexes permit equality queries and may be suitable shard keys for some collections.

Build Indexes on Replica Sets

To build indexes on a replica set, you build the indexes separately on the primary and the secondaries, as described here.

Build Indexes in the Background

Background index construction allows read and write operations to continue while building the index, but take longer to complete and result in a larger index.

Build Old Style Indexes

A {v : 0} index is necessary if you need to roll back from MongoDB version 2.0 (or later) to MongoDB version 1.8.

Create an Index

Create a Compound Index

Create a Unique Index

Create a Sparse Index

Create a Hashed Index

Build Indexes on Replica Sets

Build Indexes in the Background

Build Old Style Indexes

Create an Index

Indexes allow MongoDB to process and fulfill queries quickly by creating small and efficient representations of the documents in a collection. Users can create indexes for any collection on any field in a document. By default, MongoDB creates an index on the _id field of every collection.

This tutorial describes how to create an index on a single field. MongoDB also supports compound indexes, which are indexes on multiple fields. See Create a Compound Index for instructions on building compound indexes.

Create an Index on a Single Field

To create an index, use ensureIndex() or a similar method from your driver [http://api.mongodb.org/]. The ensureIndex() method only creates an index if an index of the same specification does not already exist.

For example, the following operation creates an index on the userid field of the records collection:

db.records.ensureIndex( { userid: 1 } )

The value of the field in the index specification describes the kind of index for that field. For example, a value of 1 specifies an index that orders items in ascending order. A value of -1 specifies an index that orders items in descending order. For additional index types, see Index Types.

The created index will support queries that select on the field userid, such as the following:

db.records.find( { userid: 2 } )
db.records.find( { userid: { $gt: 10 } } )

But the created index does not support the following query on the profile_url field:

db.records.find( { profile_url: 2 } )

For queries that cannot use an index, MongoDB must scan all documents in a collection for documents that match the query.

Additional Considerations

Although indexes can improve query performances, indexes also present some operational considerations. See Operational Considerations for Indexes for more information.

If your collection holds a large amount of data, and your application needs to be able to access the data while building the index, consider building the index in the background, as described in Background Construction. To build indexes on replica sets, see the Build Indexes on Replica Sets section for more information.

Note

To build or rebuild indexes for a replica set see Build Indexes on Replica Sets.

Some drivers may specify indexes, using NumberLong(1) rather than 1 as the specification. This does not have any affect on the resulting index.

See also

Create a Compound Index, Indexing Tutorials and Index Concepts for more information.

Create a Compound Index

Indexes allow MongoDB to process and fulfill queries quickly by creating small and efficient representations of the documents in a collection. MongoDB supports indexes that include content on a single field, as well as compound indexes that include content from multiple fields. Continue reading for instructions and examples of building a compound index.

Build a Compound Index

To create a compound index use an operation that resembles the following prototype:

db.collection.ensureIndex( { a: 1, b: 1, c: 1 } )

The value of the field in the index specification describes the kind of index for that field. For example, a value of 1 specifies an index that orders items in ascending order. A value of -1 specifies an index that orders items in descending order. For additional index types, see Index Types.

Example

The following operation will create an index on the item, category, and price fields of the products collection:

db.products.ensureIndex( { item: 1, category: 1, price: 1 } )

Additional Considerations

If your collection holds a large amount of data, and your application needs to be able to access the data while building the index, consider building the index in the background, as described in Background Construction. To build indexes on replica sets, see the Build Indexes on Replica Sets section for more information.

Note

To build or rebuild indexes for a replica set see Build Indexes on Replica Sets.

Some drivers may specify indexes, using NumberLong(1) rather than 1 as the specification. This does not have any affect on the resulting index.

See also

Create an Index, Indexing Tutorials and Index Concepts for more information.

Create a Unique Index

MongoDB allows you to specify a unique constraint on an index. These constraints prevent applications from inserting documents that have duplicate values for the inserted fields. Additionally, if you want to create an index on a collection that has existing data that might have duplicate values for the indexed field, you may choose to combine unique enforcement with duplicate dropping.

Unique Indexes

To create a unique index, consider the following prototype:

db.collection.ensureIndex( { a: 1 }, { unique: true } )

For example, you may want to create a unique index on the "tax-id": of the accounts collection to prevent storing multiple account records for the same legal entity:

db.accounts.ensureIndex( { "tax-id": 1 }, { unique: true } )

The _id index is a unique index. In some situations you may consider using the _id field itself for this kind of data rather than using a unique index on another field.

If a document does not have a value for a field, the index entry for that item will be null in any index that includes it. Thus, in many situations you will want to combine the unique constraint with the sparse option. Sparse indexes skip over any document that is missing the indexed field, rather than storing null for the index entry. Since unique indexes cannot have duplicate values for a field, without the sparse option, MongoDB will reject the second document and all subsequent documents without the indexed field. Consider the following prototype.

db.collection.ensureIndex( { a: 1 }, { unique: true, sparse: true } )

You can also enforce a unique constraint on compound indexes, as in the following prototype:

db.collection.ensureIndex( { a: 1, b: 1 }, { unique: true } )

These indexes enforce uniqueness for the combination of index keys and not for either key individually.

Drop Duplicates

To force the creation of a unique index index on a collection with duplicate values in the field you are indexing you can use the dropDups option. This will force MongoDB to create a unique index by deleting documents with duplicate values when building the index. Consider the following prototype invocation of ensureIndex():

db.collection.ensureIndex( { a: 1 }, { unique: true, dropDups: true } )

See the full documentation of duplicate dropping for more information.

Warning

Specifying { dropDups: true } may delete data from your database. Use with extreme caution.

Refer to the ensureIndex() documentation for additional index creation options.

Create a Sparse Index

Sparse indexes are like non-sparse indexes, except that they omit references to documents that do not include the indexed field. For fields that are only present in some documents sparse indexes may provide a significant space savings. See Sparse Indexes for more information about sparse indexes and their use.

See also

Index Concepts and Indexing Tutorials for more information.

Prototype

To create a sparse index on a field, use an operation that resembles the following prototype:

db.collection.ensureIndex( { a: 1 }, { sparse: true } )

Example

The following operation, creates a sparse index on the users collection that only includes a document in the index if the twitter_name field exists in a document.

db.users.ensureIndex( { twitter_name: 1 }, { sparse: true } )

The index excludes all documents that do not include the twitter_name field.

Considerations

Note

Sparse indexes can affect the results returned by the query, particularly with respect to sorts on fields not included in the index. See the sparse index section for more information.

Create a Hashed Index

New in version 2.4.

Hashed indexes compute a hash of the value of a field in a collection and index the hashed value. These indexes permit equality queries and may be suitable shard keys for some collections.

Tip

MongoDB automatically computes the hashes when resolving queries using hashed indexes. Applications do not need to compute hashes.

See

Hashed Shard Keys for more information about hashed indexes in sharded clusters, as well as Index Concepts and Indexing Tutorials for more information about indexes.

Procedure

To create a hashed index, specify hashed as the value of the index key, as in the following example:

Example

Specify a hashed index on _id

db.collection.ensureIndex( { _id: "hashed" } )

Considerations

MongoDB supports hashed indexes of any single field. The hashing function collapses embedded documents and computes the hash for the entire value, but does not support multi-key (i.e. arrays) indexes.

You may not create compound indexes that have hashed index fields.

Build Indexes on Replica Sets

For replica sets, secondaries will begin building indexes after the primary finishes building the index. In sharded clusters, the mongos will send ensureIndex() to the primary members of the replica set for each shard, which then replicate to the secondaries after the primary finishes building the index.

To minimize the impact of building an index on your replica set, use the following procedure to build indexes:

See

Indexing Tutorials and Index Concepts for more information.

Considerations

Ensure that your oplog is large enough to permit the indexing or re-indexing operation to complete without falling too far behind to catch up. See the oplog sizing documentation for additional information.

This procedure does take one member out of the replica set at a time. However, this procedure will only affect one member of the set at a time rather than all secondaries at the same time.

Do not use this procedure when building a unique index with the dropDups option.

Before version 2.6 Background index creation operations become foreground indexing operations on secondary members of replica sets. After 2.6, background index builds replicate as background index builds on the secondaries.

Procedure

Note

If you need to build an index in a sharded cluster, repeat the following procedure for each replica set that provides each shard.

Stop One Secondary

Stop the mongod process on one secondary. Restart the mongod process without the --replSet option and running on a different port. [1] This instance is now in “standalone” mode.

For example, if your mongod normally runs with on the default port of 27017 with the --replSet option you would use the following invocation:

mongod --port 47017

[1]
By running the mongod on a different port, you ensure that the other members of the replica set and all clients will not contact the member while you are building the index.

Build the Index

Create the new index using the ensureIndex() in the mongo shell, or comparable method in your driver. This operation will create or rebuild the index on this mongod instance

For example, to create an ascending index on the username field of the records collection, use the following mongo shell operation:

db.records.ensureIndex( { username: 1 } )

See also

Create an Index and Create a Compound Index for more information.

Restart the Program mongod

When the index build completes, start the mongod instance with the --replSet option on its usual port:

mongod --port 27017 --replSet rs0

Modify the port number (e.g. 27017) or the replica set name (e.g. rs0) as needed.

Allow replication to catch up on this member.

Build Indexes on all Secondaries

Changed in version 2.6: Secondary members can now build indexes in the background. Previously all index builds on secondaries were in the foreground.

For each secondary in the set, build an index according to the following steps:

Stop One Secondary

Build the Index

Restart the Program mongod

Build the Index on the Primary

To build an index on the primary you can either:

Build the index in the background on the primary.

Step down the primary using the rs.stepDown() method in the mongo shell to cause the current primary to become a secondary graceful and allow the set to elect another member as primary.

Then repeat the index building procedure, listed below, to build the index on the primary:

Stop One Secondary

Build the Index

Restart the Program mongod

Building the index in the background takes longer than the foreground index build and results in a less compact index structure. Additionally, the background index build may impact write performance on the primary. However, building the index in the background allows the set to be continuously up for write operations during while MongoDB builds the index.

Build Indexes in the Background

By default, MongoDB builds indexes in the foreground, which prevents all read and write operations to the database while the index builds. Also, no operation that requires a read or write lock on all databases (e.g. listDatabases) can occur during a foreground index build.

Background index construction allows read and write operations to continue while building the index.

See also

Index Concepts and Indexing Tutorials for more information.

Considerations

Background index builds take longer to complete and result in an index that is initially larger, or less compact, than an index built in the foreground. Over time, the compactness of indexes built in the background will approach foreground-built indexes.

After MongoDB finishes building the index, background-built indexes are functionally identical to any other index.

Procedure

To create an index in the background, add the background argument to the ensureIndex() operation, as in the following index:

db.collection.ensureIndex( { a: 1 }, { background: true } )

Consider the section on background index construction for more information about these indexes and their implications.

Build Old Style Indexes

Important

Use this procedure only if you must have indexes that are compatible with a version of MongoDB earlier than 2.0.

MongoDB version 2.0 introduced the {v:1} index format. MongoDB versions 2.0 and later support both the {v:1} format and the earlier {v:0} format.

MongoDB versions prior to 2.0, however, support only the {v:0} format. If you need to roll back MongoDB to a version prior to 2.0, you must drop and re-create your indexes.

To build pre-2.0 indexes, use the dropIndexes() and ensureIndex() methods. You cannot simply reindex the collection. When you reindex on versions that only support {v:0} indexes, the v fields in the index definition still hold values of 1, even though the indexes would now use the {v:0} format. If you were to upgrade again to version 2.0 or later, these indexes would not work.

Example

Suppose you rolled back from MongoDB 2.0 to MongoDB 1.8, and suppose you had the following index on the items collection:

{ "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.items", "name" : "name_1" }

The v field tells you the index is a {v:1} index, which is incompatible with version 1.8.

To drop the index, issue the following command:

db.items.dropIndex( { name : 1 } )

To recreate the index as a {v:0} index, issue the following command:

db.foo.ensureIndex( { name : 1 } , { v : 0 } )

See also

Index Performance Enhancements.

Index Management Tutorials

Instructions for managing indexes and assessing index performance and use.

Remove Indexes

Drop an index from a collection.

Modify an Index

Modify an existing index.

Rebuild Indexes

In a single operation, drop all indexes on a collection and then rebuild them.

Manage In-Progress Index Creation

Check the status of indexing progress, or terminate an ongoing index build.

Return a List of All Indexes

Obtain a list of all indexes on a collection or of all indexes on all collections in a database.

Measure Index Use

Study query operations and observe index use for your database.

Remove Indexes

Modify an Index

Rebuild Indexes

Manage In-Progress Index Creation

Return a List of All Indexes

Measure Index Use

Remove Indexes

To remove an index from a collection use the dropIndex() method and the following procedure. If you simply need to rebuild indexes you can use the process described in the Rebuild Indexes document.

See also

Indexing Tutorials and Index Concepts for more information about indexes and indexing operations in MongoDB.

Remove a Specific Index

To remove an index, use the db.collection.dropIndex() method.

For example, the following operation removes an ascending index on the tax-id field in the accounts collection:

db.accounts.dropIndex( { "tax-id": 1 } )

The operation returns a document with the status of the operation:

{ "nIndexesWas" : 3, "ok" : 1 }

Where the value of nIndexesWas reflects the number of indexes before removing this index.

For text indexes, pass the index name to the db.collection.dropIndex() method. See Use the Index Name to Drop a text Index for details.

Remove All Indexes

You can also use the db.collection.dropIndexes() to remove all indexes, except for the _id index from a collection.

These shell helpers provide wrappers around the dropIndexes database command. Your client library may have a different or additional interface for these operations.

Modify an Index

To modify an existing index, you need to drop and recreate the index.

1

Create a unique index.

Use the ensureIndex() method create a unique index.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 },
   { unique: true }
)

The method returns a document with the status of the results. The method only creates an index if the index does not already exist. See Create an Index and Index Creation Tutorials for more information on creating indexes.

Step 1: Create a unique index.

Use the ensureIndex() method create a unique index.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 },
   { unique: true }
)

The method returns a document with the status of the results. The method only creates an index if the index does not already exist. See Create an Index and Index Creation Tutorials for more information on creating indexes.

2

Attempt to modify the index.

To modify an existing index, you cannot just re-issue the ensureIndex() method with the updated specification of the index.

For example, the following operation attempts to remove the unique constraint from the previously created index by using the ensureIndex() method.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The status document returned by the operation shows an error.

Step 2: Attempt to modify the index.

To modify an existing index, you cannot just re-issue the ensureIndex() method with the updated specification of the index.

For example, the following operation attempts to remove the unique constraint from the previously created index by using the ensureIndex() method.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The status document returned by the operation shows an error.

3

Drop the index.

To modify the index, you must drop the index first.

db.orders.dropIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The method returns a document with the status of the operation. Upon successful operation, the ok field in the returned document should specify a 1. See Remove Indexes for more information about dropping indexes.

Step 3: Drop the index.

To modify the index, you must drop the index first.

db.orders.dropIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The method returns a document with the status of the operation. Upon successful operation, the ok field in the returned document should specify a 1. See Remove Indexes for more information about dropping indexes.

4

Recreate the index without the unique constraint.

Recreate the index without the unique constraint.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The method returns a document with the status of the results. Upon successful operation, the returned document should show the numIndexesAfter to be greater than numIndexesBefore by one.

Step 4: Recreate the index without the unique constraint.

Recreate the index without the unique constraint.

db.orders.ensureIndex(
   { "cust_id" : 1, "ord_date" : -1, "items" : 1 }
)

The method returns a document with the status of the results. Upon successful operation, the returned document should show the numIndexesAfter to be greater than numIndexesBefore by one.

See also

Index Introduction, Index Concepts.

Rebuild Indexes

If you need to rebuild indexes for a collection you can use the db.collection.reIndex() method to rebuild all indexes on a collection in a single operation. This operation drops all indexes, including the _id index, and then rebuilds all indexes.

See also

Index Concepts and Indexing Tutorials.

Process

The operation takes the following form:

db.accounts.reIndex()

MongoDB will return the following document when the operation completes:

{
        "nIndexesWas" : 2,
        "msg" : "indexes dropped for collection",
        "nIndexes" : 2,
        "indexes" : [
                {
                        "key" : {
                                "_id" : 1,
                                "tax-id" : 1
                        },
                        "ns" : "records.accounts",
                        "name" : "_id_"
                }
        ],
        "ok" : 1
}

This shell helper provides a wrapper around the reIndex database command. Your client library may have a different or additional interface for this operation.

Additional Considerations

Note

To build or rebuild indexes for a replica set see Build Indexes on Replica Sets.

Manage In-Progress Index Creation

View Index Creation Operations

To see the status of an indexing process, you can use the db.currentOp() method in the mongo shell. To filter the current operations for index creation operations, see Active Indexing Operations for an example.

The msg field will include the percent of the build that is complete.

Terminate Index Creation

To terminate an ongoing index build, use the db.killOp() method in the mongo shell. For index builds, the effects of db.killOp() may not be immediate and may occur well after much of the index build operation has completed.

You cannot terminate a replicated index build on secondary members of a replica set. To minimize the impact of building an index on replica sets, see Build Indexes on Replica Sets.

Changed in version 2.4: Before MongoDB 2.4, you could only terminate background index builds. After 2.4, you can terminate both background index builds and foreground index builds.

See also

db.currentOp(), db.killOp()

Return a List of All Indexes

When performing maintenance you may want to check which indexes exist on a collection. Every index on a collection has a corresponding document in the system.indexes collection, and you can use standard queries (i.e. find()) to list the indexes, or in the mongo shell, the getIndexes() method to return a list of the indexes on a collection, as in the following examples.

See also

Index Concepts and Indexing Tutorials for more information about indexes in MongoDB and common index management operations.

List all Indexes on a Collection

To return a list of all indexes on a collection, use the db.collection.getIndexes() method or a similar method for your driver [http://api.mongodb.org/].

For example, to view all indexes on the people collection:

db.people.getIndexes()

List all Indexes for a Database

To return a list of all indexes on all collections in a database, use the following operation in the mongo shell:

db.system.indexes.find()

See system.indexes for more information about these documents.

Measure Index Use

Synopsis

Query performance is a good general indicator of index use; however, for more precise insight into index use, MongoDB provides a number of tools that allow you to study query operations and observe index use for your database.

See also

Index Concepts and Indexing Tutorials for more information.

Operations

Return Query Plan with explain()

Append the explain() method to any cursor (e.g. query) to return a document with statistics about the query process, including the index used, the number of documents scanned, and the time the query takes to process in milliseconds.

Control Index Use with hint()

Append the hint() to any cursor (e.g. query) with the index as the argument to force MongoDB to use a specific index to fulfill the query. Consider the following example:

db.people.find( { name: "John Doe", zipcode: { $gt: "63000" } } ).hint( { zipcode: 1 } )

You can use hint() and explain() in conjunction with each other to compare the effectiveness of a specific index. Specify the $natural operator to the hint() method to prevent MongoDB from using any index:

db.people.find( { name: "John Doe", zipcode: { $gt: "63000" } } ).hint( { $natural: 1 } )

Instance Index Use Reporting

MongoDB provides a number of metrics of index use and operation that you may want to consider when analyzing index use for your database:

In the output of serverStatus:

indexCounters

scanned

scanAndOrder

In the output of collStats:

totalIndexSize

indexSizes

In the output of dbStats:

dbStats.indexes

dbStats.indexSize

Geospatial Index Tutorials

Instructions for creating and querying 2d, 2dsphere, and haystack indexes.

Create a 2dsphere Index

A 2dsphere index supports data stored as both GeoJSON objects and as legacy coordinate pairs.

Query a 2dsphere Index

Search for locations within, near, or intersected by a GeoJSON shape, or within a circle as defined by coordinate points on a sphere.

Create a 2d Index

Create a 2d index to support queries on data stored as legacy coordinate pairs.

Query a 2d Index

Search for locations using legacy coordinate pairs.

Create a Haystack Index

A haystack index is optimized to return results over small areas. For queries that use spherical geometry, a 2dsphere index is a better option.

Query a Haystack Index

Search based on location and non-location data within a small area.

Calculate Distance Using Spherical Geometry

Convert distances to radians and back again.

Create a 2dsphere Index

Query a 2dsphere Index

Create a 2d Index

Query a 2d Index

Create a Haystack Index

Query a Haystack Index

Calculate Distance Using Spherical Geometry

Create a 2dsphere Index

To create a geospatial index for GeoJSON-formatted data, use the db.collection.ensureIndex() method to create a 2dsphere index. In the index specification document for the db.collection.ensureIndex() method, specify the location field as the index key and specify the string literal "2dsphere" as the value:

db.collection.ensureIndex( { <location field> : "2dsphere" } )

The following procedure presents steps to populate a collection with documents that contain a GeoJSON data field and create 2dsphere indexes. Although the procedure populates the collection first, you can also create the indexes before populating the collection.

Procedure

First, populate a collection places with documents that store location data as GeoJSON Point in a field named loc. The coordinate order is longitude, then latitude.

db.places.insert(
   {
      loc : { type: "Point", coordinates: [ -73.97, 40.77 ] },
      name: "Central Park",
      category : "Parks"
   }
)

db.places.insert(
   {
      loc : { type: "Point", coordinates: [ -73.88, 40.78 ] },
      name: "La Guardia Airport",
      category : "Airport"
   }
)

Then, create the 2dsphere index.

Create a 2dsphere Index

For example, the following creates a 2dsphere index on the location field loc:

db.places.ensureIndex( { loc : "2dsphere" } )

Create a Compound Index with 2dsphere Index Key

A compound index can include a 2dsphere index key in combination with non-geospatial index keys. For example, the following operation creates a compound index where the first key loc is a 2dsphere index key, and the remaining keys category and names are non-geospatial index keys, specifically descending (-1) and ascending (1) keys respectively.

db.places.ensureIndex( { loc : "2dsphere" , category : -1, name: 1 } )

Unlike the 2d index, a compound 2dsphere index does not require the location field to be the first field indexed. For example:

db.places.ensureIndex( { category : 1 , loc : "2dsphere" } )

Considerations

The geoNear command and the $geoNear pipeline stage require that a collection have at most only one 2dsphere index and/or only one 2d index whereas geospatial query operators (e.g. $near and $geoWithin) permit collections to have multiple geospatial indexes.

The geospatial index restriction for the geoNear command and the $geoNear pipeline stage exists because neither the geoNear command nor the $geoNear pipeline stage syntax includes the location field. As such, index selection among multiple 2d indexes or 2dsphere indexes is ambiguous.

No such restriction applies for geospatial query operators since these operators take a location field, eliminating the ambiguity.

As such, although this tutorial creates multiple 2dsphere indexes, to use the geoNear command or the $geoNear pipeline stage against the example collection, you will need to drop all but one of the 2dsphere indexes.

To query using the 2dsphere index, see Query a 2dsphere Index.

Query a 2dsphere Index

The following sections describe queries supported by the 2dsphere index. For an overview of recommended geospatial queries, see Geospatial Query Compatibility.

GeoJSON Objects Bounded by a Polygon

The $geoWithin operator queries for location data found within a GeoJSON polygon. Your location data must be stored in GeoJSON format. Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                           { $geometry :
                             { type : "Polygon" ,
                               coordinates : [ <coordinates> ]
                      } } } } )

The following example selects all points and shapes that exist entirely within a GeoJSON polygon:

db.places.find( { loc :
                  { $geoWithin :
                    { $geometry :
                      { type : "Polygon" ,
                        coordinates : [ [
                                          [ 0 , 0 ] ,
                                          [ 3 , 6 ] ,
                                          [ 6 , 1 ] ,
                                          [ 0 , 0 ]
                                        ] ]
                } } } } )

Intersections of GeoJSON Objects

New in version 2.4.

The $geoIntersects operator queries for locations that intersect a specified GeoJSON object. A location intersects the object if the intersection is non-empty. This includes documents that have a shared edge.

The $geoIntersects operator uses the following syntax:

db.<collection>.find( { <location field> :
                         { $geoIntersects :
                           { $geometry :
                             { type : "<GeoJSON object type>" ,
                               coordinates : [ <coordinates> ]
                      } } } } )

The following example uses $geoIntersects to select all indexed points and shapes that intersect with the polygon defined by the coordinates array.

db.places.find( { loc :
                  { $geoIntersects :
                    { $geometry :
                      { type : "Polygon" ,
                        coordinates: [ [
                                         [ 0 , 0 ] ,
                                         [ 3 , 6 ] ,
                                         [ 6 , 1 ] ,
                                         [ 0 , 0 ]
                                       ] ]
                } } } } )

Proximity to a GeoJSON Point

Proximity queries return the points closest to the defined point and sorts the results by distance. A proximity query on GeoJSON data requires a 2dsphere index.

To query for proximity to a GeoJSON point, use either the $near operator or geoNear command. Distance is in meters.

The $near uses the following syntax:

db.<collection>.find( { <location field> :
                         { $near :
                           { $geometry :
                              { type : "Point" ,
                                coordinates : [ <longitude> , <latitude> ] } ,
                             $maxDistance : <distance in meters>
                      } } } )

For examples, see $near.

The geoNear command uses the following syntax:

db.runCommand( { geoNear : <collection> ,
              near : { type : "Point" ,
                       coordinates: [ <longitude>, <latitude> ] } ,
              spherical : true } )

The geoNear command offers more options and returns more information than does the $near operator. To run the command, see geoNear.

Points within a Circle Defined on a Sphere

To select all grid coordinates in a “spherical cap” on a sphere, use $geoWithin with the $centerSphere operator. Specify an array that contains:

The grid coordinates of the circle’s center point

The circle’s radius measured in radians. To calculate radians, see Calculate Distance Using Spherical Geometry.

Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                           { $centerSphere :
                              [ [ <x>, <y> ] , <radius> ] }
                      } } )

The following example queries grid coordinates and returns all documents within a 10 mile radius of longitude 88 W and latitude 30 N. The example converts the distance, 10 miles, to radians by dividing by the approximate radius of the earth, 3959 miles:

db.places.find( { loc :
                  { $geoWithin :
                    { $centerSphere :
                       [ [ -88 , 30 ] , 10 / 3959 ]
                } } } )

Create a 2d Index

To build a geospatial 2d index, use the ensureIndex() method and specify 2d. Use the following syntax:

db.<collection>.ensureIndex( { <location field> : "2d" ,
                               <additional field> : <value> } ,
                             { <index-specification options> } )

The 2d index uses the following optional index-specification options:

{ min : <lower bound> , max : <upper bound> ,
  bits : <bit precision> }

Define Location Range for a 2d Index

By default, a 2d index assumes longitude and latitude and has boundaries of -180 inclusive and 180 non-inclusive. If documents contain coordinate data outside of the specified range, MongoDB returns an error.

Important

The default boundaries allow applications to insert documents with invalid latitudes greater than 90 or less than -90. The behavior of geospatial queries with such invalid points is not defined.

On 2d indexes you can change the location range.

You can build a 2d geospatial index with a location range other than the default. Use the min and max options when creating the index. Use the following syntax:

db.collection.ensureIndex( { <location field> : "2d" } ,
                           { min : <lower bound> , max : <upper bound> } )

Define Location Precision for a 2d Index

By default, a 2d index on legacy coordinate pairs uses 26 bits of precision, which is roughly equivalent to 2 feet or 60 centimeters of precision using the default range of -180 to 180. Precision is measured by the size in bits of the geohash values used to store location data. You can configure geospatial indexes with up to 32 bits of precision.

Index precision does not affect query accuracy. The actual grid coordinates are always used in the final query processing. Advantages to lower precision are a lower processing overhead for insert operations and use of less space. An advantage to higher precision is that queries scan smaller portions of the index to return results.

To configure a location precision other than the default, use the bits option when creating the index. Use following syntax:

db.<collection>.ensureIndex( {<location field> : "<index type>"} ,
                             { bits : <bit precision> } )

For information on the internals of geohash values, see Calculation of Geohash Values for 2d Indexes.

Query a 2d Index

The following sections describe queries supported by the 2d index. For an overview of recommended geospatial queries, see Geospatial Query Compatibility.

Points within a Shape Defined on a Flat Surface

To select all legacy coordinate pairs found within a given shape on a flat surface, use the $geoWithin operator along with a shape operator. Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                            { $box|$polygon|$center : <coordinates>
                      } } } )

The following queries for documents within a rectangle defined by [ 0 , 0 ] at the bottom left corner and by [ 100 , 100 ] at the top right corner.

db.places.find( { loc :
                  { $geoWithin :
                     { $box : [ [ 0 , 0 ] ,
                                [ 100 , 100 ] ]
                 } } } )

The following queries for documents that are within the circle centered on [ -74 , 40.74 ] and with a radius of 10:

db.places.find( { loc: { $geoWithin :
                          { $center : [ [-74, 40.74 ] , 10 ]
                } } } )

For syntax and examples for each shape, see the following:

$box

$polygon

$center (defines a circle)

Points within a Circle Defined on a Sphere

MongoDB supports rudimentary spherical queries on flat 2d indexes for legacy reasons. In general, spherical calculations should use a 2dsphere index, as described in 2dsphere Indexes.

To query for legacy coordinate pairs in a “spherical cap” on a sphere, use $geoWithin with the $centerSphere operator. Specify an array that contains:

The grid coordinates of the circle’s center point

The circle’s radius measured in radians. To calculate radians, see Calculate Distance Using Spherical Geometry.

Use the following syntax:

db.<collection>.find( { <location field> :
                         { $geoWithin :
                            { $centerSphere : [ [ <x>, <y> ] , <radius> ] }
                      } } )

The following example query returns all documents within a 10-mile radius of longitude 88 W and latitude 30 N. The example converts distance to radians by dividing distance by the approximate radius of the earth, 3959 miles:

db.<collection>.find( { loc : { $geoWithin :
                                 { $centerSphere :
                                    [ [ 88 , 30 ] , 10 / 3959 ]
                      } } } )

Proximity to a Point on a Flat Surface

Proximity queries return the 100 legacy coordinate pairs closest to the defined point and sort the results by distance. Use either the $near operator or geoNear command. Both require a 2d index.

The $near operator uses the following syntax:

db.<collection>.find( { <location field> :
                         { $near : [ <x> , <y> ]
                      } } )

For examples, see $near.

The geoNear command uses the following syntax:

db.runCommand( { geoNear: <collection>, near: [ <x> , <y> ] } )

The geoNear command offers more options and returns more information than does the $near operator. To run the command, see geoNear.

Exact Matches on a Flat Surface

Changed in version 2.6: Previously, 2d indexes would support exact-match queries for coordinate pairs.

You cannot use a 2d index to return an exact match for a coordinate pair. Use a scalar, ascending or descending, index on a field that stores coordinates to return exact matches.

In the following example, the find() operation will return an exact match on a location if you have a { 'loc': 1} index:

db.<collection>.find( { loc: [ <x> , <y> ] } )

This query will return any documents with the value of [ <x> , <y> ].

Create a Haystack Index

A haystack index must reference two fields: the location field and a second field. The second field is used for exact matches. Haystack indexes return documents based on location and an exact match on a single additional criterion. These indexes are not necessarily suited to returning the closest documents to a particular location.

To build a haystack index, use the following syntax:

db.coll.ensureIndex( { <location field> : "geoHaystack" ,
                       <additional field> : 1 } ,
                     { bucketSize : <bucket value> } )

To build a haystack index, you must specify the bucketSize option when creating the index. A bucketSize of 5 creates an index that groups location values that are within 5 units of the specified longitude and latitude. The bucketSize also determines the granularity of the index. You can tune the parameter to the distribution of your data so that in general you search only very small regions. The areas defined by buckets can overlap. A document can exist in multiple buckets.

Example

If you have a collection with documents that contain fields similar to the following:

{ _id : 100, pos: { lng : 126.9, lat : 35.2 } , type : "restaurant"}
{ _id : 200, pos: { lng : 127.5, lat : 36.1 } , type : "restaurant"}
{ _id : 300, pos: { lng : 128.0, lat : 36.7 } , type : "national park"}

The following operations create a haystack index with buckets that store keys within 1 unit of longitude or latitude.

db.places.ensureIndex( { pos : "geoHaystack", type : 1 } ,
                       { bucketSize : 1 } )

This index stores the document with an _id field that has the value 200 in two different buckets:

In a bucket that includes the document where the _id field has a value of 100

In a bucket that includes the document where the _id field has a value of 300

To query using a haystack index you use the geoSearch command. See Query a Haystack Index.

By default, queries that use a haystack index return 50 documents.

Query a Haystack Index

A haystack index is a special 2d geospatial index that is optimized to return results over small areas. To create a haystack index see Create a Haystack Index.

To query a haystack index, use the geoSearch command. You must specify both the coordinates and the additional field to geoSearch. For example, to return all documents with the value restaurant in the type field near the example point, the command would resemble:

db.runCommand( { geoSearch : "places" ,
                 search : { type: "restaurant" } ,
                 near : [-74, 40.74] ,
                 maxDistance : 10 } )

Note

Haystack indexes are not suited to queries for the complete list of documents closest to a particular location. The closest documents could be more distant compared to the bucket size.

Note

Spherical query operations are not currently supported by haystack indexes.

The find() method and geoNear command cannot access the haystack index.

Calculate Distance Using Spherical Geometry

Note

While basic queries using spherical distance are supported by the 2d index, consider moving to a 2dsphere index if your data is primarily longitude and latitude.

The 2d index supports queries that calculate distances on a Euclidean plane (flat surface). The index also supports the following query operators and command that calculate distances using spherical geometry:

$nearSphere

$centerSphere

$near

geoNear command with the { spherical: true } option.

Important

These three queries use radians for distance. Other query types do not.

For spherical query operators to function properly, you must convert distances to radians, and convert from radians to the distances units used by your application.

To convert:

distance to radians: divide the distance by the radius of the sphere (e.g. the Earth) in the same units as the distance measurement.

radians to distance: multiply the radian measure by the radius of the sphere (e.g. the Earth) in the units system that you want to convert the distance to.

The radius of the Earth is approximately 3,959 miles or 6,371 kilometers.

The following query would return documents from the places collection within the circle described by the center [ -74, 40.74 ] with a radius of 100 miles:

db.places.find( { loc: { $geoWithin: { $centerSphere: [ [ -74, 40.74 ] ,
                                                     100 / 3959 ] } } } )

You may also use the distanceMultiplier option to the geoNear to convert radians in the mongod process, rather than in your application code. See distance multiplier.

The following spherical query, returns all documents in the collection places within 100 miles from the point [ -74, 40.74 ].

db.runCommand( { geoNear: "places",
                 near: [ -74, 40.74 ],
                 spherical: true
               }  )

The output of the above command would be:

{
   // [ ... ]
   "results" : [
      {
         "dis" : 0.01853688938212826,
         "obj" : {
            "_id" : ObjectId( ... )
            "loc" : [
               -73,
               40
            ]
         }
      }
   ],
   "stats" : {
      // [ ... ]
      "avgDistance" : 0.01853688938212826,
      "maxDistance" : 0.01853714811400047
   },
   "ok" : 1
}

Warning

Spherical queries that wrap around the poles or at the transition from -180 to 180 longitude raise an error.

Note

While the default Earth-like bounds for geospatial indexes are between -180 inclusive, and 180, valid values for latitude are between -90 and 90.

Distance Multiplier

The distanceMultiplier option of the geoNear command returns distances only after multiplying the results by an assigned value. This allows MongoDB to return converted values, and removes the requirement to convert units in application logic.

Using distanceMultiplier in spherical queries provides results from the geoNear command that do not need radian-to-distance conversion. The following example uses distanceMultiplier in the geoNear command with a spherical example:

db.runCommand( { geoNear: "places",
                 near: [ -74, 40.74 ],
                 spherical: true,
                 distanceMultiplier: 3959
               }  )

The output of the above operation would resemble the following:

{
   // [ ... ]
   "results" : [
      {
         "dis" : 73.46525170413567,
         "obj" : {
            "_id" : ObjectId( ... )
            "loc" : [
               -73,
               40
            ]
         }
      }
   ],
   "stats" : {
      // [ ... ]
      "avgDistance" : 0.01853688938212826,
      "maxDistance" : 0.01853714811400047
   },
   "ok" : 1
}

Text Search Tutorials

Instructions for enabling MongoDB’s text search feature, and for building and configuring text indexes.

Create a text Index

A text index allows searches on text strings in the index’s specified fields.

Specify a Language for Text Index

The specified language determines the list of stop words and the rules for Text Search’s stemmer and tokenizer.

Specify Name for text Index

Override the text index name limit for long index names.

Control Search Results with Weights

Give priority to certain search values by denoting the significance of an indexed field relative to other indexed fields

Limit the Number of Entries Scanned

Create an index to support queries that includes $text expressions and equality conditions.

Text Search in the Aggregation Pipeline

Perform various text search in the aggregation pipeline.

Create a text Index

Specify a Language for Text Index

Specify Name for text Index

Control Search Results with Weights

Limit the Number of Entries Scanned

Text Search in the Aggregation Pipeline

Create a text Index

You can create a text index on the field or fields whose value is a string or an array of string elements. When creating a text index on multiple fields, you can specify the individual fields or you can use wildcard specifier ($**).

Index Specific Fields

The following example creates a text index on the fields subject and content:

db.collection.ensureIndex(
                           {
                             subject: "text",
                             content: "text"
                           }
                         )

This text index catalogs all string data in the subject field and the content field, where the field value is either a string or an array of string elements.

Index All Fields

To allow for text search on all fields with string content, use the wildcard specifier ($**) to index all fields that contain string content.

The following example indexes any string value in the data of every field of every document in collection and names the index TextIndex:

db.collection.ensureIndex(
                           { "$**": "text" },
                           { name: "TextIndex" }
                         )

Note

In order to drop a text index, use the index name. See Use the Index Name to Drop a text Index for more information.

Specify a Language for Text Index

This tutorial describes how to specify the default language associated with the text index and also how to create text indexes for collections that contain documents in different languages.

Specify the Default Language for a text Index

The default language associated with the indexed data determines the rules to parse word roots (i.e. stemming) and ignore stop words. The default language for the indexed data is english.

To specify a different language, use the default_language option when creating the text index. See Text Search Languages for the languages available for default_language.

The following example creates for the quotes collection a text index on the content field and sets the default_language to spanish:

db.quotes.ensureIndex(
   { content : "text" },
   { default_language: "spanish" }
)

Create a text Index for a Collection in Multiple Languages

Changed in version 2.6: Added support for language overrides within embedded documents.

Specify the Index Language within the Document

If a collection contains documents or embedded documents that are in different languages, include a field named language in the documents or embedded documents and specify as its value the language for that document or embedded document.

MongoDB will use the specified language for that document or embedded document when building the text index:

The specified language in the document overrides the default language for the text index.

The specified language in an embedded document override the language specified in an enclosing document or the default language for the index.

See Text Search Languages for a list of supported languages.

For example, a collection quotes contains multi-language documents that include the language field in the document and/or the embedded document as needed:

{
   _id: 1,
   language: "portuguese",
   original: "A sorte protege os audazes.",
   translation:
     [
        {
           language: "english",
           quote: "Fortune favors the bold."
        },
        {
           language: "spanish",
           quote: "La suerte protege a los audaces."
        }
    ]
}
{
   _id: 2,
   language: "spanish",
   original: "Nada hay más surrealista que la realidad.",
   translation:
      [
        {
          language: "english",
          quote: "There is nothing more surreal than reality."
        },
        {
          language: "french",
          quote: "Il n'y a rien de plus surréaliste que la réalité."
        }
      ]
}
{
   _id: 3,
   original: "is this a dagger which I see before me.",
   translation:
   {
      language: "spanish",
      quote: "Es este un puñal que veo delante de mí."
   }
}

If you create a text index on the quote field with the default language of English.

db.quotes.ensureIndex( { original: "text", "translation.quote": "text" } )

Then, for the documents and embedded documents that contain the language field, the text index uses that language to parse word stems and other linguistic characteristics.

For embedded documents that do not contain the language field,

If the enclosing document contains the language field, then the index uses the document’s language for the embedded document.

Otherwise, the index uses the default language for the embedded documents.

For documents that do not contain the language field, the index uses the default language, which is English.

Use any Field to Specify the Language for a Document

To use a field with a name other than language, include the language_override option when creating the index.

For example, give the following command to use idioma as the field name instead of language:

db.quotes.ensureIndex( { quote : "text" },
                       { language_override: "idioma" } )

The documents of the quotes collection may specify a language with the idioma field:

{ _id: 1, idioma: "portuguese", quote: "A sorte protege os audazes" }
{ _id: 2, idioma: "spanish", quote: "Nada hay más surrealista que la realidad." }
{ _id: 3, idioma: "english", quote: "is this a dagger which I see before me" }

Specify Name for text Index

The default name for the index consists of each indexed field name concatenated with _text. For example, the following command creates a text index on the fields content, users.comments, and users.profiles:

db.collection.ensureIndex(
   {
     content: "text",
     "users.comments": "text",
     "users.profiles": "text"
   }
)

The default name for the index is:

"content_text_users.comments_text_users.profiles_text"

The text index, like other indexes, must fall within the index name length limit.

Specify a Name for text Index

To avoid creating an index with a name that exceeds the index name length limit, you can pass the name option to the db.collection.ensureIndex() method:

db.collection.ensureIndex(
   {
     content: "text",
     "users.comments": "text",
     "users.profiles": "text"
   },
   {
     name: "MyTextIndex"
   }
)

Use the Index Name to Drop a text Index

Whether the text index has the default name or you specified a name for the text index, to drop the text index, pass the index name to the db.collection.dropIndex() method.

For example, consider the index created by the following operation:

db.collection.ensureIndex(
   {
     content: "text",
     "users.comments": "text",
     "users.profiles": "text"
   },
   {
     name: "MyTextIndex"
   }
)

Then, to remove this text index, pass the name "MyTextIndex" to the db.collection.dropIndex() method, as in the following:

db.collection.dropIndex("MyTextIndex")

To get the names of the indexes, use the db.collection.getIndexes() method.

Control Search Results with Weights

This document describes how to create a text index with specified weights for results fields.

For a text index, the weight of an indexed field denotes the significance of the field relative to the other indexed fields in terms of the score. The score for a given word in a document is derived from the weighted sum of the frequency for each of the indexed fields in that document. See $meta operator for details on returning and sorting by text scores.

The default weight is 1 for the indexed fields. To adjust the weights for the indexed fields, include the weights option in the db.collection.ensureIndex() method.

Warning

Choose the weights carefully in order to prevent the need to reindex.

A collection blog has the following documents:

{ _id: 1,
  content: "This morning I had a cup of coffee.",
  about: "beverage",
  keywords: [ "coffee" ]
}

{ _id: 2,
  content: "Who doesn't like cake?",
  about: "food",
  keywords: [ "cake", "food", "dessert" ]
}

To create a text index with different field weights for the content field and the keywords field, include the weights option to the ensureIndex() method. For example, the following command creates an index on three fields and assigns weights to two of the fields:

db.blog.ensureIndex(
                     {
                       content: "text",
                       keywords: "text",
                       about: "text"
                     },
                     {
                       weights: {
                                  content: 10,
                                  keywords: 5,
                                },
                       name: "TextIndex"
                     }
                   )

The text index has the following fields and weights:

content has a weight of 10,

keywords has a weight of 5, and

about has the default weight of 1.

These weights denote the relative significance of the indexed fields to each other. For instance, a term match in the content field has:

2 times (i.e. 10:5) the impact as a term match in the keywords field and

10 times (i.e. 10:1) the impact as a term match in the about field.

Limit the Number of Entries Scanned

This tutorial describes how to create indexes to limit the number of index entries scanned for queries that includes a $text expression and equality conditions.

A collection inventory contains the following documents:

{ _id: 1, dept: "tech", description: "lime green computer" }
{ _id: 2, dept: "tech", description: "wireless red mouse" }
{ _id: 3, dept: "kitchen", description: "green placemat" }
{ _id: 4, dept: "kitchen", description: "red peeler" }
{ _id: 5, dept: "food", description: "green apple" }
{ _id: 6, dept: "food", description: "red potato" }

Consider the common use case that performs text searches by individual departments, such as:

db.inventory.find( { dept: "kitchen", $text: { $search: "green" } } )

To limit the text search to scan only those documents within a specific dept, create a compound index that first specifies an ascending/descending index key on the field dept and then a text index key on the field description:

db.inventory.ensureIndex(
   {
     dept: 1,
     description: "text"
   }
)

Then, the text search [1] within a particular department will limit the scan of indexed documents. For example, the following query scans only those documents with dept equal to kitchen:

db.inventory.find( { dept: "kitchen", $text: { $search: "green" } } )

Note

A compound text index cannot include any other special index types, such as multi-key or geospatial index fields.

If the compound text index includes keys preceding the text index key, to perform a $text search, the query predicate must include equality match conditions on the preceding keys.

[1]
If using the deprecated text command, the text command must include the filter option that specifies an equality condition for the prefix fields.

See also

Text Indexes

Text Search in the Aggregation Pipeline

New in version 2.6.

In the aggregation pipeline, text search is available via the use of the $text query operator in the $match stage.

Restrictions

Text search in the aggregation pipeline has the following restrictions:

The $match stage that includes a $text must be the first stage in the pipeline.

A text operator can only occur once in the stage.

The text operator expression cannot appear in $or or $not expressions.

The text search, by default, does not return the matching documents in order of matching scores. Use the $meta aggregation expression in the $sort stage.

Text Score

The $text operator assigns a score to each document that contains the search term in the indexed fields. The score represents the relevance of a document to a given text search query. The score can be part of a $sort pipeline specification as well as part of the projection expression. The { $meta: "textScore" } expression provides information on the processing of the $text operation. See $meta aggregation for details on accessing the score for projection or sort.

The metadata is only available after the $match stage that includes the $text operation.

Examples

The following examples assume a collection articles that has a text index on the field subject:

db.articles.ensureIndex( { subject: "text" } )

Calculate the Total Views for Articles that Contains a Word

The following aggregation searches for the term cake in the $match stage and calculates the total views for the matching documents in the $group stage.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake" } } },
     { $group: { _id: null, views: { $sum: "$views" } } }
   ]
)

Return Results Sorted by Text Search Score

To sort by the text search score, include a $meta expression in the $sort stage. The following example matches on either the term cake or tea, sorts by the textScore in descending order, and returns only the title field in the results set.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake tea" } } },
     { $sort: { score: { $meta: "textScore" } } },
     { $project: { title: 1, _id: 0 } }
   ]
)

The specified metadata determines the sort order. For example, the "textScore" metadata sorts in descending order. See $meta for more information on metadata as well as an example of overriding the default sort order of the metadata.

Match on Text Score

The "textScore" metadata is available for projections, sorts, and conditions subsequent the $match stage that includes the $text operation.

The following example matches on either the term cake or tea, projects the title and the score fields, and then returns only those documents with a score greater than 1.0.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake tea" } } },
     { $project: { title: 1, _id: 0, score: { $meta: "textScore" } } },
     { $match: { score: { $gt: 1.0 } } }
   ]
)

Specify a Language for Text Search

The following aggregation searches in spanish for documents that contain the term saber but not the term claro in the $match stage and calculates the total views for the matching documents in the $group stage.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "saber -claro", $language: "es" } } },
     { $group: { _id: null, views: { $sum: "$views" } } }
   ]
)

Indexing Strategies

The best indexes for your application must take a number of factors into account, including the kinds of queries you expect, the ratio of reads to writes, and the amount of free memory on your system.

When developing your indexing strategy you should have a deep understanding of your application’s queries. Before you build indexes, map out the types of queries you will run so that you can build indexes that reference those fields. Indexes come with a performance cost, but are more than worth the cost for frequent queries on large data set. Consider the relative frequency of each query in the application and whether the query justifies an index.

The best overall strategy for designing indexes is to profile a variety of index configurations with data sets similar to the ones you’ll be running in production to see which configurations perform best.Inspect the current indexes created for your collections to ensure they are supporting your current and planned queries. If an index is no longer used, drop the index.

MongoDB can only use one index to support any given operation. However, each clause of an $or query may use a different index.

The following documents introduce indexing strategies:

Create Indexes to Support Your Queries

An index supports a query when the index contains all the fields scanned by the query. Creating indexes that supports queries results in greatly increased query performance.

Use Indexes to Sort Query Results

To support efficient queries, use the strategies here when you specify the sequential order and sort order of index fields.

Ensure Indexes Fit in RAM

When your index fits in RAM, the system can avoid reading the index from disk and you get the fastest processing.

Create Queries that Ensure Selectivity

Selectivity is the ability of a query to narrow results using the index. Selectivity allows MongoDB to use the index for a larger portion of the work associated with fulfilling the query.

Create Indexes to Support Your Queries

Use Indexes to Sort Query Results

Ensure Indexes Fit in RAM

Create Queries that Ensure Selectivity

For a conceptual introduction to indexes in MongoDB see Index Concepts.

Create Indexes to Support Your Queries

An index supports a query when the index contains all the fields scanned by the query. The query scans the index and not the collection. Creating indexes that support queries results in greatly increased query performance.

This document describes strategies for creating indexes that support queries.

Create a Single-Key Index if All Queries Use the Same, Single Key

If you only ever query on a single key in a given collection, then you need to create just one single-key index for that collection. For example, you might create an index on category in the product collection:

db.products.ensureIndex( { "category": 1 } )

Create Compound Indexes to Support Several Different Queries

If you sometimes query on only one key and at other times query on that key combined with a second key, then creating a compound index is more efficient than creating a single-key index. MongoDB will use the compound index for both queries. For example, you might create an index on both category and item.

db.products.ensureIndex( { "category": 1, "item": 1 } )

This allows you both options. You can query on just category, and you also can query on category combined with item. A single compound index on multiple fields can support all the queries that search a “prefix” subset of those fields.

Example

The following index on a collection:

{ x: 1, y: 1, z: 1 }

Can support queries that the following indexes support:

{ x: 1 }
{ x: 1, y: 1 }

There are some situations where the prefix indexes may offer better query performance: for example if z is a large array.

The { x: 1, y: 1, z: 1 } index can also support many of the same queries as the following index:

{ x: 1, z: 1 }

Also, { x: 1, z: 1 } has an additional use. Given the following query:

db.collection.find( { x: 5 } ).sort( { z: 1} )

The { x: 1, z: 1 } index supports both the query and the sort operation, while the { x: 1, y: 1, z: 1 } index only supports the query. For more information on sorting, see Use Indexes to Sort Query Results.

Starting in version 2.6, MongoDB can use index intersection to fulfill queries. The choice between creating compound indexes that support your queries or relying on index intersection depends on the specifics of your system. See Index Intersection and Compound Indexes for more details.

Use Indexes to Sort Query Results

In MongoDB, sort operations can obtain the sort order by retrieving documents based on the ordering in an index. If the query planner cannot obtain the sort order from an index, it will sort the results in memory. Sort operations that use an index often have better performance than those that do not use an index. In addition, sort operations that do not use an index will abort when they use 32 megabytes of memory.

Sort with a Single Field Index

If an ascending or a descending index is on a single field, the sort operation on the field can be in either direction.

For example, create an ascending index on the field a for a collection records:

db.records.ensureIndex( { a: 1 } )

This index can support an ascending sort on a:

db.records.find().sort( { a: 1 } )

The index can also support the following descending sort on a by traversing the index in reverse order:

db.records.find().sort( { a: -1 } )

Sort on Multiple Fields

Create a compound index to support sorting on multiple fields.

You can specify a sort on all the keys of the index or on a subset; however, the sort keys must be listed in the same order as they appear in the index. For example, an index key pattern { a: 1, b: 1 } can support a sort on { a: 1, b: 1 } but not on { b: 1, a: 1 }.

The sort must specify the same sort direction (i.e.ascending/descending) for all its keys as the index key pattern or specify the reverse sort direction for all its keys as the index key pattern. For example, an index key pattern { a: 1, b: 1 } can support a sort on { a: 1, b: 1 } and { a: -1, b: -1 } but not on { a: -1, b: 1 }.

Sort and Index Prefix

If the sort keys correspond to the index keys or an index prefix, MongoDB can use the index to sort the query results. A prefix of a compound index is a subset that consists of one or more keys at the start of the index key pattern.

For example, create a compound index on the data collection:

db.data.ensureIndex( { a:1, b: 1, c: 1, d: 1 } )

Then, the following are prefixes for that index:

{ a: 1 }
{ a: 1, b: 1 }
{ a: 1, b: 1, c: 1 }

The following query and sort operations use the index prefixes to sort the results. These operations do not need to sort the result set in memory.

Example | Index Prefix
db.data.find().sort( { a: 1 } ) | { a: 1 }
db.data.find().sort( { a: -1 } ) | { a: 1 }
db.data.find().sort( { a: 1, b: 1 } ) | { a: 1, b: 1 }
db.data.find().sort( { a: -1, b: -1 } ) | { a: 1, b: 1 }
db.data.find().sort( { a: 1, b: 1, c: 1 } ) | { a: 1, b: 1, c: 1 }
db.data.find( { a: { $gt: 4 } } ).sort( { a: 1, b: 1 } ) | { a: 1, b: 1 }

Consider the following example in which the prefix keys of the index appear in both the query predicate and the sort:

db.data.find( { a: { $gt: 4 } } ).sort( { a: 1, b: 1 } )

In such cases, MongoDB can use the index to retrieve the documents in order specified by the sort. As the example shows, the index prefix in the query predicate can be different from the prefix in the sort.

Sort and Non-prefix Subset of an Index

An index can support sort operations on a non-prefix subset of the index key pattern. To do so, the query must include equality conditions on all the prefix keys that precede the sort keys.

For example, the collection data has the following index:

{ a: 1, b: 1, c: 1, d: 1 }

The following operations can use the index to get the sort order:

Example | Index Prefix
db.data.find( { a: 5 } ).sort( { b: 1, c: 1 } ) | { a: 1 , b: 1, c: 1 }
db.data.find( { b: 3, a: 4 } ).sort( { c: 1 } ) | { a: 1, b: 1, c: 1 }
db.data.find( { a: 5, b: { $lt: 3} } ).sort( { b: 1 } ) | { a: 1, b: 1 }

As the last operation shows, only the index fields preceding the sort subset must have the equality conditions in the query document; the other index fields may specify other conditions.

If the query does not specify an equality condition on an index prefix that precedes or overlaps with the sort specification, the operation will not efficiently use the index. For example, the following operations specify a sort document of { c: 1 }, but the query documents do not contain equality matches on the preceding index fields a and b:

db.data.find( { a: { $gt: 2 } } ).sort( { c: 1 } )
db.data.find( { c: 5 } ).sort( { c: 1 } )

These operations will not efficiently use the index { a: 1, b: 1, c: 1, d: 1 } and may not even use the index to retrieve the documents.

Ensure Indexes Fit in RAM

For the fastest processing, ensure that your indexes fit entirely in RAM so that the system can avoid reading the index from disk.

To check the size of your indexes, use the db.collection.totalIndexSize() helper, which returns data in bytes:

> db.collection.totalIndexSize()
4294976499

The above example shows an index size of almost 4.3 gigabytes. To ensure this index fits in RAM, you must not only have more than that much RAM available but also must have RAM available for the rest of the working set. Also remember:

If you have and use multiple collections, you must consider the size of all indexes on all collections. The indexes and the working set must be able to fit in memory at the same time.

There are some limited cases where indexes do not need to fit in memory. See Indexes that Hold Only Recent Values in RAM.

See also

collStats and db.collection.stats()

Indexes that Hold Only Recent Values in RAM

Indexes do not have to fit entirely into RAM in all cases. If the value of the indexed field increments with every insert, and most queries select recently added documents; then MongoDB only needs to keep the parts of the index that hold the most recent or “right-most” values in RAM. This allows for efficient index use for read and write operations and minimize the amount of RAM required to support the index.

Create Queries that Ensure Selectivity

Selectivity is the ability of a query to narrow results using the index. Effective indexes are more selective and allow MongoDB to use the index for a larger portion of the work associated with fulfilling the query.

To ensure selectivity, write queries that limit the number of possible documents with the indexed field. Write queries that are appropriately selective relative to your indexed data.

Example

Suppose you have a field called status where the possible values are new and processed. If you add an index on status you’ve created a low-selectivity index. The index will be of little help in locating records.

A better strategy, depending on your queries, would be to create a compound index that includes the low-selectivity field and another field. For example, you could create a compound index on status and created_at.

Another option, again depending on your use case, might be to use separate collections, one for each status.

Example

Consider an index { a : 1 } (i.e. an index on the key a sorted in ascending order) on a collection where a has three values evenly distributed across the collection:

{ _id: ObjectId(), a: 1, b: "ab" }
{ _id: ObjectId(), a: 1, b: "cd" }
{ _id: ObjectId(), a: 1, b: "ef" }
{ _id: ObjectId(), a: 2, b: "jk" }
{ _id: ObjectId(), a: 2, b: "lm" }
{ _id: ObjectId(), a: 2, b: "no" }
{ _id: ObjectId(), a: 3, b: "pq" }
{ _id: ObjectId(), a: 3, b: "rs" }
{ _id: ObjectId(), a: 3, b: "tv" }

If you query for { a: 2, b: "no" } MongoDB must scan 3 documents in the collection to return the one matching result. Similarly, a query for { a: { $gt: 1}, b: "tv" } must scan 6 documents, also to return one result.

Consider the same index on a collection where a has nine values evenly distributed across the collection:

{ _id: ObjectId(), a: 1, b: "ab" }
{ _id: ObjectId(), a: 2, b: "cd" }
{ _id: ObjectId(), a: 3, b: "ef" }
{ _id: ObjectId(), a: 4, b: "jk" }
{ _id: ObjectId(), a: 5, b: "lm" }
{ _id: ObjectId(), a: 6, b: "no" }
{ _id: ObjectId(), a: 7, b: "pq" }
{ _id: ObjectId(), a: 8, b: "rs" }
{ _id: ObjectId(), a: 9, b: "tv" }

If you query for { a: 2, b: "cd" }, MongoDB must scan only one document to fulfill the query. The index and query are more selective because the values of a are evenly distributed and the query can select a specific document using the index.

However, although the index on a is more selective, a query such as { a: { $gt: 5 }, b: "tv" } would still need to scan 4 documents.

If overall selectivity is low, and if MongoDB must read a number of documents to return results, then some queries may perform faster without indexes. To determine performance, see Measure Index Use.

Indexing Reference

Indexing Methods in the mongo Shell

Name | Description
db.collection.createIndex() | Builds an index on a collection. Use db.collection.ensureIndex().
db.collection.dropIndex() | Removes a specified index on a collection.
db.collection.dropIndexes() | Removes all indexes on a collection.
db.collection.ensureIndex() | Creates an index if it does not currently exist. If the index exists ensureIndex() does nothing.
db.collection.getIndexes() | Returns an array of documents that describe the existing indexes on a collection.
db.collection.getIndexStats() | Renders a human-readable view of the data collected by indexStats which reflects B-tree utilization.
db.collection.indexStats() | Renders a human-readable view of the data collected by indexStats which reflects B-tree utilization.
db.collection.reIndex() | Rebuilds all existing indexes on a collection.
db.collection.totalIndexSize() | Reports the total size used by the indexes on a collection. Provides a wrapper around the totalIndexSize field of the collStats output.
cursor.explain() | Reports on the query execution plan, including index use, for a cursor.
cursor.hint() | Forces MongoDB to use a specific index for a query.
cursor.max() | Specifies an exclusive upper index bound for a cursor. For use with cursor.hint()
cursor.min() | Specifies an inclusive lower index bound for a cursor. For use with cursor.hint()
cursor.snapshot() | Forces the cursor to use the index on the _id field. Ensures that the cursor returns each document, with regards to the value of the _id field, only once.

Indexing Database Commands

Name | Description
createIndexes | Builds one or more indexes for a collection.
dropIndexes | Removes indexes from a collection.
compact | Defragments a collection and rebuilds the indexes.
reIndex | Rebuilds all indexes on a collection.
validate | Internal command that scans for a collection’s data and indexes for correctness.
indexStats | Experimental command that collects and aggregates statistics on all indexes.
geoNear | Performs a geospatial query that returns the documents closest to a given point.
geoSearch | Performs a geospatial query that uses MongoDB’s haystack index functionality.
geoWalk | An internal command to support geospatial queries.
checkShardingIndex | Internal command that validates index on shard key.

Geospatial Query Selectors

Name | Description
$geoWithin | Selects geometries within a bounding GeoJSON geometry. The 2dsphere and 2d indexes support $geoWithin.
$geoIntersects | Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects.
$near | Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near.
$nearSphere | Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d indexes support $nearSphere.

Indexing Query Modifiers

Name | Description
$explain | Forces MongoDB to report on query execution plans. See explain().
$hint | Forces MongoDB to use a specific index. See hint()
$max | Specifies an exclusive upper limit for the index to use in a query. See max().
$min | Specifies an inclusive lower limit for the index to use in a query. See min().
$returnKey | Forces the cursor to only return fields included in the index.
$snapshot | Forces the query to use the index on the _id field. See snapshot().

Other Index References

Text Search Languages

Supported languages for text indexes and $text query operations.

Text Search Languages

Text Search Languages

The text index, the $text operator, and the text command [1] support the following languages:

Changed in version 2.6: MongoDB introduces version 2 of the text search feature. With version 2, text search feature supports using the two-letter language codes defined in ISO 639-1. Version 1 of text search only supported the long form of each language name.

da or danish

nl or dutch

en or english

fi or finnish

fr or french

de or german

hu or hungarian

it or italian

nb or norwegian

pt or portuguese

ro or romanian

ru or russian

es or spanish

sv or swedish

tr or turkish

Note

If you specify a language value of "none", then the text search uses simple tokenization with no list of stop words and no stemming.

[1]
The text command is deprecated in MongoDB 2.6.

Replication

A replica set in MongoDB is a group of mongod processes that maintain the same data set. Replica sets provide redundancy and high availability, and are the basis for all production deployments. This section introduces replication in MongoDB as well as the components and architecture of replica sets. The section also provides tutorials for common tasks related to replica sets.

Replication Introduction

An introduction to replica sets, their behavior, operation, and use.

Replication Concepts

The core documentation of replica set operations, configurations, architectures and behaviors.

Replica Set Members

Introduces the components of replica sets.

Replica Set Deployment Architectures

Introduces architectural considerations related to replica sets deployment planning.

Replica Set High Availability

Presents the details of the automatic failover and recovery process with replica sets.

Replica Set Read and Write Semantics

Presents the semantics for targeting read and write operations to the replica set, with an awareness of location and set configuration.

Replica Set Tutorials

Tutorials for common tasks related to the use and maintenance of replica sets.

Replication Reference

Reference for functions and operations related to replica sets.

Replication Introduction

Replication Concepts

Replica Set Members

Replica Set Primary

Replica Set Secondary Members

Priority 0 Replica Set Members

Hidden Replica Set Members

Delayed Replica Set Members

Replica Set Arbiter

Replica Set Deployment Architectures

Three Member Replica Sets

Replica Sets with Four or More Members

Geographically Distributed Replica Sets

Replica Set High Availability

Replica Set Elections

Rollbacks During Replica Set Failover

Replica Set Read and Write Semantics

Write Concern for Replica Sets

Read Preference

Read Preference Processes

Replication Processes

Replica Set Oplog

Replica Set Data Synchronization

Master Slave Replication

Replica Set Tutorials

Replica Set Deployment Tutorials

Deploy a Replica Set

Deploy a Replica Set for Testing and Development

Deploy a Geographically Redundant Replica Set

Add an Arbiter to Replica Set

Convert a Standalone to a Replica Set

Add Members to a Replica Set

Remove Members from Replica Set

Replace a Replica Set Member

Member Configuration Tutorials

Adjust Priority for Replica Set Member

Prevent Secondary from Becoming Primary

Configure a Hidden Replica Set Member

Configure a Delayed Replica Set Member

Configure Non-Voting Replica Set Member

Convert a Secondary to an Arbiter

Replica Set Maintenance Tutorials

Change the Size of the Oplog

Perform Maintenance on Replica Set Members

Force a Member to Become Primary

Resync a Member of a Replica Set

Configure Replica Set Tag Sets

Reconfigure a Replica Set with Unavailable Members

Manage Chained Replication

Change Hostnames in a Replica Set

Configure a Secondary’s Sync Target

Troubleshoot Replica Sets

Replication Reference

Replica Set Configuration

The local Database

Replica Set Member States

Read Preference Reference

Replication Introduction

Replication is the process of synchronizing data across multiple servers.

Purpose of Replication

Replication provides redundancy and increases data availability. With multiple copies of data on different database servers, replication protects a database from the loss of a single server. Replication also allows you to recover from hardware failure and service interruptions. With additional copies of the data, you can dedicate one to disaster recovery, reporting, or backup.

In some cases, you can use replication to increase read capacity. Clients have the ability to send read and write operations to different servers. You can also maintain copies in different data centers to increase the locality and availability of data for distributed applications.

Replication in MongoDB

A replica set is a group of mongod instances that host the same data set. One mongod, the primary, receives all write operations. All other instances, secondaries, apply operations from the primary so that they have the same data set.

The primary accepts all write operations from clients. Replica set can have only one primary. Because only one member can accept write operations, replica sets provide strict consistency for all reads from the primary. To support replication, the primary logs all changes to its data sets in its oplog. See primary for more information.

The secondaries replicate the primary’s oplog and apply the operations to their data sets. Secondaries’ data sets reflect the primary’s data set. If the primary is unavailable, the replica set will elect a secondary to be primary. By default, clients read from the primary, however, clients can specify a read preferences to send read operations to secondaries. Reads from secondaries may return data that does not reflect the state of the primary. See secondaries for more information.

You may add an extra mongod instance to a replica set as an arbiter. Arbiters do not maintain a data set. Arbiters only exist to vote in elections. If your replica set has an even number of members, add an arbiter to obtain a majority of votes in an election for primary. Arbiters do not require dedicated hardware. See arbiter for more information.

An arbiter will always be an arbiter. A primary may step down and become a secondary. A secondary may become the primary during an election.

Asynchronous Replication

Secondaries apply operations from the primary asynchronously. By applying operations after the primary, sets can continue to function without some members. However, as a result secondaries may not return the most current data to clients.

See Replica Set Oplog and Replica Set Data Synchronization for more information. See Read Preference for more on read operations and secondaries.

Automatic Failover

When a primary does not communicate with the other members of the set for more than 10 seconds, the replica set will attempt to select another member to become the new primary. The first secondary that receives a majority of the votes becomes primary.

See Replica Set Elections and Rollbacks During Replica Set Failover for more information.

Additional Features

Replica sets provide a number of options to support application needs. For example, you may deploy a replica set with members in multiple data centers, or control the outcome of elections by adjusting the priority of some members. Replica sets also support dedicated members for reporting, disaster recovery, or backup functions.

See Priority 0 Replica Set Members, Hidden Replica Set Members and Delayed Replica Set Members for more information.

Replication Concepts

These documents describe and provide examples of replica set operation, configuration, and behavior. For an overview of replication, see Replication Introduction. For documentation of the administration of replica sets, see Replica Set Tutorials. The Replication Reference documents commands and operations specific to replica sets.

Replica Set Members

Introduces the components of replica sets.

Replica Set Primary

The primary is the only member of a replica set that accepts write operations.

Replica Set Secondary Members

Secondary members replicate the primary’s data set and accept read operations. If the set has no primary, a secondary can become primary.

Priority 0 Replica Set Members

Priority 0 members are secondaries that cannot become the primary.

Hidden Replica Set Members

Hidden members are secondaries that are invisible to applications. These members support dedicated workloads, such as reporting or backup.

Replica Set Arbiter

An arbiter does not maintain a copy of the data set but participate in elections.

Replica Set Deployment Architectures

Introduces architectural considerations related to replica sets deployment planning.

Replica Set High Availability

Presents the details of the automatic failover and recovery process with replica sets.

Replica Set Elections

Elections occur when the primary becomes unavailable and the replica set members autonomously select a new primary.

Read Preference

Applications specify read preference to control how drivers direct read operations to members of the replica set.

Replication Processes

Mechanics of the replication process and related topics.

Master Slave Replication

Master-slave replication provided redundancy in early versions of MongoDB. Replica sets replace master-slave for most use cases.

Replica Set Members

Replica Set Primary

Replica Set Secondary Members

Priority 0 Replica Set Members

Hidden Replica Set Members

Delayed Replica Set Members

Replica Set Arbiter

Replica Set Deployment Architectures

Three Member Replica Sets

Replica Sets with Four or More Members

Geographically Distributed Replica Sets

Replica Set High Availability

Replica Set Elections

Rollbacks During Replica Set Failover

Replica Set Read and Write Semantics

Write Concern for Replica Sets

Read Preference

Read Preference Processes

Replication Processes

Replica Set Oplog

Replica Set Data Synchronization

Master Slave Replication

Replica Set Members

A replica set in MongoDB is a group of mongod processes that provide redundancy and high availability. The members of a replica set are:

Primary.

The primary receives all write operations.

Secondaries.

Secondaries replicate operations from the primary to maintain an identical data set. Secondaries may have additional configurations for special usage profiles. For example, secondaries may be non-voting or priority 0.

You can also maintain an arbiter as part of a replica set. Arbiters do not keep a copy of the data. However, arbiters play a role in the elections that select a primary if the current primary is unavailable.

A replica set can have up to 12 members. [1] However, only 7 members can vote at a time.

The minimum requirements for a replica set are: A primary, a secondary, and an arbiter. Most deployments, however, will keep three members that store data: A primary and two secondary members.

Replica Set Primary

Replica Set Secondary Members

Priority 0 Replica Set Members

Hidden Replica Set Members

Delayed Replica Set Members

Replica Set Arbiter

[1]
While replica sets are the recommended solution for production, a replica set can support only 12 members in total. If your deployment requires more than 12 members, you’ll need to use master-slave replication. Master-slave replication lacks the automatic failover capabilities.

Replica Set Primary

The primary is the only member in the replica set that receives write operations. MongoDB applies write operations on the primary and then records the operations on the primary’s oplog. Secondary members replicate this log and apply the operations to their data sets.

In the following three-member replica set, the primary accepts all write operations. Then the secondaries replicate the oplog to apply to their data sets.

All members of the replica set can accept read operations. However, by default, an application directs its read operations to the primary member. See Read Preference for details on changing the default read behavior.

The replica set can have at most one primary. If the current primary becomes unavailable, an election determines the new primary. See Replica Set Elections for more details.

In the following 3-member replica set, the primary becomes unavailable. This triggers an election which selects one of the remaining secondaries as the new primary.

Replica Set Secondary Members

A secondary maintains a copy of the primary’s data set. To replicate data, a secondary applies operations from the primary’s oplog to its own data set in an asynchronous process. A replica set can have one or more secondaries.

The following three-member replica set has two secondary members. The secondaries replicate the primary’s oplog and apply the operations to their data sets.

Although clients cannot write data to secondaries, clients can read data from secondary members. See Read Preference for more information on how clients direct read operations to replica sets.

A secondary can become a primary. If the current primary becomes unavailable, the replica set holds an election to choose which of the secondaries becomes the new primary.

In the following three-member replica set, the primary becomes unavailable. This triggers an election where one of the remaining secondaries becomes the new primary.

See Replica Set Elections for more details.

You can configure a secondary member for a specific purpose. You can configure a secondary to:

Prevent it from becoming a primary in an election, which allows it to reside in a secondary data center or to serve as a cold standby. See Priority 0 Replica Set Members.

Prevent applications from reading from it, which allows it to run applications that require separation from normal traffic. See Hidden Replica Set Members.

Keep a running “historical” snapshot for use in recovery from certain errors, such as unintentionally deleted databases. See Delayed Replica Set Members.

Priority 0 Replica Set Members

Hidden Replica Set Members

Delayed Replica Set Members

Priority 0 Replica Set Members

A priority 0 member is a secondary that cannot become primary. Priority 0 members cannot trigger elections. Otherwise these members function as normal secondaries. A priority 0 member maintains a copy of the data set, accepts read operations, and votes in elections. Configure a priority 0 member to prevent secondaries from becoming primary, which is particularly useful in multi-data center deployments.

In a three-member replica set, in one data center hosts the primary and a secondary. A second data center hosts one priority 0 member that cannot become primary.

Priority 0 Members as Standbys

A priority 0 member can function as a standby. In some replica sets, it might not be possible to add a new member in a reasonable amount of time. A standby member keeps a current copy of the data to be able to replace an unavailable member.

In many cases, you need not set standby to priority 0. However, in sets with varied hardware or geographic distribution, a priority 0 standby ensures that only qualified members become primary.

A priority 0 standby may also be valuable for some members of a set with different hardware or workload profiles. In these cases, deploy a member with priority 0 so it can’t become primary. Also consider using an hidden member for this purpose.

If your set already has seven voting members, also configure the member as non-voting.

Priority 0 Members and Failover

When configuring a priority 0 member, consider potential failover patterns, including all possible network partitions. Always ensure that your main data center contains both a quorum of voting members and contains members that are eligible to be primary.

Configuration

To configure a priority 0 member, see Prevent Secondary from Becoming Primary.

Hidden Replica Set Members

A hidden member maintains a copy of the primary’s data set but is invisible to client applications. Hidden members are good for workloads with different usage patterns from the other members in the replica set. Hidden members must always be priority 0 members and so cannot become primary. The db.isMaster() method does not display hidden members. Hidden members, however, may vote in elections.

In the following five-member replica set, all four secondary members have copies of the primary’s data set, but one of the secondary members is hidden.

Behavior

Read Operations

Clients will not distribute reads with the appropriate read preference to hidden members. As a result, these members receive no traffic other than basic replication. Use hidden members for dedicated tasks such as reporting and backups. Delayed members should be hidden.

In a sharded cluster, mongos do not interact with hidden members.

Voting

Hidden members do vote in replica set elections. If you stop a hidden member, ensure that the set has an active majority or the primary will step down.

For the purposes of backups, you can avoid stopping a hidden member with the db.fsyncLock() and db.fsyncUnlock() operations to flush all writes and lock the mongod instance for the duration of the backup operation.

Further Reading

For more information about backing up MongoDB databases, see MongoDB Backup Methods. To configure a hidden member, see Configure a Hidden Replica Set Member.

Delayed Replica Set Members

Delayed members contain copies of a replica set’s data set. However, a delayed member’s data set reflects an earlier, or delayed, state of the set. For example, if the current time is 09:52 and a member has a delay of an hour, the delayed member has no operation more recent than 08:52.

Because delayed members are a “rolling backup” or a running “historical” snapshot of the data set, they may help you recover from various kinds of human error. For example, a delayed member can make it possible to recover from unsuccessful application upgrades and operator errors including dropped databases and collections.

Considerations

Requirements

Delayed members:

Must be priority 0 members. Set the priority to 0 to prevent a delayed member from becoming primary.

Should be hidden members. Always prevent applications from seeing and querying delayed members.

do vote in elections for primary.

Behavior

Delayed members apply operations from the oplog on a delay. When choosing the amount of delay, consider that the amount of delay:

must be is equal to or greater than your maintenance windows.

must be smaller than the capacity of the oplog. For more information on oplog size, see Oplog Size.

Sharding

In sharded clusters, delayed members have limited utility when the balancer is enabled. Because delayed members replicate chunk migrations with a delay, the state of delayed members in a sharded cluster are not useful for recovering to a previous state of the sharded cluster if any migrations occur during the delay window.

Example

In the following 5-member replica set, the primary and all secondaries have copies of the data set. One member applies operations with a delay of 3600 seconds, or an hour. This delayed member is also hidden and is a priority 0 member.

Configuration

A delayed member has its priority equal to 0, hidden equal to true, and its slaveDelay equal to the number of seconds of delay:

{
   "_id" : <num>,
   "host" : <hostname:port>,
   "priority" : 0,
   "slaveDelay" : <seconds>,
   "hidden" : true
}

To configure a delayed member, see Configure a Delayed Replica Set Member.

Replica Set Arbiter

An arbiter does not have a copy of data set and cannot become a primary. Replica sets may have arbiters to add a vote in elections of for primary. Arbiters allow replica sets to have an uneven number of members, without the overhead of a member that replicates data.

Important

Do not run an arbiter on systems that also host the primary or the secondary members of the replica set.

Only add an arbiter to sets with even numbers of members. If you add an arbiter to a set with an odd number of members, the set may suffer from tied elections. To add an arbiter, see Add an Arbiter to Replica Set.

Example

For example, in the following replica set, an arbiter allows the set to have an odd number of votes for elections:

Security

Authentication

When running with authorization, arbiters exchange credentials with other members of the set to authenticate. MongoDB encrypts the authentication process. The MongoDB authentication exchange is cryptographically secure.

Arbiters use keyfiles to authenticate to the replica set.

Communication

The only communication between arbiters and other set members are: votes during elections, heartbeats, and configuration data. These exchanges are not encrypted.

However, if your MongoDB deployment uses SSL, MongoDB will encrypt all communication between replica set members. See Configure mongod and mongos for SSL for more information.

As with all MongoDB components, run arbiters in trusted network environments.

Replica Set Deployment Architectures

The architecture of a replica set affects the set’s capacity and capability. This document provides strategies for replica set deployments and describes common architectures.

The standard replica set deployment for production system is a three-member replica set. These sets provide redundancy and fault tolerance. Avoid complexity when possible, but let your application requirements dictate the architecture.

Strategies

Determine the Number of Members

Add members in a replica set according to these strategies.

Deploy an Odd Number of Members

An odd number of members ensures that the replica set is always able to elect a primary. If you have an even number of members, add an arbiter to get an odd number. Arbiters do not store a copy of the data and require fewer resources. As a result, you may run an arbiter on an application server or other shared process.

Consider Fault Tolerance

Fault tolerance for a replica set is the number of members that can become unavailable and still leave enough members in the set to elect a primary. In other words, it is the difference between the number of members in the set and the majority needed to elect a primary. Without a primary, a replica set cannot accept write operations. Fault tolerance is an effect of replica set size, but the relationship is not direct. See the following table:

Number of Members. | Majority Required to Elect a New Primary. | Fault Tolerance.
3 | 2 | 1
4 | 3 | 1
5 | 3 | 2
6 | 4 | 2

Adding a member to the replica set does not always increase the fault tolerance. However, in these cases, additional members can provide support for dedicated functions, such as backups or reporting.

Use Hidden and Delayed Members for Dedicated Functions

Add hidden or delayed members to support dedicated functions, such as backup or reporting.

Load Balance on Read-Heavy Deployments

In a deployment with very high read traffic, you can improve read throughput by distributing reads to secondary members. As your deployment grows, add or move members to alternate data centers to improve redundancy and availability.

Always ensure that the main facility is able to elect a primary.

Add Capacity Ahead of Demand

The existing members of a replica set must have spare capacity to support adding a new member. Always add new members before the current demand saturates the capacity of the set.

Determine the Distribution of Members

Distribute Members Geographically

To protect your data if your main data center fails, keep at least one member in an alternate data center. Set these members’ priority to 0 to prevent them from becoming primary.

Keep a Majority of Members in One Location

When a replica set has members in multiple data centers, network partitions can prevent communication between data centers. To replicate data, members must be able to communicate to other members.

In an election, members must see each other to create a majority. To ensure that the replica set members can confirm a majority and elect a primary, keep a majority of the set’s members in one location.

Target Operations with Tags

Use replica set tags to ensure that operations replicate to specific data centers. Tags also support targeting read operations to specific machines.

See also

Data Center Awareness and Operational Segregation in MongoDB Deployments.

Use Journaling to Protect Against Power Failures

Enable journaling to protect data against service interruptions. Without journaling MongoDB cannot recover data after unexpected shutdowns, including power failures and unexpected reboots.

All 64-bit versions of MongoDB after version 2.0 have journaling enabled by default.

Replica Set Naming

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

Deployment Patterns

The following documents describe common replica set deployment patterns. Other patterns are possible and effective depending on the application’s requirements. If needed, combine features of each architecture in your own deployment:

Three Member Replica Sets

Three-member replica sets provide the minimum recommended architecture for a replica set.

Replica Sets with Four or More Members

Four or more member replica sets provide greater redundancy and can support greater distribution of read operations and dedicated functionality.

Geographically Distributed Replica Sets

Geographically distributed sets include members in multiple locations to protect against facility-specific failures, such as power outages.

Three Member Replica Sets

Replica Sets with Four or More Members

Geographically Distributed Replica Sets

Three Member Replica Sets

The minimum architecture of a replica set has three members. A three member replica set can have either three members that hold data, or two members that hold data and an arbiter.

Primary with Two Secondary Members

A replica set with three members that store data has:

One primary.

Two secondary members. Both secondaries can become the primary in an election.

These deployments provide two complete copies of the data set at all times in addition to the primary. These replica sets provide additional fault tolerance and high availability. If the primary is unavailable, the replica set elects a secondary to be primary and continues normal operation. The old primary rejoins the set when available.

Primary with a Secondary and an Arbiter

A three member replica set with a two members that store data has:

One primary.

One secondary member. The secondary can become primary in an election.

One arbiter. The arbiter only votes in elections.

Since the arbiter does not hold a copy of the data, these deployments provides only one complete copy of the data. Arbiters require fewer resources, at the expense of more limited redundancy and fault tolerance.

However, a deployment with a primary, secondary, and an arbiter ensures that a replica set remains available if the primary or the secondary is unavailable. If the primary is unavailable, the replica set will elect the secondary to be primary.

See also

Deploy a Replica Set.

Replica Sets with Four or More Members

Overview

Although the standard replica set configuration has three members, you can deploy larger sets. Add additional members to a set to increase redundancy or to add capacity for distributing secondary read operations.

Considerations

As you add new members to a replica set, consider the following:

Odd Number of Voting Members

Ensure that the replica set has an odd number of voting members. If you have an even number of voting members, deploy an arbiter so that the set has an odd number.

For example, the following replica set includes an arbiter to ensure an odd number of voting members.

Maximum Number of Voting Members

A replica set can have up to 12 members, [1] but only 7 voting members. If the replica set already has 7 voting members, additional members must be non-voting members.

For example, the following 9 member replica set has 7 voting members and 2 non-voting members.

See Non-Voting Members for more information.

Location of the Members

A majority of the replica set’s members should be in your application’s main data center.

For example, the following 5 member replica set has the majority, 3, of its members in its main data center, Data Center 1.

Electability of Members

Some members of the replica set, such as members that have networking restraint or limited resources, should not be able to become primary in a failover. Configure members that should not become primary to have priority 0.

For example, the secondary member in the third data center with a priority of 0 cannot become primary:

See also

Deploy a Replica Set, Add an Arbiter to Replica Set, and Add Members to a Replica Set.

[1]
While replica sets are the recommended solution for production, a replica set can support only 12 members in total. If your deployment requires more than 12 members, you’ll need to use master-slave replication. Master-slave replication lacks the automatic failover capabilities.

Geographically Distributed Replica Sets

Adding members to a replica set in multiple data centers adds redundancy and provides fault tolerance if one data center is unavailable. Members in additional data centers should have a priority of 0 to prevent them from becoming primary.

For example: the architecture of a geographically distributed replica set may be:

One primary in the main data center.

One secondary member in the main data center. This member can become primary at any time.

One priority 0 member in a second data center. This member cannot become primary.

In the following replica set, the primary and one secondary are in Data Center 1, while Data Center 2 has a priority 0 secondary that cannot become a primary.

If the primary is unavailable, the replica set will elect a new primary from Data Center 1. If the data centers cannot connect to each other, the member in Data Center 2 will not become the primary.

If Data Center 1 becomes unavailable, you can manually recover the data set from Data Center 2 with minimal downtime. With sufficient write concern, there will be no data loss.

To facilitate elections, the main data center should hold a majority of members. Also ensure that the set has an odd number of members. If adding a member in another data center results in a set with an even number of members, deploy an arbiter. For more information on elections, see Replica Set Elections.

See also

Deploy a Geographically Redundant Replica Set.

Additional Resource

MongoDB Multi-Data Center Deployments Whitepaper [http://www.mongodb.com/lp/white-paper/multi-dc]

Replica Set High Availability

Replica sets provide high availability using automatic failover. Failover allows a secondary member to become primary if primary is unavailable. Failover, in most situations does not require manual intervention.

Replica set members keep the same data set but are otherwise independent. If the primary becomes unavailable, the replica set holds an election to select a new primary. In some situations, the failover process may require a rollback. [1]

The deployment of a replica set affects the outcome of failover situations. To support effective failover, ensure that one facility can elect a primary if needed. Choose the facility that hosts the core application systems to host the majority of the replica set. Place a majority of voting members and all the members that can become primary in this facility. Otherwise, network partitions could prevent the set from being able to form a majority.

[1]
Replica sets remove “rollback” data when needed without intervention. Administrators must apply or discard rollback data manually.

Failover Processes

The replica set recovers from the loss of a primary by holding an election. Consider the following:

Replica Set Elections

Elections occur when the primary becomes unavailable and the replica set members autonomously select a new primary.

Rollbacks During Replica Set Failover

A rollback reverts write operations on a former primary when the member rejoins the replica set after a failover.

Replica Set Elections

Rollbacks During Replica Set Failover

Replica Set Elections

Replica sets use elections to determine which set member will become primary. Elections occur after initiating a replica set, and also any time the primary becomes unavailable. The primary is the only member in the set that can accept write operations. If a primary becomes unavailable, elections allow the set to recover normal operations without manual intervention. Elections are part of the failover process.

In the following three-member replica set, the primary is unavailable. The remaining secondaries hold an election to choose a new primary.

Behavior

Elections are essential for independent operation of a replica set; however, elections take time to complete. While an election is in process, the replica set has no primary and cannot accept writes and all remaining members become read-only. MongoDB avoids elections unless necessary.

If a majority of the replica set is inaccessible or unavailable, the replica set cannot accept writes and all remaining members become read-only.

Factors and Conditions that Affect Elections

Heartbeats

Replica set members send heartbeats (pings) to each other every two seconds. If a heartbeat does not return within 10 seconds, the other members mark the delinquent member as inaccessible.

Priority Comparisons

The priority setting affects elections. Members will prefer to vote for members with the highest priority value.

Members with a priority value of 0 cannot become primary and do not seek election. For details, see Priority 0 Replica Set Members.

A replica set does not hold an election as long as the current primary has the highest priority value or no secondary with higher priority is within 10 seconds of the latest oplog entry in the set.

If a higher-priority member catches up to within 10 seconds of the latest oplog entry of the current primary, the set holds an election in order to provide the higher-priority node a chance to become primary.

Optime

The optime is the timestamp of the last operation that a member applied from the oplog. A replica set member cannot become primary unless it has the highest (i.e. most recent) optime of any visible member in the set.

Connections

A replica set member cannot become primary unless it can connect to a majority of the members in the replica set. For the purposes of elections, a majority refers to the total number of votes, rather than the total number of members.

If you have a three-member replica set, where every member has one vote, the set can elect a primary as long as two members can connect to each other. If two members are unavailable, the remaining member remains a secondary because it cannot connect to a majority of the set’s members. If the remaining member is a primary and two members become unavailable, the primary steps down and becomes a secondary.

Network Partitions

Network partitions affect the formation of a majority for an election. If a primary steps down and neither portion of the replica set has a majority the set will not elect a new primary. The replica set becomes read-only.

To avoid this situation, place a majority of instances in one data center and a minority of instances in any other data centers combined.

Election Mechanics

Election Triggering Events

Replica sets hold an election any time there is no primary. Specifically, the following:

the initiation of a new replica set.

a secondary loses contact with a primary. Secondaries call for elections when they cannot see a primary.

a primary steps down.

Note

Priority 0 members, do not trigger elections, even when they cannot connect to the primary.

A primary will step down:

after receiving the replSetStepDown command.

if one of the current secondaries is eligible for election and has a higher priority.

if primary cannot contact a majority of the members of the replica set.

In some cases, modifying a replica set’s configuration will trigger an election by modifying the set so that the primary must step down.

Important

When a primary steps down, it closes all open client connections, so that clients don’t attempt to write data to a secondary. This helps clients maintain an accurate view of the replica set and helps prevent rollbacks.

Participation in Elections

Every replica set member has a priority that helps determine its eligibility to become a primary. In an election, the replica set elects an eligible member with the highest priority value as primary. By default, all members have a priority of 1 and have an equal chance of becoming primary. In the default, all members also can trigger an election.

You can set the priority value to weight the election in favor of a particular member or group of members. For example, if you have a geographically distributed replica set, you can adjust priorities so that only members in a specific data center can become primary.

The first member to receive the majority of votes becomes primary. By default, all members have a single vote, unless you modify the votes setting. Non-voting members have votes value of 0. All other members have 1 vote.

Note

Deprecated since version 2.6: votes values greater than 1.

Earlier versions of MongoDB allowed a member to have more than 1 vote by setting votes to a value greater than 1. Setting votes to value greater than 1 now produces a warning message.

The state of a member also affects its eligibility to vote. Only members in the following states can vote: PRIMARY, SECONDARY, RECOVERING, ARBITER, and ROLLBACK.

Important

Do not alter the number of votes in a replica set to control the outcome of an election. Instead, modify the priority value.

Vetoes in Elections

All members of a replica set can veto an election, including non-voting members. A member will veto an election:

If the member seeking an election is not a member of the voter’s set.

If the member seeking an election is not up-to-date with the most recent operation accessible in the replica set.

If the member seeking an election has a lower priority than another member in the set that is also eligible for election.

If a priority 0 member [1] is the most current member at the time of the election. In this case, another eligible member of the set will catch up to the state of this secondary member and then attempt to become primary.

If the current primary has more recent operations (i.e. a higher optime) than the member seeking election, from the perspective of the voting member.

If the current primary has the same or more recent operations (i.e. a higher or equal optime) than the member seeking election.

[1]
Remember that hidden and delayed imply priority 0 configuration.

Non-Voting Members

Non-voting members hold copies of the replica set’s data and can accept read operations from client applications. Non-voting members do not vote in elections, but can veto an election and become primary.

Because a replica set can have up to 12 members but only up to seven voting members, non-voting members allow a replica set to have more than seven members.

For instance, the following nine-member replica set has seven voting members and two non-voting members.

A non-voting member has a votes setting equal to 0 in its member configuration:

{
  "_id" : <num>
  "host" : <hostname:port>,
  "votes" : 0
}

Important

Do not alter the number of votes to control which members will become primary. Instead, modify the priority option. Only alter the number of votes in exceptional cases. For example, to permit more than seven members.

When possible, all members should have one vote. Changing the number of votes can cause the wrong members to become primary.

To configure a non-voting member, see Configure Non-Voting Replica Set Member.

Rollbacks During Replica Set Failover

A rollback reverts write operations on a former primary when the member rejoins its replica set after a failover. A rollback is necessary only if the primary had accepted write operations that the secondaries had not successfully replicated before the primary stepped down. When the primary rejoins the set as a secondary, it reverts, or “rolls back,” its write operations to maintain database consistency with the other members.

MongoDB attempts to avoid rollbacks, which should be rare. When a rollback does occur, it is often the result of a network partition. Secondaries that can not keep up with the throughput of operations on the former primary, increase the size and impact of the rollback.

A rollback does not occur if the write operations replicate to another member of the replica set before the primary steps down and if that member remains available and accessible to a majority of the replica set.

Collect Rollback Data

When a rollback does occur, administrators must decide whether to apply or ignore the rollback data. MongoDB writes the rollback data to BSON files in the rollback/ folder under the database’s dbPath directory. The names of rollback files have the following form:

<database>.<collection>.<timestamp>.bson

For example:

records.accounts.2011-05-09T18-10-04.0.bson

Administrators must apply rollback data manually after the member completes the rollback and returns to secondary status. Use bsondump to read the contents of the rollback files. Then use mongorestore to apply the changes to the new primary.

Avoid Replica Set Rollbacks

To prevent rollbacks, use replica acknowledged write concern to guarantee that the write operations propagate to the members of a replica set.

Rollback Limitations

A mongod instance will not rollback more than 300 megabytes of data. If your system must rollback more than 300 megabytes, you must manually intervene to recover the data. If this is the case, the following line will appear in your mongod log:

[replica set sync] replSet syncThread: 13410 replSet too much data to roll back

In this situation, save the data directly or force the member to perform an initial sync. To force initial sync, sync from a “current” member of the set by deleting the content of the dbPath directory for the member that requires a larger rollback.

See also

Replica Set High Availability and Replica Set Elections.

Replica Set Read and Write Semantics

From the perspective of a client application, whether a MongoDB instance is running as a single server (i.e. “standalone”) or a replica set is transparent.

By default, in MongoDB, read operations to a replica set return results from the primary and are consistent with the last write operation.

Users may configure read preference on a per-connection basis to prefer that the read operations return on the secondary members. If clients configure the read preference to permit secondary reads, read operations can return from secondary members that have not replicated more recent updates or operations. When reading from a secondary, a query may return data that reflects a previous state.

This behavior is sometimes characterized as eventual consistency because the secondary member’s state will eventually reflect the primary’s state and MongoDB cannot guarantee strict consistency for read operations from secondary members.

To guarantee consistency for reads from secondary members, you can configure the client and driver to ensure that write operations succeed on all members before completing successfully. See Write Concern for more information. Additionally, such configuration can help prevent Rollbacks During Replica Set Failover during a failover.

Note

Sharded clusters where the shards are also replica sets provide the same operational semantics with regards to write and read operations.

Write Concern for Replica Sets

Write concern is the guarantee an application requires from MongoDB to consider a write operation successful.

Read Preference

Applications specify read preference to control how drivers direct read operations to members of the replica set.

Read Preference Processes

With replica sets, read operations may have additional semantics and behavior.

Write Concern for Replica Sets

Read Preference

Read Preference Processes

Write Concern for Replica Sets

From the perspective of a client application, whether a MongoDB instance is running as a single server (i.e. “standalone”) or a replica set is transparent. However, replica sets offer some configuration options for write. [1]

[1]
Sharded clusters where the shards are also replica sets provide the same configuration options with regards to write and read operations.

Verify Write Operations to Replica Sets

For a replica set, the default write concern confirms write operations only on the primary. You can, however, override this default write concern, such as to confirm write operations on a specified number of the replica set members.

To override the default write concern, specify a write concern with each write operation. For example, the following method includes a write concern that specifies that the method return only after the write propagates to the primary and at least one secondary or the method times out after 5 seconds.

db.products.insert(
   { item: "envelopes", qty : 100, type: "Clasp" },
   { writeConcern: { w: 2, wtimeout: 5000 } }
)

You can include a timeout threshold for a write concern. This prevents write operations from blocking indefinitely if the write concern is unachievable. For example, if the write concern requires acknowledgement from 4 members of the replica set and the replica set has only available 3 members, the operation blocks until those members become available. See wtimeout.

See also

Write Method Acknowledgements

Modify Default Write Concern

You can modify the default write concern for a replica set by setting the getLastErrorDefaults setting in the replica set configuration. The following sequence of commands creates a configuration that waits for the write operation to complete on a majority of the set members before returning:

cfg = rs.conf()
cfg.settings = {}
cfg.settings.getLastErrorDefaults = { w: "majority", wtimeout: 5000 }
rs.reconfig(cfg)

If you issue a write operation with a specific write concern, the write operation uses its own write concern instead of the default.

Note

Use of insufficient write concern can lead to rollbacks in the case of replica set failover. Always ensure that your operations have specified the required write concern for your application.

See also

Write Concern and Write Concern Options

Custom Write Concerns

You can tag the members of replica sets and use the tags to create custom write concerns. See Configure Replica Set Tag Sets for information on configuring custom write concerns using tag sets.

Read Preference

Read preference describes how MongoDB clients route read operations to members of a replica set.

By default, an application directs its read operations to the primary member in a replica set. Reading from the primary guarantees that read operations reflect the latest version of a document. However, by distributing some or all reads to secondary members of the replica set, you can improve read throughput or reduce latency for an application that does not require fully up-to-date data.

Important

You must exercise care when specifying read preferences: modes other than primary can and will return stale data because the secondary queries will not include the most recent write operations to the replica set’s primary.

Use Cases

Indications

The following are common use cases for using non-primary read preference modes:

Running systems operations that do not affect the front-end application.

Note

Read preferences aren’t relevant to direct connections to a single mongod instance. However, in order to perform read operations on a direct connection to a secondary member of a replica set, you must set a read preference, such as secondary.

Providing local reads for geographically distributed applications.

If you have application servers in multiple data centers, you may consider having a geographically distributed replica set and using a non primary read preference or the nearest. This allows the client to read from the lowest-latency members, rather than always reading from the primary.

Maintaining availability during a failover.

Use primaryPreferred if you want an application to read from the primary under normal circumstances, but to allow stale reads from secondaries in an emergency. This provides a “read-only mode” for your application during a failover.

Counter-Indications

In general, do not use secondary and secondaryPreferred to provide extra capacity for reads, because:

All members of a replica have roughly equivalent write traffic, as a result secondaries will service reads at roughly the same rate as the primary.

Because replication is asynchronous and there is some amount of delay between a successful write operation and its replication to secondaries, reading from a secondary can return out-of-date data.

Distributing read operations to secondaries can compromise availability if any members of the set are unavailable because the remaining members of the set will need to be able to handle all application requests.

For queries of sharded collections, for clusters with the balancer active, secondaries may return stale results with missing or duplicated data because of incomplete or terminated migrations.

Sharding increases read and write capacity by distributing read and write operations across a group of machines, and is often a better strategy for adding capacity.

See Read Preference Processes for more information about the internal application of read preferences.

Read Preference Modes

New in version 2.2.

Important

All read preference modes except primary may return stale data because secondaries replicate operations from the primary with some delay. Ensure that your application can tolerate stale data if you choose to use a non-primary mode.

MongoDB drivers support five read preference modes.

Read Preference Mode | Description
primary | Default mode. All operations read from the current replica set primary.
primaryPreferred | In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
secondary | All operations read from the secondary members of the replica set.
secondaryPreferred | In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
nearest | Operations read from member of the replica set with the least network latency, irrespective of the member’s type.

The syntax for specifying the read preference mode is specific to the driver and to the idioms of the host language [http://api.mongodb.org/].

Read preference modes are also available to clients connecting to a sharded cluster through a mongos. The mongos instance obeys specified read preferences when connecting to the replica set that provides each shard in the cluster.

In the mongo shell, the readPref() cursor method provides access to read preferences.

For more information, see read preference background and read preference behavior. See also the documentation for your driver [http://api.mongodb.org/].

Tag Sets

Tag sets allow you to target read operations to specific members of a replica set.

Custom read preferences and write concerns evaluate tags sets in different ways. Read preferences consider the value of a tag when selecting a member to read from. Write concerns ignore the value of a tag to when selecting a member, except to consider whether or not the value is unique.

You can specify tag sets with the following read preference modes:

primaryPreferred

secondary

secondaryPreferred

nearest

Tags are not compatible with mode primary and, in general, only apply when selecting a secondary member of a set for a read operation. However, the nearest read mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.

All interfaces use the same member selection logic to choose the member to which to direct read operations, basing the choice on read preference mode and tag sets.

For information on configuring tag sets, see the Configure Replica Set Tag Sets tutorial.

For more information on how read preference modes interact with tag sets, see the documentation for each read preference mode.

Read Preference Processes

Changed in version 2.2.

MongoDB drivers use the following procedures to direct operations to replica sets and sharded clusters. To determine how to route their operations, applications periodically update their view of the replica set’s state, identifying which members are up or down, which member is primary, and verifying the latency to each mongod instance.

Member Selection

Clients, by way of their drivers, and mongos instances for sharded clusters, periodically update their view of the replica set’s state.

When you select non-primary read preference, the driver will determine which member to target using the following process:

Assembles a list of suitable members, taking into account member type (i.e. secondary, primary, or all members).

Excludes members not matching the tag sets, if specified.

Determines which suitable member is the closest to the client in absolute terms.

Builds a list of members that are within a defined ping distance (in milliseconds) of the “absolute nearest” member.

Applications can configure the threshold used in this stage. The default “acceptable latency” is 15 milliseconds, which you can override in the drivers with their own secondaryAcceptableLatencyMS option. For mongos you can use the --localThreshold or localPingThresholdMs runtime options to set this value.

Selects a member from these hosts at random. The member receives the read operation.

Drivers can then associate the thread or connection with the selected member. This request association is configurable by the application. See your driver documentation about request association configuration and default behavior.

Request Association

Important

Request association is configurable by the application. See your driver documentation about request association configuration and default behavior.

Because secondary members of a replica set may lag behind the current primary by different amounts, reads for secondary members may reflect data at different points in time. To prevent sequential reads from jumping around in time, the driver can associate application threads to a specific member of the set after the first read, thereby preventing reads from other members. The thread will continue to read from the same member until:

The application performs a read with a different read preference,

The thread terminates, or

The client receives a socket exception, as is the case when there’s a network error or when the mongod closes connections during a failover. This triggers a retry, which may be transparent to the application.

When using request association, if the client detects that the set has elected a new primary, the driver will discard all associations between threads and members.

Auto-Retry

Connections between MongoDB drivers and mongod instances in a replica set must balance two concerns:

The client should attempt to prefer current results, and any connection should read from the same member of the replica set as much as possible. Requests should prefer request association (e.g. pinning).

The client should minimize the amount of time that the database is inaccessible as the result of a connection issue, networking problem, or failover in a replica set.

As a result, MongoDB drivers:

Reuse a connection to a specific mongod for as long as possible after establishing a connection to that instance. This connection is pinned to this mongod.

Attempt to reconnect to a new member, obeying existing read preference modes, if the connection to mongod is lost.

Reconnections are transparent to the application itself. If the connection permits reads from secondary members, after reconnecting, the application can receive two sequential reads returning from different secondaries. Depending on the state of the individual secondary member’s replication, the documents can reflect the state of your database at different moments.

Return an error only after attempting to connect to three members of the set that match the read preference mode and tag set. If there are fewer than three members of the set, the client will error after connecting to all existing members of the set.

After this error, the driver selects a new member using the specified read preference mode. In the absence of a specified read preference, the driver uses primary.

After detecting a failover situation, [1] the driver attempts to refresh the state of the replica set as quickly as possible.

[1]
When a failover occurs, all members of the set close all client connections that produce a socket error in the driver. This behavior prevents or minimizes rollback.

Read Preference in Sharded Clusters

Changed in version 2.2: Before version 2.2, mongos did not support the read preference mode semantics.

In most sharded clusters, each shard consists of a replica set. As such, read preferences are also applicable. With regard to read preference, read operations in a sharded cluster are identical to unsharded replica sets.

Unlike simple replica sets, in sharded clusters, all interactions with the shards pass from the clients to the mongos instances that are actually connected to the set members. mongos is then responsible for the application of read preferences, which is transparent to applications.

There are no configuration changes required for full support of read preference modes in sharded environments, as long as the mongos is at least version 2.2. All mongos maintain their own connection pool to the replica set members. As a result:

A request without a specified preference has primary, the default, unless, the mongos reuses an existing connection that has a different mode set.

To prevent confusion, always explicitly set your read preference mode.

All nearest and latency calculations reflect the connection between the mongos and the mongod instances, not the client and the mongod instances.

This produces the desired result, because all results must pass through the mongos before returning to the client.

Replication Processes

Members of a replica set replicate data continuously. First, a member uses initial sync to capture the data set. Then the member continuously records and applies every operation that modifies the data set. Every member records operations in its oplog, which is a capped collection.

Replica Set Oplog

The oplog records all operations that modify the data in the replica set.

Replica Set Data Synchronization

Secondaries must replicate all changes accepted by the primary. This process is the basis of replica set operations.

Replica Set Oplog

Replica Set Data Synchronization

Replica Set Oplog

The oplog (operations log) is a special capped collection that keeps a rolling record of all operations that modify the data stored in your databases. MongoDB applies database operations on the primary and then records the operations on the primary’s oplog. The secondary members then copy and apply these operations in an asynchronous process. All replica set members contain a copy of the oplog, in the local.oplog.rs collection, which allows them to maintain the current state of the database.

To facilitate replication, all replica set members send heartbeats (pings) to all other members. Any member can import oplog entries from any other member.

Whether applied once or multiple times to the target dataset, each operation in the oplog produces the same results, i.e. each operation in the oplog is idempotent. For proper replication operations, entries in the oplog must be idempotent:

initial sync

post-rollback catch-up

sharding chunk migrations

Oplog Size

When you start a replica set member for the first time, MongoDB creates an oplog of a default size. The size depends on the architectural details of your operating system.

In most cases, the default oplog size is sufficient. For example, if an oplog is 5% of free disk space and fills up in 24 hours of operations, then secondaries can stop copying entries from the oplog for up to 24 hours without becoming too stale to continue replicating. However, most replica sets have much lower operation volumes, and their oplogs can hold much higher numbers of operations.

Before mongod creates an oplog, you can specify its size with the oplogSizeMB option. However, after you have started a replica set member for the first time, you can only change the size of the oplog using the Change the Size of the Oplog procedure.

By default, the size of the oplog is as follows:

For 64-bit Linux, Solaris, FreeBSD, and Windows systems, MongoDB allocates 5% of the available free disk space, but will always allocate at least 1 gigabyte and never more than 50 gigabytes.

For 64-bit OS X systems, MongoDB allocates 183 megabytes of space to the oplog.

For 32-bit systems, MongoDB allocates about 48 megabytes of space to the oplog.

Workloads that Might Require a Larger Oplog Size

If you can predict your replica set’s workload to resemble one of the following patterns, then you might want to create an oplog that is larger than the default. Conversely, if your application predominantly performs reads with a minimal amount of write operations, a smaller oplog may be sufficient.

The following workloads might require a larger oplog size.

Updates to Multiple Documents at Once

The oplog must translate multi-updates into individual operations in order to maintain idempotency. This can use a great deal of oplog space without a corresponding increase in data size or disk use.

Deletions Equal the Same Amount of Data as Inserts

If you delete roughly the same amount of data as you insert, the database will not grow significantly in disk use, but the size of the operation log can be quite large.

Significant Number of In-Place Updates

If a significant portion of the workload is in-place updates, the database records a large number of operations but does not change the quantity of data on disk.

Oplog Status

To view oplog status, including the size and the time range of operations, issue the rs.printReplicationInfo() method. For more information on oplog status, see Check the Size of the Oplog.

Under various exceptional situations, updates to a secondary’s oplog might lag behind the desired performance time. Use db.getReplicationInfo() from a secondary member and the replication status output to assess the current state of replication and determine if there is any unintended replication delay.

See Replication Lag for more information.

Replica Set Data Synchronization

In order to maintain up-to-date copies of the shared data set, members of a replica set sync or replicate data from other members. MongoDB uses two forms of data synchronization: initial sync to populate new members with the full data set, and replication to apply ongoing changes to the entire data set.

Initial Sync

Initial sync copies all the data from one member of the replica set to another member. A member uses initial sync when the member has no data, such as when the member is new, or when the member has data but is missing a history of the set’s replication.

When you perform an initial sync, MongoDB does the following:

Clones all databases. To clone, the mongod queries every collection in each source database and inserts all data into its own copies of these collections. At this time, _id indexes are also built.

Applies all changes to the data set. Using the oplog from the source, the mongod updates its data set to reflect the current state of the replica set.

Builds all indexes on all collections (except _id indexes, which were already completed).

When the mongod finishes building all index builds, the member can transition to a normal state, i.e. secondary.

To perform an initial sync, see Resync a Member of a Replica Set.

Replication

Replica set members replicate data continuously after the initial sync. This process keeps the members up to date with all changes to the replica set’s data. In most cases, secondaries synchronize from the primary. Secondaries may automatically change their sync targets if needed based on changes in the ping time and state of other members’ replication.

For a member to sync from another, both members must have the same value for the buildIndexes setting.

Beginning in version 2.2, secondaries avoid syncing from delayed members and hidden members.

Validity and Durability

In a replica set, only the primary can accept write operations. Writing only to the primary provides strict consistency among members.

Journaling provides single-instance write durability. Without journaling, if a MongoDB instance terminates ungracefully, you must assume that the database is in an invalid state.

Multithreaded Replication

MongoDB applies write operations in batches using multiple threads to improve concurrency. MongoDB groups batches by namespace and applies operations using a group of threads, but always applies the write operations to a namespace in order.

While applying a batch, MongoDB blocks all reads. As a result, secondaries can never return data that reflects a state that never existed on the primary.

Pre-Fetching Indexes to Improve Replication Throughput

To help improve the performance of applying oplog entries, MongoDB fetches memory pages that hold affected data and indexes. This pre-fetch stage minimizes the amount of time MongoDB holds the write lock while applying oplog entries. By default, secondaries will pre-fetch all Indexes.

Optionally, you can disable all pre-fetching or only pre-fetch the index on the _id field. See the secondaryIndexPrefetch setting for more information.

Master Slave Replication

Important

Replica sets replace master-slave replication for most use cases. If possible, use replica sets rather than master-slave replication for all new production deployments. This documentation remains to support legacy deployments and for archival purposes only.

In addition to providing all the functionality of master-slave deployments, replica sets are also more robust for production use. Master-slave replication preceded replica sets and made it possible to have a large number of non-master (i.e. slave) nodes, as well as to restrict replicated operations to only a single database; however, master-slave replication provides less redundancy and does not automate failover. See Deploy Master-Slave Equivalent using Replica Sets for a replica set configuration that is equivalent to master-slave replication. If you wish to convert an existing master-slave deployment to a replica set, see Convert a Master-Slave Deployment to a Replica Set.

Fundamental Operations

Initial Deployment

To configure a master-slave deployment, start two mongod instances: one in master mode, and the other in slave mode.

To start a mongod instance in master mode, invoke mongod as follows:

mongod --master --dbpath /data/masterdb/

With the --master option, the mongod will create a local.oplog.$main collection, which the “operation log” that queues operations that the slaves will apply to replicate operations from the master. The --dbpath is optional.

To start a mongod instance in slave mode, invoke mongod as follows:

mongod --slave --source <masterhostname><:<port>> --dbpath /data/slavedb/

Specify the hostname and port of the master instance to the --source argument. The --dbpath is optional.

For slave instances, MongoDB stores data about the source server in the local.sources collection.

Configuration Options for Master-Slave Deployments

As an alternative to specifying the --source run-time option, can add a document to local.sources specifying the master instance, as in the following operation in the mongo shell:

1
2
3

use local
db.sources.find()
db.sources.insert( { host: <masterhostname> <,only: databasename> } );

In line 1, you switch context to the local database. In line 2, the find() operation should return no documents, to ensure that there are no documents in the sources collection. Finally, line 3 uses db.collection.insert() to insert the source document into the local.sources collection. The model of the local.sources document is as follows:

host

The host field specifies the mastermongod instance, and holds a resolvable hostname, i.e. IP address, or a name from a host file, or preferably a fully qualified domain name.

You can append <:port> to the host name if the mongod is not running on the default 27017 port.

only

Optional. Specify a name of a database. When specified, MongoDB will only replicate the indicated database.

Operational Considerations for Replication with Master Slave Deployments

Master instances store operations in an oplog which is a capped collection. As a result, if a slave falls too far behind the state of the master, it cannot “catchup” and must re-sync from scratch. Slave may become out of sync with a master if:

The slave falls far behind the data updates available from that master.

The slave stops (i.e. shuts down) and restarts later after the master has overwritten the relevant operations from the master.

When slaves are out of sync, replication stops. Administrators must intervene manually to restart replication. Use the resync command. Alternatively, the --autoresync allows a slave to restart replication automatically, after ten second pause, when the slave falls out of sync with the master. With --autoresync specified, the slave will only attempt to re-sync once in a ten minute period.

To prevent these situations you should specify a larger oplog when you start the master instance, by adding the --oplogSize option when starting mongod. If you do not specify --oplogSize, mongod will allocate 5% of available disk space on start up to the oplog, with a minimum of 1GB for 64bit machines and 50MB for 32bit machines.

Run time Master-Slave Configuration

MongoDB provides a number of command line options for mongod instances in master-slave deployments. See the Master-Slave Replication Command Line Options for options.

Diagnostics

On a master instance, issue the following operation in the mongo shell to return replication status from the perspective of the master:

rs.printReplicationInfo()

New in version 2.6: rs.printReplicationInfo(). For previous versions, use db.printReplicationInfo().

On a slave instance, use the following operation in the mongo shell to return the replication status from the perspective of the slave:

rs.printSlaveReplicationInfo()

New in version 2.6: rs.printSlaveReplicationInfo(). For previous versions, use db.printSlaveReplicationInfo().

Use the serverStatus as in the following operation, to return status of the replication:

db.serverStatus()

See server status repl fields for documentation of the relevant section of output.

Security

When running with authorization enabled, in master-slave deployments configure a keyFile so that slave mongod instances can authenticate and communicate with the master mongod instance.

To enable authentication and configure the keyFile add the following option to your configuration file:

keyFile = /srv/mongodb/keyfile

Note

You may chose to set these run-time configuration options using the --keyFile option on the command line.

Setting keyFile enables authentication and specifies a key file for the mongod instances to use when authenticating to each other. The content of the key file is arbitrary but must be the same on all members of the deployment can connect to each other.

The key file must be less one kilobyte in size and may only contain characters in the base64 set. The key file must not have group or “world” permissions on UNIX systems. Use the following command to use the OpenSSL package to generate “random” content for use in a key file:

openssl rand -base64 741

See also

Security for more information about security in MongoDB

Ongoing Administration and Operation of Master-Slave Deployments

Deploy Master-Slave Equivalent using Replica Sets

If you want a replication configuration that resembles master-slave replication, using replica sets replica sets, consider the following replica configuration document. In this deployment hosts <master> and <slave> [1] provide replication that is roughly equivalent to a two-instance master-slave deployment:

{
  _id : 'setName',
  members : [
    { _id : 0, host : "<master>", priority : 1 },
    { _id : 1, host : "<slave>", priority : 0, votes : 0 }
  ]
}

See Replica Set Configuration for more information about replica set configurations.

[1]
In replica set configurations, the host field must hold a resolvable hostname.

Convert a Master-Slave Deployment to a Replica Set

To convert a master-slave deployment to a replica set, restart the current master as a one-member replica set. Then remove the data directories from previous secondaries and add them as new secondaries to the new replica set.

To confirm that the current instance is master, run:

db.isMaster()

This should return a document that resembles the following:

{
        "ismaster" : true,
        "maxBsonObjectSize" : 16777216,
        "maxMessageSizeBytes" : 48000000,
        "localTime" : ISODate("2013-07-08T20:15:13.664Z"),
        "ok" : 1
}

Shut down the mongod processes on the master and all slave(s), using the following command while connected to each instance:

db.adminCommand({shutdown : 1, force : true})

Back up your /data/db directories, in case you need to revert to the master-slave deployment.

Start the former master with the --replSet option, as in the following:

mongod --replSet <setname>

Connect to the mongod with the mongo shell, and initiate the replica set with the following command:

rs.initiate()

When the command returns, you will have successfully deployed a one-member replica set. You can check the status of your replica set at any time by running the following command:

rs.status()

You can now follow the convert a standalone to a replica set tutorial to deploy your replica set, picking up from the Expand the Replica Set section.

Failing over to a Slave (Promotion)

To permanently failover from a unavailable or damaged master (A in the following example) to a slave (B):

Shut down A.

Stop mongod on B.

Back up and move all data files that begin with local on B from the dbPath.

Warning

Removing local.* is irrevocable and cannot be undone. Perform this step with extreme caution.

Restart mongod on B with the --master option.

Note

This is a one time operation, and is not reversible. A cannot become a slave of B until it completes a full resync.

Inverting Master and Slave

If you have a master (A) and a slave (B) and you would like to reverse their roles, follow this procedure. The procedure assumes A is healthy, up-to-date and available.

If A is not healthy but the hardware is okay (power outage, server crash, etc.), skip steps 1 and 2 and in step 8 replace all of A‘s files with B‘s files in step 8.

If A is not healthy and the hardware is not okay, replace A with a new machine. Also follow the instructions in the previous paragraph.

To invert the master and slave in a deployment:

Halt writes on A using the fsync command.

Make sure B is up to date with the state of A.

Shut down B.

Back up and move all data files that begin with local on B from the dbPath to remove the existing local.sources data.

Warning

Removing local.* is irrevocable and cannot be undone. Perform this step with extreme caution.

Start B with the --master option.

Do a write on B, which primes the oplog to provide a new sync start point.

Shut down B. B will now have a new set of data files that start with local.

Shut down A and replace all files in the dbPath of A that start with local with a copy of the files in the dbPath of B that begin with local.

Considering compressing the local files from B while you copy them, as they may be quite large.

Start B with the --master option.

Start A with all the usual slave options, but include fastsync.

Creating a Slave from an Existing Master’s Disk Image

If you can stop write operations to the master for an indefinite period, you can copy the data files from the master to the new slave and then start the slave with --fastsync.

Warning

Be careful with --fastsync. If the data on both instances is not identical, a discrepancy will exist forever.

fastsync is a way to start a slave by starting with an existing master disk image/backup. This option declares that the administrator guarantees the image is correct and completely up-to-date with that of the master. If you have a full and complete copy of data from a master you can use this option to avoid a full synchronization upon starting the slave.

Creating a Slave from an Existing Slave’s Disk Image

You can just copy the other slave’s data file snapshot without any special options. Only take data snapshots when a mongod process is down or locked using db.fsyncLock().

Resyncing a Slave that is too Stale to Recover

Slaves asynchronously apply write operations from the master that the slaves poll from the master’s oplog. The oplog is finite in length, and if a slave is too far behind, a full resync will be necessary. To resync the slave, connect to a slave using the mongo and issue the resync command:

use admin
db.runCommand( { resync: 1 } )

This forces a full resync of all data (which will be very slow on a large database). You can achieve the same effect by stopping mongod on the slave, deleting the entire content of the dbPath on the slave, and restarting the mongod.

Slave Chaining

Slaves cannot be “chained.” They must all connect to the master directly.

If a slave attempts “slave from” another slave you will see the following line in the mongod long of the shell:

assertion 13051 tailable cursor requested on non capped collection ns:local.oplog.$main

Correcting a Slave’s Source

To change a slave’s source, manually modify the slave’s local.sources collection.

Example

Consider the following: If you accidentally set an incorrect hostname for the slave’s source, as in the following example:

mongod --slave --source prod.mississippi

You can correct this, by restarting the slave without the --slave and --source arguments:

mongod

Connect to this mongod instance using the mongo shell and update the local.sources collection, with the following operation sequence:

use local

db.sources.update( { host : "prod.mississippi" },
                   { $set : { host : "prod.mississippi.example.net" } } )

Restart the slave with the correct command line arguments or with no --source option. After configuring local.sources the first time, the --source will have no subsequent effect. Therefore, both of the following invocations are correct:

mongod --slave --source prod.mississippi.example.net

or

mongod --slave

The slave now polls data from the correct master.

Replica Set Tutorials

The administration of replica sets includes the initial deployment of the set, adding and removing members to a set, and configuring the operational parameters and properties of the set. Administrators generally need not intervene in failover or replication processes as MongoDB automates these functions. In the exceptional situations that require manual interventions, the tutorials in these sections describe processes such as resyncing a member. The tutorials in this section form the basis for all replica set administration.

Replica Set Deployment Tutorials

Instructions for deploying replica sets, as well as adding and removing members from an existing replica set.

Deploy a Replica Set

Configure a three-member replica set for production systems.

Convert a Standalone to a Replica Set

Convert an existing standalone mongod instance into a three-member replica set.

Add Members to a Replica Set

Add a new member to an existing replica set.

Remove Members from Replica Set

Remove a member from a replica set.

Continue reading from Replica Set Deployment Tutorials for additional tutorials of related to setting up replica set deployments.

Member Configuration Tutorials

Tutorials that describe the process for configuring replica set members.

Adjust Priority for Replica Set Member

Change the precedence given to a replica set members in an election for primary.

Prevent Secondary from Becoming Primary

Make a secondary member ineligible for election as primary.

Configure a Hidden Replica Set Member

Configure a secondary member to be invisible to applications in order to support significantly different usage, such as a dedicated backups.

Continue reading from Member Configuration Tutorials for more tutorials that describe replica set configuration.

Replica Set Maintenance Tutorials

Procedures and tasks for common operations on active replica set deployments.

Change the Size of the Oplog

Increase the size of the oplog which logs operations. In most cases, the default oplog size is sufficient.

Resync a Member of a Replica Set

Sync the data on a member. Either perform initial sync on a new member or resync the data on an existing member that has fallen too far behind to catch up by way of normal replication.

Force a Member to Become Primary

Force a replica set member to become primary.

Change Hostnames in a Replica Set

Update the replica set configuration to reflect changes in members’ hostnames.

Continue reading from Replica Set Maintenance Tutorials for descriptions of additional replica set maintenance procedures.

Troubleshoot Replica Sets

Describes common issues and operational challenges for replica sets. For additional diagnostic information, see FAQ: MongoDB Diagnostics.

Replica Set Deployment Tutorials

Deploy a Replica Set

Deploy a Replica Set for Testing and Development

Deploy a Geographically Redundant Replica Set

Add an Arbiter to Replica Set

Convert a Standalone to a Replica Set

Add Members to a Replica Set

Remove Members from Replica Set

Replace a Replica Set Member

Member Configuration Tutorials

Adjust Priority for Replica Set Member

Prevent Secondary from Becoming Primary

Configure a Hidden Replica Set Member

Configure a Delayed Replica Set Member

Configure Non-Voting Replica Set Member

Convert a Secondary to an Arbiter

Replica Set Maintenance Tutorials

Change the Size of the Oplog

Perform Maintenance on Replica Set Members

Force a Member to Become Primary

Resync a Member of a Replica Set

Configure Replica Set Tag Sets

Reconfigure a Replica Set with Unavailable Members

Manage Chained Replication

Change Hostnames in a Replica Set

Configure a Secondary’s Sync Target

Troubleshoot Replica Sets

Replica Set Deployment Tutorials

The following tutorials provide information in deploying replica sets.

See also

Security Deployment Tutorials for additional related tutorials.

Deploy a Replica Set

Configure a three-member replica set for production systems.

Deploy a Replica Set for Testing and Development

Configure a three-member replica set for either development or testing systems.

Deploy a Geographically Redundant Replica Set

Create a geographically redundant replica set to protect against location-centered availability limitations (e.g. network and power interruptions).

Add an Arbiter to Replica Set

Add an arbiter give a replica set an odd number of voting members to prevent election ties.

Convert a Standalone to a Replica Set

Convert an existing standalone mongod instance into a three-member replica set.

Add Members to a Replica Set

Add a new member to an existing replica set.

Remove Members from Replica Set

Remove a member from a replica set.

Replace a Replica Set Member

Update the replica set configuration when the hostname of a member’s corresponding mongod instance has changed.

Deploy a Replica Set

Deploy a Replica Set for Testing and Development

Deploy a Geographically Redundant Replica Set

Add an Arbiter to Replica Set

Convert a Standalone to a Replica Set

Add Members to a Replica Set

Remove Members from Replica Set

Replace a Replica Set Member

Deploy a Replica Set

This tutorial describes how to create a three-member replica set from three existing mongod instances running with access control disabled.

To deploy a replica set with enabled access control, see Deploy Replica Set and Configure Authentication and Authorization. If you wish to deploy a replica set from a single MongoDB instance, see Convert a Standalone to a Replica Set. For more information on replica set deployments, see the Replication and Replica Set Deployment Architectures documentation.

Overview

Three member replica sets provide enough redundancy to survive most network partitions and other system failures. These sets also have sufficient capacity for many distributed read operations. Replica sets should always have an odd number of members. This ensures that elections will proceed smoothly. For more about designing replica sets, see the Replication overview.

The basic procedure is to start the mongod instances that will become members of the replica set, configure the replica set itself, and then add the mongod instances to it.

Requirements

For production deployments, you should maintain as much separation between members as possible by hosting the mongod instances on separate machines. When using virtual machines for production deployments, you should place each mongod instance on a separate host server serviced by redundant power circuits and redundant network paths.

Before you can deploy a replica set, you must install MongoDB on each system that will be part of your replica set. If you have not already installed MongoDB, see the installation tutorials.

Before creating your replica set, you should verify that your network configuration allows all possible connections between each member. For a successful replica set deployment, every member must be able to connect to every other member. For instructions on how to check your connection, see Test Connections Between all Members.

Considerations When Deploying a Replica Set

Architecture

In a production, deploy each member of the replica set to its own machine and if possible bind to the standard MongoDB port of 27017. Use the bind_ip option to ensure that MongoDB listens for connections from applications on configured addresses.

For a geographically distributed replica sets, ensure that the majority of the set’s mongod instances reside in the primary site.

See Replica Set Deployment Architectures for more information.

Connectivity

Ensure that network traffic can pass between all members of the set and all clients in the network securely and efficiently. Consider the following:

Establish a virtual private network. Ensure that your network topology routes all traffic between members within a single site over the local area network.

Configure access control to prevent connections from unknown clients to the replica set.

Configure networking and firewall rules so that incoming and outgoing packets are permitted only on the default MongoDB port and only from within your deployment.

Finally ensure that each member of a replica set is accessible by way of resolvable DNS or hostnames. You should either configure your DNS names appropriately or set up your systems’ /etc/hosts file to reflect this configuration.

Configuration

Specify the run time configuration on each system in a configuration file stored in /etc/mongodb.conf or a related location. Create the directory where MongoDB stores data files before deploying MongoDB.

For more information about the run time options used above and other configuration options, see Configuration File Options.

Procedure

The following procedure outlines the steps to deploy a replica set when access control is disabled.

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

Step 1: Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

2

Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

Step 2: Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

3

Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

Step 3: Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

4

Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

Step 4: Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

5

Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

Step 5: Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

6

Check the status of the replica set.

Use the rs.status() operation:

rs.status()

Step 6: Check the status of the replica set.

Use the rs.status() operation:

rs.status()

See also

Deploy Replica Set and Configure Authentication and Authorization

Deploy a Replica Set for Testing and Development

This procedure describes deploying a replica set in a development or test environment. For a production deployment, refer to the Deploy a Replica Set tutorial.

This tutorial describes how to create a three-member replica set from three existing mongod instances running with access control disabled.

To deploy a replica set with enabled access control, see Deploy Replica Set and Configure Authentication and Authorization. If you wish to deploy a replica set from a single MongoDB instance, see Convert a Standalone to a Replica Set. For more information on replica set deployments, see the Replication and Replica Set Deployment Architectures documentation.

Overview

Three member replica sets provide enough redundancy to survive most network partitions and other system failures. These sets also have sufficient capacity for many distributed read operations. Replica sets should always have an odd number of members. This ensures that elections will proceed smoothly. For more about designing replica sets, see the Replication overview.

The basic procedure is to start the mongod instances that will become members of the replica set, configure the replica set itself, and then add the mongod instances to it.

Requirements

For test and development systems, you can run your mongod instances on a local system, or within a virtual instance.

Before you can deploy a replica set, you must install MongoDB on each system that will be part of your replica set. If you have not already installed MongoDB, see the installation tutorials.

Before creating your replica set, you should verify that your network configuration allows all possible connections between each member. For a successful replica set deployment, every member must be able to connect to every other member. For instructions on how to check your connection, see Test Connections Between all Members.

Considerations

Replica Set Naming

Important

These instructions should only be used for test or development deployments.

The examples in this procedure create a new replica set named rs0.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

You will begin by starting three mongod instances as members of a replica set named rs0.

Procedure

Create the necessary data directories for each member by issuing a command similar to the following:

mkdir -p /srv/mongodb/rs0-0 /srv/mongodb/rs0-1 /srv/mongodb/rs0-2

This will create directories called “rs0-0”, “rs0-1”, and “rs0-2”, which will contain the instances’ database files.

Start your mongod instances in their own shell windows by issuing the following commands:

First member:

mongod --port 27017 --dbpath /srv/mongodb/rs0-0 --replSet rs0 --smallfiles --oplogSize 128

Second member:

mongod --port 27018 --dbpath /srv/mongodb/rs0-1 --replSet rs0 --smallfiles --oplogSize 128

Third member:

mongod --port 27019 --dbpath /srv/mongodb/rs0-2 --replSet rs0 --smallfiles --oplogSize 128

This starts each instance as a member of a replica set named rs0, each running on a distinct port, and specifies the path to your data directory with the --dbpath setting. If you are already using the suggested ports, select different ports.

The --smallfiles and --oplogSize settings reduce the disk space that each mongod instance uses. This is ideal for testing and development deployments as it prevents overloading your machine. For more information on these and other configuration options, see Configuration File Options.

Connect to one of your mongod instances through the mongo shell. You will need to indicate which instance by specifying its port number. For the sake of simplicity and clarity, you may want to choose the first one, as in the following command;

mongo --port 27017

In the mongo shell, use rs.initiate() to initiate the replica set. You can create a replica set configuration object in the mongo shell environment, as in the following example:

rsconf = {
           _id: "rs0",
           members: [
                      {
                       _id: 0,
                       host: "<hostname>:27017"
                      }
                    ]
         }

replacing <hostname> with your system’s hostname, and then pass the rsconf file to rs.initiate() as follows:

rs.initiate( rsconf )

Display the current replica configuration by issuing the following command:

rs.conf()

The replica set configuration object resembles the following

{
   "_id" : "rs0",
   "version" : 4,
   "members" : [
      {
         "_id" : 1,
         "host" : "localhost:27017"
      }
   ]
}

In the mongo shell connected to the primary, add the second and third mongod instances to the replica set using the rs.add() method. Replace <hostname> with your system’s hostname in the following examples:

rs.add("<hostname>:27018")
rs.add("<hostname>:27019")

When complete, you should have a fully functional replica set. The new replica set will elect a primary.

Check the status of your replica set at any time with the rs.status() operation.

See also

The documentation of the following shell functions for more information:

rs.initiate()

rs.conf()

rs.reconfig()

rs.add()

You may also consider the simple setup script [https://github.com/mongodb/mongo-snippets/blob/master/replication/simple-setup.py] as an example of a basic automatically-configured replica set.

Refer to Replica Set Read and Write Semantics for a detailed explanation of read and write semantics in MongoDB.

Deploy a Geographically Redundant Replica Set

Overview

This tutorial outlines the process for deploying a replica set with members in multiple locations. The tutorial addresses three-member sets, four-member sets, and sets with more than four members.

For appropriate background, see Replication and Replica Set Deployment Architectures. For related tutorials, see Deploy a Replica Set and Add Members to a Replica Set.

Considerations

While replica sets provide basic protection against single-instance failure, replica sets whose members are all located in a single facility are susceptible to errors in that facility. Power outages, network interruptions, and natural disasters are all issues that can affect replica sets whose members are colocated. To protect against these classes of failures, deploy a replica set with one or more members in a geographically distinct facility or data center to provide redundancy.

Prerequisites

In general, the requirements for any geographically redundant replica set are as follows:

Ensure that a majority of the voting members are within a primary facility, “Site A”. This includes priority 0 members and arbiters. Deploy other members in secondary facilities, “Site B”, “Site C”, etc., to provide additional copies of the data. See Determine the Distribution of Members for more information on the voting requirements for geographically redundant replica sets.

If you deploy a replica set with an even number of members, deploy an arbiter on Site A. The arbiter must be on site A to keep the majority there.

For instance, for a three-member replica set you need two instances in a Site A, and one member in a secondary facility, Site B. Site A should be the same facility or very close to your primary application infrastructure (i.e. application servers, caching layer, users, etc.)

A four-member replica set should have at least two members in Site A, with the remaining members in one or more secondary sites, as well as a single arbiter in Site A.

For all configurations in this tutorial, deploy each replica set member on a separate system. Although you may deploy more than one replica set member on a single system, doing so reduces the redundancy and capacity of the replica set. Such deployments are typically for testing purposes and beyond the scope of this tutorial.

This tutorial assumes you have installed MongoDB on each system that will be part of your replica set. If you have not already installed MongoDB, see the installation tutorials.

Procedures

General Considerations

Architecture

In a production, deploy each member of the replica set to its own machine and if possible bind to the standard MongoDB port of 27017. Use the bind_ip option to ensure that MongoDB listens for connections from applications on configured addresses.

For a geographically distributed replica sets, ensure that the majority of the set’s mongod instances reside in the primary site.

See Replica Set Deployment Architectures for more information.

Connectivity

Ensure that network traffic can pass between all members of the set and all clients in the network securely and efficiently. Consider the following:

Establish a virtual private network. Ensure that your network topology routes all traffic between members within a single site over the local area network.

Configure access control to prevent connections from unknown clients to the replica set.

Configure networking and firewall rules so that incoming and outgoing packets are permitted only on the default MongoDB port and only from within your deployment.

Finally ensure that each member of a replica set is accessible by way of resolvable DNS or hostnames. You should either configure your DNS names appropriately or set up your systems’ /etc/hosts file to reflect this configuration.

Configuration

Specify the run time configuration on each system in a configuration file stored in /etc/mongodb.conf or a related location. Create the directory where MongoDB stores data files before deploying MongoDB.

For more information about the run time options used above and other configuration options, see Configuration File Options.

Deploy a Geographically Redundant Three-Member Replica Set

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

Step 1: Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

2

Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

Step 2: Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

3

Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

Step 3: Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

4

Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

Step 4: Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

5

Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

Step 5: Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

7

Check the status of the replica set.

Use the rs.status() operation:

rs.status()

Step 7: Check the status of the replica set.

Use the rs.status() operation:

rs.status()

6

Configure the outside member as priority 0 members.

Configure the member located in Site B (in this example, mongodb2.example.net) as a priority 0 member.

View the replica set configuration to determine the members array position for the member. Keep in mind the array position is not the same as the _id:

rs.conf()

Copy the replica set configuration object to a variable (to cfg in the example below). Then, in the variable, set the correct priority for the member. Then pass the variable to rs.reconfig() to update the replica set configuration.

For example, to set priority for the third member in the array (i.e., the member at position 2), issue the following sequence of commands:

cfg = rs.conf()
cfg.members[2].priority = 0
rs.reconfig(cfg)

Note

The rs.reconfig() shell method can force the current primary to step down, causing an election. When the primary steps down, all clients will disconnect. This is the intended behavior. While most elections complete within a minute, always make sure any replica configuration changes occur during scheduled maintenance periods.

After these commands return, you have a geographically redundant three-member replica set.

Step 6: Configure the outside member as priority 0 members.

Configure the member located in Site B (in this example, mongodb2.example.net) as a priority 0 member.

View the replica set configuration to determine the members array position for the member. Keep in mind the array position is not the same as the _id:

rs.conf()

Copy the replica set configuration object to a variable (to cfg in the example below). Then, in the variable, set the correct priority for the member. Then pass the variable to rs.reconfig() to update the replica set configuration.

For example, to set priority for the third member in the array (i.e., the member at position 2), issue the following sequence of commands:

cfg = rs.conf()
cfg.members[2].priority = 0
rs.reconfig(cfg)

Note

The rs.reconfig() shell method can force the current primary to step down, causing an election. When the primary steps down, all clients will disconnect. This is the intended behavior. While most elections complete within a minute, always make sure any replica configuration changes occur during scheduled maintenance periods.

After these commands return, you have a geographically redundant three-member replica set.

Deploy a Geographically Redundant Four-Member Replica Set

A geographically redundant four-member deployment has two additional considerations:

One host (e.g. mongodb4.example.net) must be an arbiter. This host can run on a system that is also used for an application server or on the same machine as another MongoDB process.

You must decide how to distribute your systems. There are three possible architectures for the four-member replica set:

Three members in Site A, one priority 0 member in Site B, and an arbiter in Site A.

Two members in Site A, two priority 0 members in Site B, and an arbiter in Site A.

Two members in Site A, one priority 0 member in Site B, one priority 0 member in Site C, and an arbiter in site A.

In most cases, the first architecture is preferable because it is the least complex.

To deploy a geographically redundant four-member set:

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

Step 1: Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the replica set name through the replSet option. Specify any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies the replica set name through the --replSet command-line option:

mongod --replSet "rs0"

You can also specify the replica set name in the configuration file. To start mongod with a configuration file, specify the file with the --config option:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure a control script to manage this process. Control scripts are beyond the scope of this document.

2

Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

Step 2: Connect a mongo shell to a replica set member.

For example, to connect to a mongod running on localhost on the default port of 27017, simply issue:

mongo

3

Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

Step 3: Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

4

Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

Step 4: Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}

8

Check the status of the replica set.

Use the rs.status() operation:

rs.status()

Step 8: Check the status of the replica set.

Use the rs.status() operation:

rs.status()

5

Add the remaining members to the replica set.

Use rs.add() in a mongo shell connected to the current primary. The commands should resemble the following:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")
rs.add("mongodb3.example.net")

When complete, you should have a fully functional replica set. The new replica set will elect a primary.

Step 5: Add the remaining members to the replica set.

Use rs.add() in a mongo shell connected to the current primary. The commands should resemble the following:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")
rs.add("mongodb3.example.net")

When complete, you should have a fully functional replica set. The new replica set will elect a primary.

6

Add the arbiter.

In the same shell session, issue the following command to add the arbiter (e.g. mongodb4.example.net):

rs.addArb("mongodb4.example.net")

Step 6: Add the arbiter.

In the same shell session, issue the following command to add the arbiter (e.g. mongodb4.example.net):

rs.addArb("mongodb4.example.net")

7

Configure outside members as priority 0 members.

Configure each member located outside of Site A (e.g. mongodb3.example.net) as a priority 0 member.

View the replica set configuration to determine the members array position for the member. Keep in mind the array position is not the same as the _id:

rs.conf()

Copy the replica set configuration object to a variable (to cfg in the example below). Then, in the variable, set the correct priority for the member. Then pass the variable to rs.reconfig() to update the replica set configuration.

For example, to set priority for the third member in the array (i.e., the member at position 2), issue the following sequence of commands:

cfg = rs.conf()
cfg.members[2].priority = 0
rs.reconfig(cfg)

Note

The rs.reconfig() shell method can force the current primary to step down, causing an election. When the primary steps down, all clients will disconnect. This is the intended behavior. While most elections complete within a minute, always make sure any replica configuration changes occur during scheduled maintenance periods.

After these commands return, you have a geographically redundant four-member replica set.

Step 7: Configure outside members as priority 0 members.

Configure each member located outside of Site A (e.g. mongodb3.example.net) as a priority 0 member.

View the replica set configuration to determine the members array position for the member. Keep in mind the array position is not the same as the _id:

rs.conf()

Copy the replica set configuration object to a variable (to cfg in the example below). Then, in the variable, set the correct priority for the member. Then pass the variable to rs.reconfig() to update the replica set configuration.

For example, to set priority for the third member in the array (i.e., the member at position 2), issue the following sequence of commands:

cfg = rs.conf()
cfg.members[2].priority = 0
rs.reconfig(cfg)

Note

The rs.reconfig() shell method can force the current primary to step down, causing an election. When the primary steps down, all clients will disconnect. This is the intended behavior. While most elections complete within a minute, always make sure any replica configuration changes occur during scheduled maintenance periods.

After these commands return, you have a geographically redundant four-member replica set.

Deploy a Geographically Redundant Set with More than Four Members

The above procedures detail the steps necessary for deploying a geographically redundant replica set. Larger replica set deployments follow the same steps, but have additional considerations:

Never deploy more than seven voting members.

If you have an even number of members, use the procedure for a four-member set). Ensure that a single facility, “Site A”, always has a majority of the members by deploying the arbiter in that site. For example, if a set has six members, deploy at least three voting members in addition to the arbiter in Site A, and the remaining members in alternate sites.

If you have an odd number of members, use the procedure for a three-member set. Ensure that a single facility, “Site A” always has a majority of the members of the set. For example, if a set has five members, deploy three members within Site A and two members in other facilities.

If you have a majority of the members of the set outside of Site A and the network partitions to prevent communication between sites, the current primary in Site A will step down, even if none of the members outside of Site A are eligible to become primary.

Add an Arbiter to Replica Set

Arbiters are mongod instances that are part of a replica set but do not hold data. Arbiters participate in elections in order to break ties. If a replica set has an even number of members, add an arbiter.

Arbiters have minimal resource requirements and do not require dedicated hardware. You can deploy an arbiter on an application server or a monitoring host.

Important

Do not run an arbiter on the same system as a member of the replica set.

Considerations

An arbiter does not store data, but until the arbiter’s mongod process is added to the replica set, the arbiter will act like any other mongod process and start up with a set of data files and with a full-sized journal.

To minimize the default creation of data, set the following in the arbiter’s configuration file:

journal.enabled to false

Warning

Never set journal.enabled to false on a data-bearing node.

smallFiles to true

These settings are specific to arbiters. Do not set journal.enabled to false on a data-bearing node. Similarly, do not set smallFiles unless specifically indicated.

Add an Arbiter

Create a data directory (e.g. dbPath) for the arbiter. The mongod instance uses the directory for configuration data. The directory will not hold the data set. For example, create the /data/arb directory:

mkdir /data/arb

Start the arbiter. Specify the data directory and the replica set name. The following, starts an arbiter using the /data/arb dbPath for the rs replica set:

mongod --port 30000 --dbpath /data/arb --replSet rs

Connect to the primary and add the arbiter to the replica set. Use the rs.addArb() method, as in the following example:

rs.addArb("m1.example.net:30000")

This operation adds the arbiter running on port 30000 on the m1.example.net host.

Convert a Standalone to a Replica Set

This tutorial describes the process for converting a standalone mongod instance into a three-member replica set. Use standalone instances for testing and development, but always use replica sets in production. To install a standalone instance, see the installation tutorials.

To deploy a replica set without using a pre-existing mongod instance, see Deploy a Replica Set.

Procedure

Shut down the standalone mongod instance.

Restart the instance. Use the --replSet option to specify the name of the new replica set.

For example, the following command starts a standalone instance as a member of a new replica set named rs0. The command uses the standalone’s existing database path of /srv/mongodb/db0:

mongod --port 27017 --dbpath /srv/mongodb/db0 --replSet rs0

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

For more information on configuration options, see Configuration File Options and the mongod manual page.

Connect to the mongod instance.

Use rs.initiate() to initiate the new replica set:

rs.initiate()

The replica set is now operational.

To view the replica set configuration, use rs.conf(). To check the status of the replica set, use rs.status().

Expand the Replica Set

Add additional replica set members by doing the following:

On two distinct systems, start two new standalone mongod instances. For information on starting a standalone instance, see the installation tutorial specific to your environment.

On your connection to the original mongod instance (the former standalone instance), issue a command in the following form for each new instance to add to the replica set:

rs.add("<hostname><:port>")

Replace <hostname> and <port> with the resolvable hostname and port of the mongod instance to add to the set. For more information on adding a host to a replica set, see Add Members to a Replica Set.

Sharding Considerations

If the new replica set is part of a sharded cluster, change the shard host information in the config database by doing the following:

Connect to one of the sharded cluster’s mongos instances and issue a command in the following form:

db.getSiblingDB("config").shards.save( {_id: "<name>", host: "<replica-set>/<member,><member,><...>" } )

Replace <name> with the name of the shard. Replace <replica-set> with the name of the replica set. Replace <member,><member,><> with the list of the members of the replica set.

Restart all mongos instances. If possible, restart all components of the replica sets (i.e., all mongos and all shard mongod instances).

Add Members to a Replica Set

Overview

This tutorial explains how to add an additional member to an existing replica set. For background on replication deployment patterns, see the Replica Set Deployment Architectures document.

Maximum Voting Members

A replica set can have a maximum of seven voting members. To add a member to a replica set that already has seven votes, you must either add the member as a non-voting member or remove a vote from an existing member.

Control Scripts

In production deployments you can configure a control script to manage member processes.

Existing Members

You can use these procedures to add new members to an existing set. You can also use the same procedure to “re-add” a removed member. If the removed member’s data is still relatively recent, it can recover and catch up easily.

Data Files

If you have a backup or snapshot of an existing member, you can move the data files (e.g. the dbPath directory) to a new system and use them to quickly initiate a new member. The files must be:

A valid copy of the data files from a member of the same replica set. See Backup and Restore with Filesystem Snapshots document for more information.

Important

Always use filesystem snapshots to create a copy of a member of the existing replica set. Do not use mongodump and mongorestore to seed a new replica set member.

More recent than the oldest operation in the primary’s oplog. The new member must be able to become current by applying operations from the primary’s oplog.

Requirements

An active replica set.

A new MongoDB system capable of supporting your data set, accessible by the active replica set through the network.

Otherwise, use the MongoDB installation tutorial and the Deploy a Replica Set tutorials.

Procedures

Prepare the Data Directory

Before adding a new member to an existing replica set, prepare the new member’s data directory using one of the following strategies:

Make sure the new member’s data directory does not contain data. The new member will copy the data from an existing member.

If the new member is in a recovering state, it must exit and become a secondary before MongoDB can copy all data as part of the replication process. This process takes time but does not require administrator intervention.

Manually copy the data directory from an existing member. The new member becomes a secondary member and will catch up to the current state of the replica set. Copying the data over may shorten the amount of time for the new member to become current.

Ensure that you can copy the data directory to the new member and begin replication within the window allowed by the oplog. Otherwise, the new instance will have to perform an initial sync, which completely resynchronizes the data, as described in Resync a Member of a Replica Set.

Use rs.printReplicationInfo() to check the current state of replica set members with regards to the oplog.

For background on replication deployment patterns, see the Replica Set Deployment Architectures document.

Add a Member to an Existing Replica Set

Start the new mongod instance. Specify the data directory and the replica set name. The following example specifies the /srv/mongodb/db0 data directory and the rs0 replica set:

mongod --dbpath /srv/mongodb/db0 --replSet rs0

Take note of the host name and port information for the new mongod instance.

For more information on configuration options, see the mongod manual page.

Optional

You can specify the data directory and replica set in the mongo.conf configuration file, and start the mongod with the following command:

mongod --config /etc/mongodb.conf

Connect to the replica set’s primary.

You can only add members while connected to the primary. If you do not know which member is the primary, log into any member of the replica set and issue the db.isMaster() command.

Use rs.add() to add the new member to the replica set. For example, to add a member at host mongodb3.example.net, issue the following command:

rs.add("mongodb3.example.net")

You can include the port number, depending on your setup:

rs.add("mongodb3.example.net:27017")

Verify that the member is now part of the replica set. Call the rs.conf() method, which displays the replica set configuration:

rs.conf()

To view replica set status, issue the rs.status() method. For a description of the status fields, see replSetGetStatus.

Configure and Add a Member

You can add a member to a replica set by passing to the rs.add() method a members document. The document must be in the form of a local.system.replset.members document. These documents define a replica set member in the same form as the replica set configuration document.

Important

Specify a value for the _id field of the members document. MongoDB does not automatically populate the _id field in this case. Finally, the members document must declare the host value. All other fields are optional.

Example

To add a member with the following configuration:

an _id of 1.

a hostname and port number of mongodb3.example.net:27017.

a priority value within the replica set of 0.

a configuration as hidden,

Issue the following:

rs.add({_id: 1, host: "mongodb3.example.net:27017", priority: 0, hidden: true})

Remove Members from Replica Set

To remove a member of a replica set use either of the following procedures.

Remove a Member Using rs.remove()

Shut down the mongod instance for the member you wish to remove. To shut down the instance, connect using the mongo shell and the db.shutdownServer() method.

Connect to the replica set’s current primary. To determine the current primary, use db.isMaster() while connected to any member of the replica set.

Use rs.remove() in either of the following forms to remove the member:

rs.remove("mongod3.example.net:27017")
rs.remove("mongod3.example.net")

MongoDB disconnects the shell briefly as the replica set elects a new primary. The shell then automatically reconnects. The shell displays a DBClientCursor::init call() failed error even though the command succeeds.

Remove a Member Using rs.reconfig()

To remove a member you can manually edit the replica set configuration document, as described here.

Shut down the mongod instance for the member you wish to remove. To shut down the instance, connect using the mongo shell and the db.shutdownServer() method.

Connect to the replica set’s current primary. To determine the current primary, use db.isMaster() while connected to any member of the replica set.

Issue the rs.conf() method to view the current configuration document and determine the position in the members array of the member to remove:

Example

mongod_C.example.net is in position 2 of the following configuration file:

{
    "_id" : "rs",
    "version" : 7,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongod_A.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongod_B.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "mongod_C.example.net:27017"
        }
    ]
}

Assign the current configuration document to the variable cfg:

cfg = rs.conf()

Modify the cfg object to remove the member.

Example

To remove mongod_C.example.net:27017 use the following JavaScript operation:

cfg.members.splice(2,1)

Overwrite the replica set configuration document with the new configuration by issuing the following:

rs.reconfig(cfg)

As a result of rs.reconfig() the shell will disconnect while the replica set renegotiates which member is primary. The shell displays a DBClientCursor::init call() failed error even though the command succeeds, and will automatically reconnected.

To confirm the new configuration, issue rs.conf().

For the example above the output would be:

{
    "_id" : "rs",
    "version" : 8,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongod_A.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongod_B.example.net:27017"
        }
    ]
}

Replace a Replica Set Member

If you need to change the hostname of a replica set member without changing the configuration of that member or the set, you can use the operation outlined in this tutorial. For example if you must re-provision systems or rename hosts, you can use this pattern to minimize the scope of that change.

Operation

To change the hostname for a replica set member modify the host field. The value of _id field will not change when you reconfigure the set.

See Replica Set Configuration and rs.reconfig() for more information.

Note

Any replica set configuration change can trigger the current primary to step down, which forces an election. During the election, the current shell session and clients connected to this replica set disconnect, which produces an error even when the operation succeeds.

Example

To change the hostname to mongo2.example.net for the replica set member configured at members[0], issue the following sequence of commands:

cfg = rs.conf()
cfg.members[0].host = "mongo2.example.net"
rs.reconfig(cfg)

Member Configuration Tutorials

The following tutorials provide information in configuring replica set members to support specific operations, such as to provide dedicated backups, to support reporting, or to act as a cold standby.

Adjust Priority for Replica Set Member

Change the precedence given to a replica set members in an election for primary.

Prevent Secondary from Becoming Primary

Make a secondary member ineligible for election as primary.

Configure a Hidden Replica Set Member

Configure a secondary member to be invisible to applications in order to support significantly different usage, such as a dedicated backups.

Configure a Delayed Replica Set Member

Configure a secondary member to keep a delayed copy of the data set in order to provide a rolling backup.

Configure Non-Voting Replica Set Member

Create a secondary member that keeps a copy of the data set but does not vote in an election.

Convert a Secondary to an Arbiter

Convert a secondary to an arbiter.

Adjust Priority for Replica Set Member

Prevent Secondary from Becoming Primary

Configure a Hidden Replica Set Member

Configure a Delayed Replica Set Member

Configure Non-Voting Replica Set Member

Convert a Secondary to an Arbiter

Adjust Priority for Replica Set Member

Overview

The priority settings of replica set members affect the outcomes of elections for primary. Use this setting to ensure that some members are more likely to become primary and that others can never become primary.

The value of the member’s priority setting determines the member’s priority in elections. The higher the number, the higher the priority.

Considerations

To modify priorities, you update the members array in the replica configuration object. The array index begins with 0. Do not confuse this index value with the value of the replica set member’s _id field in the array.

The value of priority can be any floating point (i.e. decimal) number between 0 and 1000. The default value for the priority field is 1.

To block a member from seeking election as primary, assign it a priority of 0. Hidden members, delayed members, and arbiters all have priority set to 0.

Adjust priority during a scheduled maintenance window. Reconfiguring priority can force the current primary to step down, leading to an election. Before an election the primary closes all open client connections.

Procedure

1

Copy the replica set configuration to a variable.

In the mongo shell, use rs.conf() to retrieve the replica set configuration and assign it to a variable. For example:

cfg = rs.conf()

Step 1: Copy the replica set configuration to a variable.

In the mongo shell, use rs.conf() to retrieve the replica set configuration and assign it to a variable. For example:

cfg = rs.conf()

2

Change each member’s priority value.

Change each member’s priority value, as configured in the members array.

cfg.members[0].priority = 0.5
cfg.members[1].priority = 2
cfg.members[2].priority = 2

This sequence of operations modifies the value of cfg to set the priority for the first three members defined in the members array.

Step 2: Change each member’s priority value.

Change each member’s priority value, as configured in the members array.

cfg.members[0].priority = 0.5
cfg.members[1].priority = 2
cfg.members[2].priority = 2

This sequence of operations modifies the value of cfg to set the priority for the first three members defined in the members array.

3

Assign the replica set the new configuration.

Use rs.reconfig() to apply the new configuration.

rs.reconfig(cfg)

This operation updates the configuration of the replica set using the configuration defined by the value of cfg.

Step 3: Assign the replica set the new configuration.

Use rs.reconfig() to apply the new configuration.

rs.reconfig(cfg)

This operation updates the configuration of the replica set using the configuration defined by the value of cfg.

Prevent Secondary from Becoming Primary

Overview

In a replica set, by default all secondary members are eligible to become primary through the election process. You can use the priority to affect the outcome of these elections by making some members more likely to become primary and other members less likely or unable to become primary.

Secondaries that cannot become primary are also unable to trigger elections. In all other respects these secondaries are identical to other secondaries.

To prevent a secondary member from ever becoming a primary in a failover, assign the secondary a priority of 0, as described here. For a detailed description of secondary-only members and their purposes, see Priority 0 Replica Set Members.

Considerations

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the _id field in each document in the members array.

Note

MongoDB does not permit the current primary to have a priority of 0. To prevent the current primary from again becoming a primary, you must first step down the current primary using rs.stepDown().

Procedure

This tutorial uses a sample replica set with 5 members.

Warning

The rs.reconfig() shell method can force the current primary to step down, which causes an election. When the primary steps down, the mongod closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

To successfully reconfigure a replica set, a majority of the members must be accessible. If your replica set has an even number of members, add an arbiter to ensure that members can quickly obtain a majority of votes in an election for primary.

1

Retrieve the current replica set configuration.

The rs.conf() method returns a replica set configuration document that contains the current configuration for a replica set.

In a mongo shell connected to a primary, run the rs.conf() method and assign the result to a variable:

cfg = rs.conf()

The returned document contains a members field which contains an array of member configuration documents, one document for each member of the replica set.

Step 1: Retrieve the current replica set configuration.

The rs.conf() method returns a replica set configuration document that contains the current configuration for a replica set.

In a mongo shell connected to a primary, run the rs.conf() method and assign the result to a variable:

cfg = rs.conf()

The returned document contains a members field which contains an array of member configuration documents, one document for each member of the replica set.

2

Assign priority value of 0.

To prevent a secondary member from becoming a primary, update the secondary member’s priority to 0.

To assign a priority value to a member of the replica set, access the member configuration document using the array index. In this tutorial, the secondary member to change corresponds to the configuration document found at position 2 of the members array.

cfg.members[2].priority = 0

The configuration change does not take effect until you reconfigure the replica set.

Step 2: Assign priority value of 0.

To prevent a secondary member from becoming a primary, update the secondary member’s priority to 0.

To assign a priority value to a member of the replica set, access the member configuration document using the array index. In this tutorial, the secondary member to change corresponds to the configuration document found at position 2 of the members array.

cfg.members[2].priority = 0

The configuration change does not take effect until you reconfigure the replica set.

3

Reconfigure the replica set.

Use rs.reconfig() method to reconfigure the replica set with the updated replica set configuration document.

Pass the cfg variable to the rs.reconfig() method:

rs.reconfig(cfg)

Step 3: Reconfigure the replica set.

Use rs.reconfig() method to reconfigure the replica set with the updated replica set configuration document.

Pass the cfg variable to the rs.reconfig() method:

rs.reconfig(cfg)

Related Documents

priority

Adjust Priority for Replica Set Member

Replica Set Reconfiguration

Replica Set Elections

Configure a Hidden Replica Set Member

Hidden members are part of a replica set but cannot become primary and are invisible to client applications. Hidden members do vote in elections. For a more information on hidden members and their uses, see Hidden Replica Set Members.

Considerations

The most common use of hidden nodes is to support delayed members. If you only need to prevent a member from becoming primary, configure a priority 0 member.

If the chainingAllowed setting allows secondary members to sync from other secondaries, MongoDB by default prefers non-hidden members over hidden members when selecting a sync target. MongoDB will only choose hidden members as a last resort. If you want a secondary to sync from a hidden member, use the replSetSyncFrom database command to override the default sync target. See the documentation for replSetSyncFrom before using the command.

See also

Manage Chained Replication

Changed in version 2.0: For sharded clusters running with replica sets before 2.0, if you reconfigured a member as hidden, you had to restart mongos to prevent queries from reaching the hidden member.

Examples

Member Configuration Document

To configure a secondary member as hidden, set its priority value to 0 and set its hidden value to true in its member configuration:

{
  "_id" : <num>
  "host" : <hostname:port>,
  "priority" : 0,
  "hidden" : true
}

Configuration Procedure

The following example hides the secondary member currently at the index 0 in the members array. To configure a hidden member, use the following sequence of operations in a mongo shell connected to the primary, specifying the member to configure by its array index in the members array:

cfg = rs.conf()
cfg.members[0].priority = 0
cfg.members[0].hidden = true
rs.reconfig(cfg)

After re-configuring the set, this secondary member has a priority of 0 so that it cannot become primary and is hidden. The other members in the set will not advertise the hidden member in the isMaster or db.isMaster() output.

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the _id field in each document in the members array.

Warning

The rs.reconfig() shell method can force the current primary to step down, which causes an election. When the primary steps down, the mongod closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

To successfully reconfigure a replica set, a majority of the members must be accessible. If your replica set has an even number of members, add an arbiter to ensure that members can quickly obtain a majority of votes in an election for primary.

Related Documents

Replica Set Reconfiguration

Replica Set Elections

Read Preference

Configure a Delayed Replica Set Member

To configure a delayed secondary member, set its priority value to 0, its hidden value to true, and its slaveDelay value to the number of seconds to delay.

Important

The length of the secondary slaveDelay must fit within the window of the oplog. If the oplog is shorter than the slaveDelay window, the delayed member cannot successfully replicate operations.

When you configure a delayed member, the delay applies both to replication and to the member’s oplog. For details on delayed members and their uses, see Delayed Replica Set Members.

Example

The following example sets a 1-hour delay on a secondary member currently at the index 0 in the members array. To set the delay, issue the following sequence of operations in a mongo shell connected to the primary:

cfg = rs.conf()
cfg.members[0].priority = 0
cfg.members[0].hidden = true
cfg.members[0].slaveDelay = 3600
rs.reconfig(cfg)

After the replica set reconfigures, the delayed secondary member cannot become primary and is hidden from applications. The slaveDelay value delays both replication and the member’s oplog by 3600 seconds (1 hour).

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the _id field in each document in the members array.

Warning

The rs.reconfig() shell method can force the current primary to step down, which causes an election. When the primary steps down, the mongod closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

To successfully reconfigure a replica set, a majority of the members must be accessible. If your replica set has an even number of members, add an arbiter to ensure that members can quickly obtain a majority of votes in an election for primary.

Related Documents

slaveDelay

Replica Set Reconfiguration

Oplog Size

Change the Size of the Oplog tutorial

Replica Set Elections

Configure Non-Voting Replica Set Member

Non-voting members allow you to add additional members for read distribution beyond the maximum seven voting members. To configure a member as non-voting, set its votes value to 0.

Example

To disable the ability to vote in elections for the fourth, fifth, and sixth replica set members, use the following command sequence in the mongo shell connected to the primary. You identify each replica set member by its array index in the members array:

cfg = rs.conf()
cfg.members[3].votes = 0
cfg.members[4].votes = 0
cfg.members[5].votes = 0
rs.reconfig(cfg)

This sequence gives 0 votes to the fourth, fifth, and sixth members of the set according to the order of the members array in the output of rs.conf(). This setting allows the set to elect these members as primary but does not allow them to vote in elections. Place voting members so that your designated primary or primaries can reach a majority of votes in the event of a network partition.

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the _id field in each document in the members array.

Warning

The rs.reconfig() shell method can force the current primary to step down, which causes an election. When the primary steps down, the mongod closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

To successfully reconfigure a replica set, a majority of the members must be accessible. If your replica set has an even number of members, add an arbiter to ensure that members can quickly obtain a majority of votes in an election for primary.

In general and when possible, all members should have only 1 vote. This prevents intermittent ties, deadlocks, or the wrong members from becoming primary. Use priority to control which members are more likely to become primary.

Related Documents

votes

Replica Set Reconfiguration

Replica Set Elections

Convert a Secondary to an Arbiter

If you have a secondary in a replica set that no longer needs to hold data but that needs to remain in the set to ensure that the set can elect a primary, you may convert the secondary to an arbiter using either procedure in this tutorial. Both procedures are operationally equivalent:

You may operate the arbiter on the same port as the former secondary. In this procedure, you must shut down the secondary and remove its data before restarting and reconfiguring it as an arbiter.

For this procedure, see Convert Secondary to Arbiter and Reuse the Port Number.

Run the arbiter on a new port. In this procedure, you can reconfigure the server as an arbiter before shutting down the instance running as a secondary.

For this procedure, see Convert Secondary to Arbiter Running on a New Port Number.

Convert Secondary to Arbiter and Reuse the Port Number

If your application is connecting directly to the secondary, modify the application so that MongoDB queries don’t reach the secondary.

Shut down the secondary.

Remove the secondary from the replica set by calling the rs.remove() method. Perform this operation while connected to the current primary in the mongo shell:

rs.remove("<hostname><:port>")

Verify that the replica set no longer includes the secondary by calling the rs.conf() method in the mongo shell:

rs.conf()

Move the secondary’s data directory to an archive folder. For example:

mv /data/db /data/db-old

Optional

You may remove the data instead.

Create a new, empty data directory to point to when restarting the mongod instance. You can reuse the previous name. For example:

mkdir /data/db

Restart the mongod instance for the secondary, specifying the port number, the empty data directory, and the replica set. You can use the same port number you used before. Issue a command similar to the following:

mongod --port 27021 --dbpath /data/db --replSet rs

In the mongo shell convert the secondary to an arbiter using the rs.addArb() method:

rs.addArb("<hostname><:port>")

Verify the arbiter belongs to the replica set by calling the rs.conf() method in the mongo shell.

rs.conf()

The arbiter member should include the following:

"arbiterOnly" : true

Convert Secondary to Arbiter Running on a New Port Number

If your application is connecting directly to the secondary or has a connection string referencing the secondary, modify the application so that MongoDB queries don’t reach the secondary.

Create a new, empty data directory to be used with the new port number. For example:

mkdir /data/db-temp

Start a new mongod instance on the new port number, specifying the new data directory and the existing replica set. Issue a command similar to the following:

mongod --port 27021 --dbpath /data/db-temp --replSet rs

In the mongo shell connected to the current primary, convert the new mongod instance to an arbiter using the rs.addArb() method:

rs.addArb("<hostname><:port>")

Verify the arbiter has been added to the replica set by calling the rs.conf() method in the mongo shell.

rs.conf()

The arbiter member should include the following:

"arbiterOnly" : true

Shut down the secondary.

Remove the secondary from the replica set by calling the rs.remove() method in the mongo shell:

rs.remove("<hostname><:port>")

Verify that the replica set no longer includes the old secondary by calling the rs.conf() method in the mongo shell:

rs.conf()

Move the secondary’s data directory to an archive folder. For example:

mv /data/db /data/db-old

Optional

You may remove the data instead.

Replica Set Maintenance Tutorials

The following tutorials provide information in maintaining existing replica sets.

Change the Size of the Oplog

Increase the size of the oplog which logs operations. In most cases, the default oplog size is sufficient.

Perform Maintenance on Replica Set Members

Perform maintenance on a member of a replica set while minimizing downtime.

Force a Member to Become Primary

Force a replica set member to become primary.

Resync a Member of a Replica Set

Sync the data on a member. Either perform initial sync on a new member or resync the data on an existing member that has fallen too far behind to catch up by way of normal replication.

Configure Replica Set Tag Sets

Assign tags to replica set members for use in targeting read and write operations to specific members.

Reconfigure a Replica Set with Unavailable Members

Reconfigure a replica set when a majority of replica set members are down or unreachable.

Manage Chained Replication

Disable or enable chained replication. Chained replication occurs when a secondary replicates from another secondary instead of the primary.

Change Hostnames in a Replica Set

Update the replica set configuration to reflect changes in members’ hostnames.

Configure a Secondary’s Sync Target

Specify the member that a secondary member synchronizes from.

Change the Size of the Oplog

Perform Maintenance on Replica Set Members

Force a Member to Become Primary

Resync a Member of a Replica Set

Configure Replica Set Tag Sets

Reconfigure a Replica Set with Unavailable Members

Manage Chained Replication

Change Hostnames in a Replica Set

Configure a Secondary’s Sync Target

Change the Size of the Oplog

The oplog exists internally as a capped collection, so you cannot modify its size in the course of normal operations. In most cases the default oplog size is an acceptable size; however, in some situations you may need a larger or smaller oplog. For example, you might need to change the oplog size if your applications perform large numbers of multi-updates or deletes in short periods of time.

This tutorial describes how to resize the oplog. For a detailed explanation of oplog sizing, see Oplog Size. For details how oplog size affects delayed members and affects replication lag, see Delayed Replica Set Members.

Overview

To change the size of the oplog, you must perform maintenance on each member of the replica set in turn. The procedure requires: stopping the mongod instance and starting as a standalone instance, modifying the oplog size, and restarting the member.

Important

Always start rolling replica set maintenance with the secondaries, and finish with the maintenance on primary member.

Procedure

Restart the member in standalone mode.

Tip

Always use rs.stepDown() to force the primary to become a secondary, before stopping the server. This facilitates a more efficient election process.

Recreate the oplog with the new size and with an old oplog entry as a seed.

Restart the mongod instance as a member of the replica set.

Restart a Secondary in Standalone Mode on a Different Port

Shut down the mongod instance for one of the non-primary members of your replica set. For example, to shut down, use the db.shutdownServer() method:

db.shutdownServer()

Restart this mongod as a standalone instance running on a different port and without the --replSet parameter. Use a command similar to the following:

mongod --port 37017 --dbpath /srv/mongodb

Create a Backup of the Oplog (Optional)

Optionally, backup the existing oplog on the standalone instance, as in the following example:

mongodump --db local --collection 'oplog.rs' --port 37017

Recreate the Oplog with a New Size and a Seed Entry

Save the last entry from the oplog. For example, connect to the instance using the mongo shell, and enter the following command to switch to the local database:

use local

In mongo shell scripts you can use the following operation to set the db object:

db = db.getSiblingDB('local')

Ensure that the temp temporary collection is empty by dropping the collection:

db.temp.drop()

Use the db.collection.save() method and a sort on reverse natural order to find the last entry and save it to a temporary collection:

db.temp.save( db.oplog.rs.find( { }, { ts: 1, h: 1 } ).sort( {$natural : -1} ).limit(1).next() )

To see this oplog entry, use the following operation:

db.temp.find()

Remove the Existing Oplog Collection

Drop the old oplog.rs collection in the local database. Use the following command:

db = db.getSiblingDB('local')
db.oplog.rs.drop()

This returns true in the shell.

Create a New Oplog

Use the create command to create a new oplog of a different size. Specify the size argument in bytes. A value of 2 * 1024 * 1024 * 1024 will create a new oplog that’s 2 gigabytes:

db.runCommand( { create: "oplog.rs", capped: true, size: (2 * 1024 * 1024 * 1024) } )

Upon success, this command returns the following status:

{ "ok" : 1 }

Insert the Last Entry of the Old Oplog into the New Oplog

Insert the previously saved last entry from the old oplog into the new oplog. For example:

db.oplog.rs.save( db.temp.findOne() )

To confirm the entry is in the new oplog, use the following operation:

db.oplog.rs.find()

Restart the Member

Restart the mongod as a member of the replica set on its usual port. For example:

db.shutdownServer()
mongod --replSet rs0 --dbpath /srv/mongodb

The replica set member will recover and “catch up” before it is eligible for election to primary.

Repeat Process for all Members that may become Primary

Repeat this procedure for all members you want to change the size of the oplog. Repeat the procedure for the primary as part of the following step.

Change the Size of the Oplog on the Primary

To finish the rolling maintenance operation, step down the primary with the rs.stepDown() method and repeat the oplog resizing procedure above.

Perform Maintenance on Replica Set Members

Overview

Replica sets allow a MongoDB deployment to remain available during the majority of a maintenance window.

This document outlines the basic procedure for performing maintenance on each of the members of a replica set. Furthermore, this particular sequence strives to minimize the amount of time that the primary is unavailable and controlling the impact on the entire deployment.

Use these steps as the basis for common replica set operations, particularly for procedures such as upgrading to the latest version of MongoDB and changing the size of the oplog.

Procedure

For each member of a replica set, starting with a secondary member, perform the following sequence of events, ending with the primary:

Restart the mongod instance as a standalone.

Perform the task on the standalone instance.

Restart the mongod instance as a member of the replica set.

1

Stop a secondary.

In the mongo shell, shut down the mongod instance:

db.shutdownServer()

Step 1: Stop a secondary.

In the mongo shell, shut down the mongod instance:

db.shutdownServer()

2

Restart the secondary as a standalone on a different port.

At the operating system shell prompt, restart mongod as a standalone instance running on a different port and without the --replSet parameter:

mongod --port 37017 --dbpath /srv/mongodb

Always start mongod with the same user, even when restarting a replica set member as a standalone instance.

Step 2: Restart the secondary as a standalone on a different port.

At the operating system shell prompt, restart mongod as a standalone instance running on a different port and without the --replSet parameter:

mongod --port 37017 --dbpath /srv/mongodb

Always start mongod with the same user, even when restarting a replica set member as a standalone instance.

3

Perform maintenance operations on the secondary.

While the member is a standalone, use the mongo shell to perform maintenance:

mongo --port 37017

Step 3: Perform maintenance operations on the secondary.

While the member is a standalone, use the mongo shell to perform maintenance:

mongo --port 37017

4

Restart mongod as a member of the replica set.

After performing all maintenance tasks, use the following procedure to restart the mongod as a member of the replica set on its usual port.

From the mongo shell, shut down the standalone server after completing the maintenance:

db.shutdownServer()

Restart the mongod instance as a member of the replica set using its normal command-line arguments or configuration file.

The secondary takes time to catch up to the primary. From the mongo shell, use the following command to verify that the member has caught up from the RECOVERING state to the SECONDARY state.

rs.status()

Step 4: Restart mongod as a member of the replica set.

After performing all maintenance tasks, use the following procedure to restart the mongod as a member of the replica set on its usual port.

From the mongo shell, shut down the standalone server after completing the maintenance:

db.shutdownServer()

Restart the mongod instance as a member of the replica set using its normal command-line arguments or configuration file.

The secondary takes time to catch up to the primary. From the mongo shell, use the following command to verify that the member has caught up from the RECOVERING state to the SECONDARY state.

rs.status()

5

Perform maintenance on the primary last.

To perform maintenance on the primary after completing maintenance tasks on all secondaries, use rs.stepDown() in the mongo shell to step down the primary and allow one of the secondaries to be elected the new primary. Specify a 300 second waiting period to prevent the member from being elected primary again for five minutes:

rs.stepDown(300)

After the primary steps down, the replica set will elect a new primary. See Replica Set Elections for more information about replica set elections.

Step 5: Perform maintenance on the primary last.

To perform maintenance on the primary after completing maintenance tasks on all secondaries, use rs.stepDown() in the mongo shell to step down the primary and allow one of the secondaries to be elected the new primary. Specify a 300 second waiting period to prevent the member from being elected primary again for five minutes:

rs.stepDown(300)

After the primary steps down, the replica set will elect a new primary. See Replica Set Elections for more information about replica set elections.

Force a Member to Become Primary

Overview

You can force a replica set member to become primary by giving it a higher priority value than any other member in the set.

Optionally, you also can force a member never to become primary by setting its priority value to 0, which means the member can never seek election as primary. For more information, see Priority 0 Replica Set Members.

Consideration

A majority of the configured members of a replica set must be available for a set to reconfigure a set or elect a primary. See Replica Set Elections for more information.

Procedures

Force a Member to be Primary by Setting its Priority High

Changed in version 2.0.

For more information on priorities, see priority.

This procedure assumes your current primary is m1.example.net and that you’d like to instead make m3.example.net primary. The procedure also assumes you have a three-member replica set with the configuration below. For more information on configurations, see Replica Set Configuration Use.

This procedure assumes this configuration:

{
    "_id" : "rs",
    "version" : 7,
    "members" : [
        {
            "_id" : 0,
            "host" : "m1.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "m2.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "m3.example.net:27017"
        }
    ]
}

In the mongo shell, use the following sequence of operations to make m3.example.net the primary:

cfg = rs.conf()
cfg.members[0].priority = 0.5
cfg.members[1].priority = 0.5
cfg.members[2].priority = 1
rs.reconfig(cfg)

This sets m3.example.net to have a higher local.system.replset.members[n].priority value than the other mongod instances.

The following sequence of events occur:

m3.example.net and m2.example.net sync with m1.example.net (typically within 10 seconds).

m1.example.net sees that it no longer has highest priority and, in most cases, steps down. m1.example.net does not step down if m3.example.net‘s sync is far behind. In that case, m1.example.net waits until m3.example.net is within 10 seconds of its optime and then steps down. This minimizes the amount of time with no primary following failover.

The step down forces on election in which m3.example.net becomes primary based on its priority setting.

Optionally, if m3.example.net is more than 10 seconds behind m1.example.net‘s optime, and if you don’t need to have a primary designated within 10 seconds, you can force m1.example.net to step down by running:

db.adminCommand({replSetStepDown: 86400, force: 1})

This prevents m1.example.net from being primary for 86,400 seconds (24 hours), even if there is no other member that can become primary. When m3.example.net catches up with m1.example.net it will become primary.

If you later want to make m1.example.net primary again while it waits for m3.example.net to catch up, issue the following command to make m1.example.net seek election again:

rs.freeze()

The rs.freeze() provides a wrapper around the replSetFreeze database command.

Force a Member to be Primary Using Database Commands

Changed in version 1.8.

Consider a replica set with the following members:

mdb0.example.net - the current primary.

mdb1.example.net - a secondary.

mdb2.example.net - a secondary .

To force a member to become primary use the following procedure:

In a mongo shell, run rs.status() to ensure your replica set is running as expected.

In a mongo shell connected to the mongod instance running on mdb2.example.net, freeze mdb2.example.net so that it does not attempt to become primary for 120 seconds.

rs.freeze(120)

In a mongo shell connected the mongod running on mdb0.example.net, step down this instance that the mongod is not eligible to become primary for 120 seconds:

rs.stepDown(120)

mdb1.example.net becomes primary.

Note

During the transition, there is a short window where the set does not have a primary.

For more information, consider the rs.freeze() and rs.stepDown() methods that wrap the replSetFreeze and replSetStepDown commands.

Resync a Member of a Replica Set

A replica set member becomes “stale” when its replication process falls so far behind that the primary overwrites oplog entries the member has not yet replicated. The member cannot catch up and becomes “stale.” When this occurs, you must completely resynchronize the member by removing its data and performing an initial sync.

This tutorial addressed both resyncing a stale member and to creating a new member using seed data from another member. When syncing a member, choose a time when the system has the bandwidth to move a large amount of data. Schedule the synchronization during a time of low usage or during a maintenance window.

MongoDB provides two options for performing an initial sync:

Restart the mongod with an empty data directory and let MongoDB’s normal initial syncing feature restore the data. This is the more simple option but may take longer to replace the data.

See Procedures.

Restart the machine with a copy of a recent data directory from another member in the replica set. This procedure can replace the data more quickly but requires more manual steps.

See Sync by Copying Data Files from Another Member.

Procedures

Automatically Sync a Member

Warning

During initial sync, mongod will remove the content of the dbPath.

This procedure relies on MongoDB’s regular process for initial sync. This will store the current data on the member. For an overview of MongoDB initial sync process, see the Replication Processes section.

If the instance has no data, you can simply follow the Add Members to a Replica Set or Replace a Replica Set Member procedure to add a new member to a replica set.

You can also force a mongod that is already a member of the set to to perform an initial sync by restarting the instance without the content of the dbPath as follows:

Stop the member’s mongod instance. To ensure a clean shutdown, use the db.shutdownServer() method from the mongo shell or on Linux systems, the mongod --shutdown option.

Delete all data and sub-directories from the member’s data directory. By removing the data dbPath, MongoDB will perform a complete resync. Consider making a backup first.

At this point, the mongod will perform an initial sync. The length of the initial sync process depends on the size of the database and network connection between members of the replica set.

Initial sync operations can impact the other members of the set and create additional traffic to the primary and can only occur if another member of the set is accessible and up to date.

Sync by Copying Data Files from Another Member

This approach “seeds” a new or stale member using the data files from an existing member of the replica set. The data files must be sufficiently recent to allow the new member to catch up with the oplog. Otherwise the member would need to perform an initial sync.

Copy the Data Files

You can capture the data files as either a snapshot or a direct copy. However, in most cases you cannot copy data files from a running mongod instance to another because the data files will change during the file copy operation.

Important

If copying data files, you must copy the content of the local database.

You cannot use a mongodump backup for the data files, only a snapshot backup. For approaches to capturing a consistent snapshot of a running mongod instance, see the MongoDB Backup Methods documentation.

Sync the Member

After you have copied the data files from the “seed” source, start the mongod instance and allow it to apply all operations from the oplog until it reflects the current state of the replica set.

Configure Replica Set Tag Sets

Tag sets let you customize write concern and read preferences for a replica set. MongoDB stores tag sets in the replica set configuration object, which is the document returned by rs.conf(), in the members[n].tags embedded document.

This section introduces the configuration of tag sets. For an overview on tag sets and their use, see Replica Set Write Concern and Tag Sets.

Differences Between Read Preferences and Write Concerns

Custom read preferences and write concerns evaluate tags sets in different ways:

Read preferences consider the value of a tag when selecting a member to read from.

Write concerns do not use the value of a tag to select a member except to consider whether or not the value is unique.

For example, a tag set for a read operation may resemble the following document:

{ "disk": "ssd", "use": "reporting" }

To fulfill such a read operation, a member would need to have both of these tags. Any of the following tag sets would satisfy this requirement:

{ "disk": "ssd", "use": "reporting" }
{ "disk": "ssd", "use": "reporting", "rack": "a" }
{ "disk": "ssd", "use": "reporting", "rack": "d" }
{ "disk": "ssd", "use": "reporting", "mem": "r"}

The following tag sets would not be able to fulfill this query:

{ "disk": "ssd" }
{ "use": "reporting" }
{ "disk": "ssd", "use": "production" }
{ "disk": "ssd", "use": "production", "rack": "k" }
{ "disk": "spinning", "use": "reporting", "mem": "32" }

Add Tag Sets to a Replica Set

Given the following replica set configuration:

{
    "_id" : "rs0",
    "version" : 1,
    "members" : [
             {
                     "_id" : 0,
                     "host" : "mongodb0.example.net:27017"
             },
             {
                     "_id" : 1,
                     "host" : "mongodb1.example.net:27017"
             },
             {
                     "_id" : 2,
                     "host" : "mongodb2.example.net:27017"
             }
     ]
}

You could add tag sets to the members of this replica set with the following command sequence in the mongo shell:

conf = rs.conf()
conf.members[0].tags = { "dc": "east", "use": "production"  }
conf.members[1].tags = { "dc": "east", "use": "reporting"  }
conf.members[2].tags = { "use": "production"  }
rs.reconfig(conf)

After this operation the output of rs.conf() would resemble the following:

{
    "_id" : "rs0",
    "version" : 2,
    "members" : [
             {
                     "_id" : 0,
                     "host" : "mongodb0.example.net:27017",
                     "tags" : {
                             "dc": "east",
                             "use": "production"
                     }
             },
             {
                     "_id" : 1,
                     "host" : "mongodb1.example.net:27017",
                     "tags" : {
                             "dc": "east",
                             "use": "reporting"
                     }
             },
             {
                     "_id" : 2,
                     "host" : "mongodb2.example.net:27017",
                     "tags" : {
                             "use": "production"
                     }
             }
     ]
}

Important

In tag sets, all tag values must be strings.

Custom Multi-Datacenter Write Concerns

Given a five member replica set with members in two data centers:

a facility VA tagged dc.va

a facility GTO tagged dc.gto

Create a custom write concern to require confirmation from two data centers using replica set tags, using the following sequence of operations in the mongo shell:

Create a replica set configuration JavaScript object conf:

conf = rs.conf()

Add tags to the replica set members reflecting their locations:

conf.members[0].tags = { "dc.va": "rack1"}
conf.members[1].tags = { "dc.va": "rack2"}
conf.members[2].tags = { "dc.gto": "rack1"}
conf.members[3].tags = { "dc.gto": "rack2"}
conf.members[4].tags = { "dc.va": "rack1"}
rs.reconfig(conf)

Create a custom getLastErrorModes setting to ensure that the write operation will propagate to at least one member of each facility:

conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 1, "dc.gto": 1}}

Reconfigure the replica set using the modified conf configuration object:

rs.reconfig(conf)

To ensure that a write operation propagates to at least one member of the set in both data centers, use the MultipleDC write concern mode as follows:

db.users.insert( { id: "xyz", status: "A" }, { writeConcern: { w: "MultipleDC" } } )

Alternatively, if you want to ensure that each write operation propagates to at least 2 racks in each facility, reconfigure the replica set as follows in the mongo shell:

Create a replica set configuration object conf:

conf = rs.conf()

Redefine the getLastErrorModes value to require two different values of both dc.va and dc.gto:

conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 2, "dc.gto": 2}}

Reconfigure the replica set using the modified conf configuration object:

rs.reconfig(conf)

Now, the following write operation will only return after the write operation propagates to at least two different racks in the each facility:

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations. Previous versions used the getLastError command to specify the write concerns.

db.users.insert( { id: "xyz", status: "A" }, { writeConcern: { w: "MultipleDC" } } )

Configure Tag Sets for Functional Segregation of Read and Write Operations

Given a replica set with tag sets that reflect:

data center facility,

physical rack location of instance, and

storage system (i.e. disk) type.

Where each member of the set has a tag set that resembles one of the following: [1]

{"dc.va": "rack1", disk:"ssd", ssd: "installed" }
{"dc.va": "rack2", disk:"raid"}
{"dc.gto": "rack1", disk:"ssd", ssd: "installed" }
{"dc.gto": "rack2", disk:"raid"}
{"dc.va": "rack1", disk:"ssd", ssd: "installed" }

To target a read operation to a member of the replica set with a disk type of ssd, you could use the following tag set:

{ disk: "ssd" }

However, to create comparable write concern modes, you would specify a different set of getLastErrorModes configuration. Consider the following sequence of operations in the mongo shell:

Create a replica set configuration object conf:

conf = rs.conf()

Redefine the getLastErrorModes value to configure two write concern modes:

conf.settings = {
                 "getLastErrorModes" : {
                         "ssd" : {
                                    "ssd" : 1
                         },
                         "MultipleDC" : {
                                 "dc.va" : 1,
                                "dc.gto" : 1
                         }
                 }
               }

Reconfigure the replica set using the modified conf configuration object:

rs.reconfig(conf)

Now you can specify the MultipleDC write concern mode, as in the following, to ensure that a write operation propagates to each data center.

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations. Previous versions used the getLastError command to specify the write concerns.

db.users.insert( { id: "xyz", status: "A" }, { writeConcern: { w: "MultipleDC" } } )

Additionally, you can specify the ssd write concern mode to ensure that a write operation propagates to at least one instance with an SSD.

[1]
Since read preferences and write concerns use the value of fields in tag sets differently, larger deployments may have some redundancy.

Reconfigure a Replica Set with Unavailable Members

To reconfigure a replica set when a majority of members are available, use the rs.reconfig() operation on the current primary, following the example in the Replica Set Reconfiguration Procedure.

This document provides the following options for re-configuring a replica set when only a minority of members are accessible:

Reconfigure by Forcing the Reconfiguration

Reconfigure by Replacing the Replica Set

You may need to use one of these procedures, for example, in a geographically distributed replica set, where no local group of members can reach a majority. See Replica Set Elections for more information on this situation.

Reconfigure by Forcing the Reconfiguration

Changed in version 2.0.

This procedure lets you recover while a majority of replica set members are down or unreachable. You connect to any surviving member and use the force option to the rs.reconfig() method.

The force option forces a new configuration onto the member. Use this procedure only to recover from catastrophic interruptions. Do not use force every time you reconfigure. Also, do not use the force option in any automatic scripts and do not use force when there is still a primary.

To force reconfiguration:

Back up a surviving member.

Connect to a surviving member and save the current configuration. Consider the following example commands for saving the configuration:

cfg = rs.conf()

printjson(cfg)

On the same member, remove the down and unreachable members of the replica set from the members array by setting the array equal to the surviving members alone. Consider the following example, which uses the cfg variable created in the previous step:

cfg.members = [cfg.members[0] , cfg.members[4] , cfg.members[7]]

On the same member, reconfigure the set by using the rs.reconfig() command with the force option set to true:

rs.reconfig(cfg, {force : true})

This operation forces the secondary to use the new configuration. The configuration is then propagated to all the surviving members listed in the members array. The replica set then elects a new primary.

Note

When you use force : true, the version number in the replica set configuration increases significantly, by tens or hundreds of thousands. This is normal and designed to prevent set version collisions if you accidentally force re-configurations on both sides of a network partition and then the network partitioning ends.

If the failure or partition was only temporary, shut down or decommission the removed members as soon as possible.

Reconfigure by Replacing the Replica Set

Use the following procedure only for versions of MongoDB prior to version 2.0. If you’re running MongoDB 2.0 or later, use the above procedure, Reconfigure by Forcing the Reconfiguration.

These procedures are for situations where a majority of the replica set members are down or unreachable. If a majority is running, then skip these procedures and instead use the rs.reconfig() command according to the examples in Examples.

If you run a pre-2.0 version and a majority of your replica set is down, you have the two options described here. Both involve replacing the replica set.

Reconfigure by Turning Off Replication

This option replaces the replica set with a standalone server.

Stop the surviving mongod instances. To ensure a clean shutdown, use an existing control script or use the db.shutdownServer() method.

For example, to use the db.shutdownServer() method, connect to the server using the mongo shell and issue the following sequence of commands:

use admin
db.shutdownServer()

Create a backup of the data directory (i.e. dbPath) of the surviving members of the set.

Optional

If you have a backup of the database you may instead remove this data.

Restart one of the mongod instances without the --replSet parameter.

The data is now accessible and provided by a single server that is not a replica set member. Clients can use this server for both reads and writes.

When possible, re-deploy a replica set to provide redundancy and to protect your deployment from operational interruption.

Reconfigure by “Breaking the Mirror”

This option selects a surviving replica set member to be the new primary and to “seed” a new replica set. In the following procedure, the new primary is db0.example.net. MongoDB copies the data from db0.example.net to all the other members.

Stop the surviving mongod instances. To ensure a clean shutdown, use an existing control script or use the db.shutdownServer() method.

For example, to use the db.shutdownServer() method, connect to the server using the mongo shell and issue the following sequence of commands:

use admin
db.shutdownServer()

Move the data directories (i.e. dbPath) for all the members except db0.example.net, so that all the members except db0.example.net have empty data directories. For example:

mv /data/db /data/db-old

Move the data files for local database (i.e. local.*) so that db0.example.net has no local database. For example

mkdir /data/local-old
mv /data/db/local* /data/local-old/

Start each member of the replica set normally.

Connect to db0.example.net in a mongo shell and run rs.initiate() to initiate the replica set.

Add the other set members using rs.add(). For example, to add a member running on db1.example.net at port 27017, issue the following command:

rs.add("db1.example.net:27017")

MongoDB performs an initial sync on the added members by copying all data from db0.example.net to the added members.

See also

Resync a Member of a Replica Set

Manage Chained Replication

Starting in version 2.0, MongoDB supports chained replication. A chained replication occurs when a secondary member replicates from another secondary member instead of from the primary. This might be the case, for example, if a secondary selects its replication target based on ping time and if the closest member is another secondary.

Chained replication can reduce load on the primary. But chained replication can also result in increased replication lag, depending on the topology of the network.

New in version 2.2.2.

You can use the chainingAllowed setting in Replica Set Configuration to disable chained replication for situations where chained replication is causing lag.

MongoDB enables chained replication by default. This procedure describes how to disable it and how to re-enable it.

Note

If chained replication is disabled, you still can use replSetSyncFrom to specify that a secondary replicates from another secondary. But that configuration will last only until the secondary recalculates which member to sync from.

Disable Chained Replication

To disable chained replication, set the chainingAllowed field in Replica Set Configuration to false.

You can use the following sequence of commands to set chainingAllowed to false:

Copy the configuration settings into the cfg object:

cfg = rs.config()

Take note of whether the current configuration settings contain the settings embedded document. If they do, skip this step.

Warning

To avoid data loss, skip this step if the configuration settings contain the settings embedded document.

If the current configuration settings do not contain the settings embedded document, create the embedded document by issuing the following command:

cfg.settings = { }

Issue the following sequence of commands to set chainingAllowed to false:

cfg.settings.chainingAllowed = false
rs.reconfig(cfg)

Re-enable Chained Replication

To re-enable chained replication, set chainingAllowed to true. You can use the following sequence of commands:

cfg = rs.config()
cfg.settings.chainingAllowed = true
rs.reconfig(cfg)

Change Hostnames in a Replica Set

For most replica sets, the hostnames in the host field never change. However, if organizational needs change, you might need to migrate some or all host names.

Note

Always use resolvable hostnames for the value of the host field in the replica set configuration to avoid confusion and complexity.

Overview

This document provides two separate procedures for changing the hostnames in the host field. Use either of the following approaches:

Change hostnames without disrupting availability. This approach ensures your applications will always be able to read and write data to the replica set, but the approach can take a long time and may incur downtime at the application layer.

If you use the first procedure, you must configure your applications to connect to the replica set at both the old and new locations, which often requires a restart and reconfiguration at the application layer and which may affect the availability of your applications. Re-configuring applications is beyond the scope of this document.

Stop all members running on the old hostnames at once. This approach has a shorter maintenance window, but the replica set will be unavailable during the operation.

See also

Replica Set Reconfiguration Process, Deploy a Replica Set, and Add Members to a Replica Set.

Assumptions

Given a replica set with three members:

database0.example.com:27017 (the primary)

database1.example.com:27017

database2.example.com:27017

And with the following rs.conf() output:

{
    "_id" : "rs",
    "version" : 3,
    "members" : [
        {
            "_id" : 0,
            "host" : "database0.example.com:27017"
        },
        {
            "_id" : 1,
            "host" : "database1.example.com:27017"
        },
        {
            "_id" : 2,
            "host" : "database2.example.com:27017"
        }
    ]
}

The following procedures change the members’ hostnames as follows:

mongodb0.example.net:27017 (the primary)

mongodb1.example.net:27017

mongodb2.example.net:27017

Use the most appropriate procedure for your deployment.

Change Hostnames while Maintaining Replica Set Availability

This procedure uses the above assumptions.

For each secondary in the replica set, perform the following sequence of operations:

Stop the secondary.

Restart the secondary at the new location.

Open a mongo shell connected to the replica set’s primary. In our example, the primary runs on port 27017 so you would issue the following command:

mongo --port 27017

Use rs.reconfig() to update the replica set configuration document with the new hostname.

For example, the following sequence of commands updates the hostname for the secondary at the array index 1 of the members array (i.e. members[1]) in the replica set configuration document:

cfg = rs.conf()
cfg.members[1].host = "mongodb1.example.net:27017"
rs.reconfig(cfg)

For more information on updating the configuration document, see Examples.

Make sure your client applications are able to access the set at the new location and that the secondary has a chance to catch up with the other members of the set.

Repeat the above steps for each non-primary member of the set.

Open a mongo shell connected to the primary and step down the primary using the rs.stepDown() method:

rs.stepDown()

The replica set elects another member to the become primary.

When the step down succeeds, shut down the old primary.

Start the mongod instance that will become the new primary in the new location.

Connect to the current primary, which was just elected, and update the replica set configuration document with the hostname of the node that is to become the new primary.

For example, if the old primary was at position 0 and the new primary’s hostname is mongodb0.example.net:27017, you would run:

cfg = rs.conf()
cfg.members[0].host = "mongodb0.example.net:27017"
rs.reconfig(cfg)

Open a mongo shell connected to the new primary.

To confirm the new configuration, call rs.conf() in the mongo shell.

Your output should resemble:

{
    "_id" : "rs",
    "version" : 4,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
        }
    ]
}

Change All Hostnames at the Same Time

This procedure uses the above assumptions.

Stop all members in the replica set.

Restart each member on a different port and without using the --replSet run-time option. Changing the port number during maintenance prevents clients from connecting to this host while you perform maintenance. Use the member’s usual --dbpath, which in this example is /data/db1. Use a command that resembles the following:

mongod --dbpath /data/db1/ --port 37017

For each member of the replica set, perform the following sequence of operations:

Open a mongo shell connected to the mongod running on the new, temporary port. For example, for a member running on a temporary port of 37017, you would issue this command:

mongo --port 37017

Edit the replica set configuration manually. The replica set configuration is the only document in the system.replset collection in the local database. Edit the replica set configuration with the new hostnames and correct ports for all the members of the replica set. Consider the following sequence of commands to change the hostnames in a three-member set:

use local

cfg = db.system.replset.findOne( { "_id": "rs" } )

cfg.members[0].host = "mongodb0.example.net:27017"

cfg.members[1].host = "mongodb1.example.net:27017"

cfg.members[2].host = "mongodb2.example.net:27017"

db.system.replset.update( { "_id": "rs" } , cfg )

Stop the mongod process on the member.

After re-configuring all members of the set, start each mongod instance in the normal way: use the usual port number and use the --replSet option. For example:

mongod --dbpath /data/db1/ --port 27017 --replSet rs

Connect to one of the mongod instances using the mongo shell. For example:

mongo --port 27017

To confirm the new configuration, call rs.conf() in the mongo shell.

Your output should resemble:

{
    "_id" : "rs",
    "version" : 4,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
        }
    ]
}

Configure a Secondary’s Sync Target

Overview

Secondaries capture data from the primary member to maintain an up to date copy of the sets’ data. However, by default secondaries may automatically change their sync targets to secondary members based on changes in the ping time between members and the state of other members’ replication. See Replica Set Data Synchronization and Manage Chained Replication for more information.

For some deployments, implementing a custom replication sync topology may be more effective than the default sync target selection logic. MongoDB provides the ability to specify a host to use as a sync target.

To override the default sync target selection logic, you may manually configure a secondary member’s sync target to temporarily pull oplog entries. The following provide access to this functionality:

replSetSyncFrom command, or

rs.syncFrom() helper in the mongo shell

Considerations

Sync Logic

Only modify the default sync logic as needed, and always exercise caution. rs.syncFrom() will not affect an in-progress initial sync operation. To affect the sync target for the initial sync, run rs.syncFrom() operation before initial sync.

If you run rs.syncFrom() during initial sync, MongoDB produces no error messages, but the sync target will not change until after the initial sync operation.

Persistence

replSetSyncFrom and rs.syncFrom() provide a temporary override of default behavior. mongod will revert to the default sync behavior in the following situations:

The mongod instance restarts.

The connection between the mongod and the sync target closes.

Changed in version 2.4: The sync target falls more than 30 seconds behind another member of the replica set; the mongod will revert to the default sync target.

Target

The member to sync from must be a valid source for data in the set. To sync from a member, the member must:

Have data. It cannot be an arbiter, in startup or recovering mode, and must be able to answer data queries.

Be accessible.

Be a member of the same set in the replica set configuration.

Build indexes with the buildIndexes setting.

A different member of the set, to prevent syncing from itself.

If you attempt to replicate from a member that is more than 10 seconds behind the current member, mongod will log a warning but will still replicate from the lagging member.

If you run replSetSyncFrom during initial sync, MongoDB produces no error messages, but the sync target will not change until after the initial sync operation.

Procedure

To use the replSetSyncFrom command in the mongo shell:

db.adminCommand( { replSetSyncFrom: "hostname<:port>" } );

To use the rs.syncFrom() helper in the mongo shell:

rs.syncFrom("hostname<:port>");

Troubleshoot Replica Sets

This section describes common strategies for troubleshooting replica set deployments.

Check Replica Set Status

To display the current state of the replica set and current state of each member, run the rs.status() method in a mongo shell connected to the replica set’s primary. For descriptions of the information displayed by rs.status(), see replSetGetStatus.

Note

The rs.status() method is a wrapper that runs the replSetGetStatus database command.

Check the Replication Lag

Replication lag is a delay between an operation on the primary and the application of that operation from the oplog to the secondary. Replication lag can be a significant issue and can seriously affect MongoDB replica set deployments. Excessive replication lag makes “lagged” members ineligible to quickly become primary and increases the possibility that distributed read operations will be inconsistent.

To check the current length of replication lag:

In a mongo shell connected to the primary, call the rs.printSlaveReplicationInfo() method.

Returns the syncedTo value for each member, which shows the time when the last oplog entry was written to the secondary, as shown in the following example:

source: m1.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary
source: m2.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary

A delayed member may show as 0 seconds behind the primary when the inactivity period on the primary is greater than the slaveDelay value.

Note

The rs.status() method is a wrapper around the replSetGetStatus database command.

Monitor the rate of replication by watching the oplog time in the “replica” graph in the MongoDB Management Service [https://mms.mongodb.com/]. For more information see the documentation for MMS [https://docs.mms.mongodb.com/].

Possible causes of replication lag include:

Network Latency

Check the network routes between the members of your set to ensure that there is no packet loss or network routing issue.

Use tools including ping to test latency between set members and traceroute to expose the routing of packets network endpoints.

Disk Throughput

If the file system and disk device on the secondary is unable to flush data to disk as quickly as the primary, then the secondary will have difficulty keeping state. Disk-related issues are incredibly prevalent on multi-tenant systems, including virtualized instances, and can be transient if the system accesses disk devices over an IP network (as is the case with Amazon’s EBS system.)

Use system-level tools to assess disk status, including iostat or vmstat.

Concurrency

In some cases, long-running operations on the primary can block replication on secondaries. For best results, configure write concern to require confirmation of replication to secondaries, as described in replica set write concern. This prevents write operations from returning if replication cannot keep up with the write load.

Use the database profiler to see if there are slow queries or long-running operations that correspond to the incidences of lag.

Appropriate Write Concern

If you are performing a large data ingestion or bulk load operation that requires a large number of writes to the primary, particularly with unacknowledged write concern, the secondaries will not be able to read the oplog fast enough to keep up with changes.

To prevent this, require write acknowledgment or journaled write concern after every 100, 1,000, or an another interval to provide an opportunity for secondaries to catch up with the primary.

For more information see:

Replica Acknowledge Write Concern

Replica Set Write Concern

Oplog Size

Test Connections Between all Members

All members of a replica set must be able to connect to every other member of the set to support replication. Always verify connections in both “directions.” Networking topologies and firewall configurations prevent normal and required connectivity, which can block replication.

Consider the following example of a bidirectional test of networking:

Example

Given a replica set with three members running on three separate hosts:

m1.example.net

m2.example.net

m3.example.net

Test the connection from m1.example.net to the other hosts with the following operation set m1.example.net:

mongo --host m2.example.net --port 27017

mongo --host m3.example.net --port 27017

Test the connection from m2.example.net to the other two hosts with the following operation set from m2.example.net, as in:

mongo --host m1.example.net --port 27017

mongo --host m3.example.net --port 27017

You have now tested the connection between m2.example.net and m1.example.net in both directions.

Test the connection from m3.example.net to the other two hosts with the following operation set from the m3.example.net host, as in:

mongo --host m1.example.net --port 27017

mongo --host m2.example.net --port 27017

If any connection, in any direction fails, check your networking and firewall configuration and reconfigure your environment to allow these connections.

Socket Exceptions when Rebooting More than One Secondary

When you reboot members of a replica set, ensure that the set is able to elect a primary during the maintenance. This means ensuring that a majority of the set’s ‘votes are available.

When a set’s active members can no longer form a majority, the set’s primary steps down and becomes a secondary. The former primary closes all open connections to client applications. Clients attempting to write to the former primary receive socket exceptions and Connection reset errors until the set can elect a primary.

Example

Given a three-member replica set where every member has one vote, the set can elect a primary only as long as two members can connect to each other. If two you reboot the two secondaries once, the primary steps down and becomes a secondary. Until the at least one secondary becomes available, the set has no primary and cannot elect a new primary.

For more information on votes, see Replica Set Elections. For related information on connection errors, see Does TCP keepalive time affect sharded clusters and replica sets?.

Check the Size of the Oplog

A larger oplog can give a replica set a greater tolerance for lag, and make the set more resilient.

To check the size of the oplog for a given replica set member, connect to the member in a mongo shell and run the rs.printReplicationInfo() method.

The output displays the size of the oplog and the date ranges of the operations contained in the oplog. In the following example, the oplog is about 10MB and is able to fit about 26 hours (94400 seconds) of operations:

configured oplog size:   10.10546875MB
log length start to end: 94400 (26.22hrs)
oplog first event time:  Mon Mar 19 2012 13:50:38 GMT-0400 (EDT)
oplog last event time:   Wed Oct 03 2012 14:59:10 GMT-0400 (EDT)
now:                     Wed Oct 03 2012 15:00:21 GMT-0400 (EDT)

The oplog should be long enough to hold all transactions for the longest downtime you expect on a secondary. At a minimum, an oplog should be able to hold minimum 24 hours of operations; however, many users prefer to have 72 hours or even a week’s work of operations.

For more information on how oplog size affects operations, see:

Oplog Size,

Delayed Replica Set Members, and

Check the Replication Lag.

Note

You normally want the oplog to be the same size on all members. If you resize the oplog, resize it on all members.

To change oplog size, see the Change the Size of the Oplog tutorial.

Oplog Entry Timestamp Error

Consider the following error in mongod output and logs:

replSet error fatal couldn't query the local local.oplog.rs collection.  Terminating mongod after 30 seconds.
<timestamp> [rsStart] bad replSet oplog entry?

Often, an incorrectly typed value in the ts field in the last oplog entry causes this error. The correct data type is Timestamp.

Check the type of the ts value using the following two queries against the oplog collection:

db = db.getSiblingDB("local")
db.oplog.rs.find().sort({$natural:-1}).limit(1)
db.oplog.rs.find({ts:{$type:17}}).sort({$natural:-1}).limit(1)

The first query returns the last document in the oplog, while the second returns the last document in the oplog where the ts value is a Timestamp. The $type operator allows you to select BSON type 17, is the Timestamp data type.

If the queries don’t return the same document, then the last document in the oplog has the wrong data type in the ts field.

Example

If the first query returns this as the last oplog entry:

{ "ts" : {t: 1347982456000, i: 1},
  "h" : NumberLong("8191276672478122996"),
  "op" : "n",
  "ns" : "",
  "o" : { "msg" : "Reconfig set", "version" : 4 } }

And the second query returns this as the last entry where ts has the Timestamp type:

{ "ts" : Timestamp(1347982454000, 1),
  "h" : NumberLong("6188469075153256465"),
  "op" : "n",
  "ns" : "",
  "o" : { "msg" : "Reconfig set", "version" : 3 } }

Then the value for the ts field in the last oplog entry is of the wrong data type.

To set the proper type for this value and resolve this issue, use an update operation that resembles the following:

db.oplog.rs.update( { ts: { t:1347982456000, i:1 } },
                    { $set: { ts: new Timestamp(1347982456000, 1)}})

Modify the timestamp values as needed based on your oplog entry. This operation may take some period to complete because the update must scan and pull the entire oplog into memory.

Duplicate Key Error on local.slaves

The duplicate key on local.slaves error, occurs when a secondary or slave changes its hostname and the primary or master tries to update its local.slaves collection with the new name. The update fails because it contains the same _id value as the document containing the previous hostname. The error itself will resemble the following.

exception: E11000 duplicate key error index: local.slaves.$_id_  dup key: { : ObjectId('<object ID>') } 0ms

This is a benign error and does not affect replication operations on the secondary or slave.

To prevent the error from appearing, drop the local.slaves collection from the primary or master, with the following sequence of operations in the mongo shell:

use local
db.slaves.drop()

The next time a secondary or slave polls the primary or master, the primary or master recreates the local.slaves collection.

Replication Reference

Replication Methods in the mongo Shell

Name | Description
rs.add() | Adds a member to a replica set.
rs.addArb() | Adds an arbiter to a replica set.
rs.conf() | Returns the replica set configuration document.
rs.freeze() | Prevents the current member from seeking election as primary for a period of time.
rs.help() | Returns basic help text for replica set functions.
rs.initiate() | Initializes a new replica set.
rs.printReplicationInfo() | Prints a report of the status of the replica set from the perspective of the primary.
rs.printSlaveReplicationInfo() | Prints a report of the status of the replica set from the perspective of the secondaries.
rs.reconfig() | Re-configures a replica set by applying a new replica set configuration object.
rs.remove() | Remove a member from a replica set.
rs.slaveOk() | Sets the slaveOk property for the current connection. Deprecated. Use readPref() and Mongo.setReadPref() to set read preference.
rs.status() | Returns a document with information about the state of the replica set.
rs.stepDown() | Causes the current primary to become a secondary which forces an election.
rs.syncFrom() | Sets the member that this replica set member will sync from, overriding the default sync target selection logic.

Replication Database Commands

Name | Description
replSetFreeze | Prevents the current member from seeking election as primary for a period of time.
replSetGetStatus | Returns a document that reports on the status of the replica set.
replSetInitiate | Initializes a new replica set.
replSetMaintenance | Enables or disables a maintenance mode, which puts a secondary node in a RECOVERING state.
replSetReconfig | Applies a new configuration to an existing replica set.
replSetStepDown | Forces the current primary to step down and become a secondary, forcing an election.
replSetSyncFrom | Explicitly override the default logic for selecting a member to replicate from.
resync | Forces a mongod to re-synchronize from the master. For master-slave replication only.
applyOps | Internal command that applies oplog entries to the current data set.
isMaster | Displays information about this member’s role in the replica set, including whether it is the master.
getoptime | Internal command to support replication, returns the optime.

Replica Set Reference Documentation

Replica Set Configuration

Complete documentation of the replica set configuration object returned by rs.conf().

The local Database

Complete documentation of the content of the local database that mongod instances use to support replication.

Replica Set Member States

Reference for the replica set member states.

Read Preference Reference

Complete documentation of the five read preference modes that the MongoDB drivers support.

Replica Set Configuration

The local Database

Replica Set Member States

Read Preference Reference

Replica Set Configuration

The configuration for a replica set is stored as a document in the system.replset collection in the local database.

Replica Set Configuration Document

The following document provides a representation of a replica set configuration document. The configuration of your replica set may include only a subset of these settings:

{
  _id: <string>,
  version: <int>,
  members: [
    {
      _id: <int>,
      host: <string>,
      arbiterOnly: <boolean>,
      buildIndexes: <boolean>,
      hidden: <boolean>,
      priority: <number>,
      tags: <document>,
      slaveDelay: <int>,
      votes: <number>
    },
    ...
  ],
  settings: {
    getLastErrorDefaults : <document>,
    chainingAllowed : <boolean>,
    getLastErrorModes : <document>,
    heartbeatTimeoutSecs: <int>
  }
}

Configuration Settings

local.system.replset._id

Type: string

The name of the replica set. Once set, you cannot change the name of a replica set.

See

replSetName or --replSet for information on setting the replica set name.

local.system.replset.version

An incrementing number used to distinguish revisions of the replica set configuration object from previous iterations of the configuration.

replset.members

local.system.replset.members

Type: array

An array of member configuration documents, one for each member of the replica set. The members array is a zero-indexed array.

Each member-specific configuration document can contain the following fields:

local.system.replset.members[n]._id

Type: integer

A numeric identifier of every member in the replica set. Once set, you cannot change the _id of a member.

Note

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the _id field in each document in the members array.

local.system.replset.members[n].host

Type: string

The hostname and, if specified, the port number, of the set member.

The hostname name must be resolvable for every host in the replica set.

Warning

host cannot hold a value that resolves to localhost or the local interface unless all members of the set are on hosts that resolve to localhost.

local.system.replset.members[n].arbiterOnly

Optional.

Type: boolean

Default: false

A boolean that identifies an arbiter. A value of true indicates that the member is an arbiter.

When using the rs.addArb() method to add an arbiter, the method automatically sets arbiterOnly to true for the added member.

local.system.replset.members[n].buildIndexes

Optional.

Type: boolean

Default: true

A boolean that indicates whether the mongod builds indexes on this member. You can only set this value when adding a member to a replica set. You cannot change buildIndexes field after the member has been added to the set. To add a member, see rs.add() and rs.reconfig().

Do not set to false for mongod instances that receive queries from clients.

Setting buildIndexes to false may be useful if all the following conditions are true:

you are only using this instance to perform backups using mongodump, and

this member will receive no queries, and

index creation and maintenance overburdens the host system.

Even if set to false, secondaries will build indexes on the _id field in order to facilitate operations required for replication.

Warning

If you set buildIndexes to false, you must also set priority to 0. If priority is not 0, MongoDB will return an error when attempting to add a member with buildIndexes equal to false.

To ensure the member receives no queries, you should make all instances that do not build indexes hidden.

Other secondaries cannot replicate from a member where buildIndexes is false.

local.system.replset.members[n].hidden

Optional.

Type: boolean

Default: false

When this value is true, the replica set hides this instance and does not include the member in the output of db.isMaster() or isMaster. This prevents read operations (i.e. queries) from ever reaching this host by way of secondary read preference.

See also

Hidden Replica Set Members

local.system.replset.members[n].priority

Optional.

Type: Number, between 0 and 1000.

Default: 1.0

A number that indicates the relative eligibility of a member to become a primary.

Specify higher values to make a member more eligible to become primary, and lower values to make the member less eligible. Priorities are only used in comparison to each other. Members of the set will veto election requests from members when another eligible member has a higher priority value. Changing the balance of priority in a replica set will trigger an election.

A priority of 0 makes it impossible for a member to become primary.

See also

Replica Set Elections.

local.system.replset.members[n].tags

Optional.

Type: document

Default: none

A document that contains arbitrary field and value pairs for describing or tagging members in order to extend write concern and read preference and thereby allowing configurable data center awareness.

Use tags to configure write concerns in conjunction with getLastErrorModes and getLastErrorDefaults.

Important

In tag sets, all tag values must be strings.

For more information on configuring tag sets for read preference and write concern, see Configure Replica Set Tag Sets.

local.system.replset.members[n].slaveDelay

Optional.

Type: integer

Default: 0

The number of seconds “behind” the primary that this replica set member should “lag”.

Use this option to create delayed members. Delayed members maintain a copy of the data that reflects the state of the data at some time in the past.

See also

Delayed Replica Set Members

local.system.replset.members[n].votes

Optional.

Type: integer

Default: 1

The number of votes a server will cast in a replica set election. The number of votes each member has can be either 1 or 0.

A replica set can have up to 12 members, but can have at most only 7 voting members. If you need more than 7 members in one replica set, set votes to 0 for the additional non-voting members.

Note

Deprecated since version 2.6: votes values greater than 1.

Earlier versions of MongoDB allowed a member to have more than 1 vote by setting votes to a value greater than 1. Setting votes to value greater than 1 now produces a warning message.

replset.settings

local.system.replset.settings

Optional.

Type: document

A document that contains configuration options that apply to the whole replica set.

The settings document contain the following fields:

local.system.replset.settings.chainingAllowed

New in version 2.2.4.

Optional.

Type: boolean

Default: true

When chainingAllowed is true, the replica set allows secondary members to replicate from other secondary members. When chainingAllowed is false, secondaries can replicate only from the primary.

When you run rs.conf() to view a replica set’s configuration, the chainingAllowed field appears only when set to false. If not set, chainingAllowed is true.

See also

Manage Chained Replication

local.system.replset.settings.getLastErrorDefaults

Optional.

Type: document

A document that specifies the write concern for the replica set. The replica set will use this write concern only when write operations or getLastError specify no other write concern.

If getLastErrorDefaults is not set, the default write concern for the replica set only requires confirmation from the primary.

local.system.replset.settings.getLastErrorModes

Optional.

Type: document

A document used to define an extended write concern through the use of tags. The extended write concern can provide data-center awareness.

For example, the following document defines an extended write concern named eastCoast and associates with a write to a member that has the east tag.

{ getLastErrorModes: { eastCoast: { "east": 1 } } }

Write operations to the replica set can use the extended write concern, e.g. { w: "eastCoast" }.

See Configure Replica Set Tag Sets for more information and example.

local.system.replset.settings.heartbeatTimeoutSecs

Optional.

Type: int

Default: 10

Number of seconds that the replica set members wait for a successful heartbeat from each other. If a member does not respond in time, other members mark the delinquent member as inaccessible.

View Replica Set Configuration

To view the current configuration for a replica set, use the rs.conf() method. See rs.conf() for more information.

Modify Replica Set Configuration

To modify the configuration for a replica set, use the rs.reconfig() method, passing a configuration document to the method. See rs.reconfig() for more information.

The local Database

Overview

Every mongod instance has its own local database, which stores data used in the replication process, and other instance-specific data. The local database is invisible to replication: collections in the local database are not replicated.

In replication, the local database store stores internal replication data for each member of a replica set. The local stores the following collections:

Changed in version 2.4: When running with authentication (i.e. authorization), authenticating to the local database is not equivalent to authenticating to the admin database. In previous versions, authenticating to the local database provided access to all databases.

Collection on all mongod Instances

local.startup_log

On startup, each mongod instance inserts a document into startup_log with diagnostic information about the mongod instance itself and host information. startup_log is a capped collection. This information is primarily useful for diagnostic purposes.

Example

Consider the following prototype of a document from the startup_log collection:

{
  "_id" : "<string>",
  "hostname" : "<string>",
  "startTime" : ISODate("<date>"),
  "startTimeLocal" : "<string>",
  "cmdLine" : {
        "dbpath" : "<path>",
        "<option>" : <value>
  },
  "pid" : <number>,
  "buildinfo" : {
        "version" : "<string>",
        "gitVersion" : "<string>",
        "sysInfo" : "<string>",
        "loaderFlags" : "<string>",
        "compilerFlags" : "<string>",
        "allocator" : "<string>",
        "versionArray" : [ <num>, <num>, <...> ],
        "javascriptEngine" : "<string>",
        "bits" : <number>,
        "debug" : <boolean>,
        "maxBsonObjectSize" : <number>
  }
}

Documents in the startup_log collection contain the following fields:

local.startup_log._id

Includes the system hostname and a millisecond epoch value.

local.startup_log.hostname

The system’s hostname.

local.startup_log.startTime

A UTC ISODate value that reflects when the server started.

local.startup_log.startTimeLocal

A string that reports the startTime in the system’s local time zone.

local.startup_log.cmdLine

An embedded document that reports the mongod runtime options and their values.

local.startup_log.pid

The process identifier for this process.

local.startup_log.buildinfo

An embedded document that reports information about the build environment and settings used to compile this mongod. This is the same output as buildInfo. See buildInfo.

Collections on Replica Set Members

local.system.replset

local.system.replset holds the replica set’s configuration object as its single document. To view the object’s configuration information, issue rs.conf() from the mongo shell. You can also query this collection directly.

local.oplog.rs

local.oplog.rs is the capped collection that holds the oplog. You set its size at creation using the oplogSizeMB setting. To resize the oplog after replica set initiation, use the Change the Size of the Oplog procedure. For additional information, see the Oplog Size section.

local.replset.minvalid

This contains an object used internally by replica sets to track replication status.

local.slaves

This contains information about each member of the set and the latest point in time that this member has synced to. If this collection becomes out of date, you can refresh it by dropping the collection and allowing MongoDB to automatically refresh it during normal replication:

db.getSiblingDB("local").slaves.drop()

Collections used in Master/Slave Replication

In master/slave replication, the local database contains the following collections:

On the master:

local.oplog.$main

This is the oplog for the master-slave configuration.

local.slaves

This contains information about each slave.

On each slave:

local.sources

This contains information about the slave’s master server.

Replica Set Member States

Each member of a replica set has a state that reflects its disposition within the set.

Number | Name | State Description
0 | STARTUP | Not yet an active member of any set. All members start up in this state. The mongod parses the replica set configuration document while in STARTUP.
1 | PRIMARY | The member in state primary is the only member that can accept write operations.
2 | SECONDARY | A member in state secondary is replicating the data store. Data is available for reads, although they may be stale.
3 | RECOVERING | A member in this state is replicating the data store but does not yet have a consistent view of the data. Data is not available for reads until the member transitions to state secondary.
5 | STARTUP2 | The member has joined the set and is running an initial sync.
6 | UNKNOWN | The member’s state, as seen from another member of the set, is not yet known.
7 | ARBITER | Arbiters do not replicate data and exist solely to participate in elections.
8 | DOWN | The member, as seen from another member of the set, is unreachable.
9 | ROLLBACK | This member is actively performing a rollback. Data is not available for reads.
10 | REMOVED | This member was once in a replica set but was subsequently removed.

States

Core States

PRIMARY

Members in PRIMARY state accept write operations. A replica set has at most one primary at a time. A SECONDARY member becomes primary after an election. Members in the PRIMARY state are eligible to vote.

SECONDARY

Members in SECONDARY state replicate the primary’s data set and can be configured to accept read operations. Secondaries are eligible to vote in elections, and may be elected to the PRIMARY state if the primary becomes unavailable.

ARBITER

Members in ARBITER state do not replicate data or accept write operations. They are eligible to vote, and exist solely to break a tie during elections. Replica sets should only have a member in the ARBITER state if the set would otherwise have an even number of members, and could suffer from tied elections. There should only be at most one arbiter configured in any replica set.

See Replica Set Members for more information on core states.

Other States

STARTUP

Each member of a replica set starts up in STARTUP state. mongod then loads that member’s replica set configuration, and transitions the member’s state to STARTUP2. Members in STARTUP are not eligible to vote, as they are not yet a recognized member of any replica set.

STARTUP2

Each member of a replica set enters the STARTUP2 state as soon as mongod finishes loading that member’s configuration, at which time it becomes an active member of the replica set. The member then decides whether or not to undertake an initial sync. If a member begins an initial sync, the member remains in STARTUP2 until all data is copied and all indexes are built. Afterwards, the member transitions to RECOVERING.

RECOVERING

A member of a replica set enters RECOVERING state when it is not ready to accept reads. The RECOVERING state can occur during normal operation, and doesn’t necessarily reflect an error condition. Members in the RECOVERING state are eligible to vote in elections, but are not eligible to enter the PRIMARY state.

A member transitions from RECOVERING to SECONDARY after replicating enough data to guarantee a consistent view of the data for client reads. The only difference between RECOVERING and SECONDARY states is that RECOVERING prohibits client reads and SECONDARY permits them. SECONDARY state does not guarantee anything about the staleness of the data with respect to the primary.

Due to overload, a secondary may fall far enough behind the other members of the replica set such that it may need to resync with the rest of the set. When this happens, the member enters the RECOVERING state and requires manual intervention.

Members in SECONDARY state can be forced into state RECOVERING to prevent client reads by using _maintenance mode_. You can toggle maintenance mode with the replSetMaintenance command. Maintenance mode is also enabled automatically by the compact and touch commands. While maintenance mode is on, a member will remain in RECOVERING state and will reject client reads.

UNKNOWN

Members that have never communicated status information to the replica set are in the UNKNOWN state.

DOWN

Members that lose their connection to the replica set are seen as DOWN by the remaining members of the set.

REMOVED

Members that are removed from the replica set enter the REMOVED state. When members enter the REMOVED state, the logs will mark this event with a replSet REMOVED message entry.

ROLLBACK

Whenever the replica set replaces a primary in an election, the old primary may contain documents that did not replicate to the secondary members. In this case, the old primary member reverts those writes. During rollback, the member will have ROLLBACK state.

FATAL

A member in FATAL encountered an unrecoverable error. The member must be shut down and restarted; a resync may be required as well.

Read Preference Reference

Read preference describes how MongoDB clients route read operations to members of a replica set.

By default, an application directs its read operations to the primary member in a replica set. Reading from the primary guarantees that read operations reflect the latest version of a document. However, by distributing some or all reads to secondary members of the replica set, you can improve read throughput or reduce latency for an application that does not require fully up-to-date data.

Read Preference Mode | Description
primary | Default mode. All operations read from the current replica set primary.
primaryPreferred | In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
secondary | All operations read from the secondary members of the replica set.
secondaryPreferred | In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
nearest | Operations read from member of the replica set with the least network latency, irrespective of the member’s type.

Read Preference Modes

primary

All read operations use only the current replica set primary. This is the default. If the primary is unavailable, read operations produce an error or throw an exception.

The primary read preference mode is not compatible with read preference modes that use tag sets. If you specify a tag set with primary, the driver will produce an error.

primaryPreferred

In most situations, operations read from the primary member of the set. However, if the primary is unavailable, as is the case during failover situations, operations read from secondary members.

When the read preference includes a tag set, the client reads first from the primary, if available, and then from secondaries that match the specified tags. If no secondaries have matching tags, the read operation produces an error.

Since the application may receive data from a secondary, read operations using the primaryPreferred mode may return stale data in some situations.

Warning

Changed in version 2.2: mongos added full support for read preferences.

When connecting to a mongos instance older than 2.2, using a client that supports read preference modes, primaryPreferred will send queries to secondaries.

secondary

Operations read only from the secondary members of the set. If no secondaries are available, then this read operation produces an error or exception.

Most sets have at least one secondary, but there are situations where there may be no available secondary. For example, a set with a primary, a secondary, and an arbiter may not have any secondaries if a member is in recovering state or unavailable.

When the read preference includes a tag set, the client attempts to find secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group. If no secondaries have matching tags, the read operation produces an error. [1]

Read operations using the secondary mode may return stale data.

secondaryPreferred

In most situations, operations read from secondary members, but in situations where the set consists of a single primary (and no other members), the read operation will use the set’s primary.

When the read preference includes a tag set, the client attempts to find a secondary member that matches the specified tag set and directs reads to a random secondary from among the nearest group. If no secondaries have matching tags, the client ignores tags and reads from the primary.

Read operations using the secondaryPreferred mode may return stale data.

nearest

The driver reads from the nearest member of the set according to the member selection process. Reads in the nearest mode do not consider the member’s type. Reads in nearest mode may read from both primaries and secondaries.

Set this mode to minimize the effect of network latency on read operations without preference for current or stale data.

If you specify a tag set, the client attempts to find a replica set member that matches the specified tag set and directs reads to an arbitrary member from among the nearest group.

Read operations using the nearest mode may return stale data.

Note

All operations read from a member of the nearest group of the replica set that matches the specified read preference mode. The nearest mode prefers low latency reads over a member’s primary or secondary status.

For nearest, the client assembles a list of acceptable hosts based on tag set and then narrows that list to the host with the shortest ping time and all other members of the set that are within the “local threshold,” or acceptable latency. See Member Selection for more information.

[1]
If your set has more than one secondary, and you use the secondary read preference mode, consider the following effect. If you have a three member replica set with a primary and two secondaries, and if one secondary becomes unavailable, all secondary queries must target the remaining secondary. This will double the load on this secondary. Plan and provide capacity to support this as needed.

Use Cases

Depending on the requirements of an application, you can configure different applications to use different read preferences, or use different read preferences for different queries in the same application. Consider the following applications for different read preference strategies.

Maximize Consistency

To avoid stale reads under all circumstances, use primary. This prevents all queries when the set has no primary, which happens during elections, or when a majority of the replica set is not accessible.

Maximize Availability

To permit read operations when possible, Use primaryPreferred. When there’s a primary you will get consistent reads, but if there is no primary you can still query secondaries.

Minimize Latency

To always read from a low-latency node, use nearest. The driver or mongos will read from the nearest member and those no more than 15 milliseconds [2] further away than the nearest member.

nearest does not guarantee consistency. If the nearest member to your application server is a secondary with some replication lag, queries could return stale data. nearest only reflects network distance and does not reflect I/O or CPU load.

[2]
This threshold is configurable. See localPingThresholdMs for mongos or your driver documentation for the appropriate setting.

Query From Geographically Distributed Members

If the members of a replica set are geographically distributed, you can create replica tags based that reflect the location of the instance and then configure your application to query the members nearby.

For example, if members in “east” and “west” data centers are tagged {'dc': 'east'} and {'dc': 'west'}, your application servers in the east data center can read from nearby members with the following read preference:

db.collection.find().readPref( { mode: 'nearest',
                                 tags: [ {'dc': 'east'} ] } )

Although nearest already favors members with low network latency, including the tag makes the choice more predictable.

Reduce load on the primary

To shift read load from the primary, use mode secondary. Although secondaryPreferred is tempting for this use case, it carries some risk: if all secondaries are unavailable and your set has enough arbiters to prevent the primary from stepping down, then the primary will receive all traffic from clients. If the primary is unable to handle this load, queries will compete with writes. For this reason, use secondary to distribute read load to replica sets, not secondaryPreferred.

Read Preferences for Database Commands

Because some database commands read and return data from the database, all of the official drivers support full read preference mode semantics for the following commands:

group

mapReduce [3]

aggregate [4]

collStats

dbStats

count

distinct

geoNear

geoSearch

geoWalk

parallelCollectionScan

New in version 2.4: mongos adds support for routing commands to shards using read preferences. Previously mongos sent all commands to shards’ primaries.

[3]
Only “inline” mapReduce operations that do not write data support read preference, otherwise these operations must run on the primary members.

[4]
Using the $out pipeline operator forces the aggregation pipeline to run on the primary.

Sharding

Sharding is the process of storing data records across multiple machines and is MongoDB’s approach to meeting the demands of data growth. As the size of the data increases, a single machine may not be sufficient to store the data nor provide an acceptable read and write throughput. Sharding solves the problem with horizontal scaling. With sharding, you add more machines to support data growth and the demands of read and write operations.

Sharding Introduction

A high-level introduction to horizontal scaling, data partitioning, and sharded clusters in MongoDB.

Sharding Concepts

The core documentation of sharded cluster features, configuration, architecture and behavior.

Sharded Cluster Components

A sharded cluster consists of shards, config servers, and mongos instances.

Sharded Cluster Architectures

Outlines the requirements for sharded clusters, and provides examples of several possible architectures for sharded clusters.

Sharded Cluster Behavior

Discusses the operations of sharded clusters with regards to the automatic balancing of data in a cluster and other related availability and security considerations.

Sharding Mechanics

Discusses the internal operation and behavior of sharded clusters, including chunk migration, balancing, and the cluster metadata.

Sharded Cluster Tutorials

Tutorials that describe common procedures and administrative operations relevant to the use and maintenance of sharded clusters.

Sharding Reference

Reference for sharding-related functions and operations.

Sharding Introduction

Sharding Concepts

Sharded Cluster Components

Shards

Config Servers

Sharded Cluster Architectures

Sharded Cluster Requirements

Production Cluster Architecture

Sharded Cluster Test Architecture

Sharded Cluster Behavior

Shard Keys

Sharded Cluster High Availability

Sharded Cluster Query Routing

Sharding Mechanics

Sharded Collection Balancing

Chunk Migration Across Shards

Chunk Splits in a Sharded Cluster

Shard Key Indexes

Sharded Cluster Metadata

Sharded Cluster Tutorials

Sharded Cluster Deployment Tutorials

Deploy a Sharded Cluster

Considerations for Selecting Shard Keys

Shard a Collection Using a Hashed Shard Key

Add Shards to a Cluster

Deploy Three Config Servers for Production Deployments

Convert a Replica Set to a Replicated Sharded Cluster

Convert Sharded Cluster to Replica Set

Sharded Cluster Maintenance Tutorials

View Cluster Configuration

Migrate Config Servers with the Same Hostname

Migrate Config Servers with Different Hostnames

Replace Disabled Config Server

Migrate a Sharded Cluster to Different Hardware

Backup Cluster Metadata

Configure Behavior of Balancer Process in Sharded Clusters

Manage Sharded Cluster Balancer

Remove Shards from an Existing Sharded Cluster

Sharded Cluster Data Management

Create Chunks in a Sharded Cluster

Split Chunks in a Sharded Cluster

Migrate Chunks in a Sharded Cluster

Merge Chunks in a Sharded Cluster

Modify Chunk Size in a Sharded Cluster

Clear jumbo Flag

Tag Aware Sharding

Manage Shard Tags

Enforce Unique Keys for Sharded Collections

Shard GridFS Data Store

Troubleshoot Sharded Clusters

Sharding Reference

Config Database

Sharding Introduction

Sharding is a method for storing data across multiple machines. MongoDB uses sharding to support deployments with very large data sets and high throughput operations.

Purpose of Sharding

Database systems with large data sets and high throughput applications can challenge the capacity of a single server. High query rates can exhaust the CPU capacity of the server. Larger data sets exceed the storage capacity of a single machine. Finally, working set sizes larger than the system’s RAM stress the I/O capacity of disk drives.

To address these issues of scales, database systems have two basic approaches: vertical scaling and sharding.

Vertical scaling adds more CPU and storage resources to increase capacity. Scaling by adding capacity has limitations: high performance systems with large numbers of CPUs and large amount of RAM are disproportionately more expensive than smaller systems. Additionally, cloud-based providers may only allow users to provision smaller instances. As a result there is a practical maximum capability for vertical scaling.

Sharding, or horizontal scaling, by contrast, divides the data set and distributes the data over multiple servers, or shards. Each shard is an independent database, and collectively, the shards make up a single logical database.

Sharding addresses the challenge of scaling to support high throughput and large data sets:

Sharding reduces the number of operations each shard handles. Each shard processes fewer operations as the cluster grows. As a result, a cluster can increase capacity and throughput horizontally.

For example, to insert data, the application only needs to access the shard responsible for that record.

Sharding reduces the amount of data that each server needs to store. Each shard stores less data as the cluster grows.

For example, if a database has a 1 terabyte data set, and there are 4 shards, then each shard might hold only 256GB of data. If there are 40 shards, then each shard might hold only 25GB of data.

Sharding in MongoDB

MongoDB supports sharding through the configuration of a sharded clusters.

Sharded cluster has the following components: shards, query routers and config servers.

Shards store the data. To provide high availability and data consistency, in a production sharded cluster, each shard is a replica set [1]. For more information on replica sets, see Replica Sets.

Query Routers, or mongos instances, interface with client applications and direct operations to the appropriate shard or shards. The query router processes and targets operations to shards and then returns results to the clients. A sharded cluster can contain more than one query router to divide the client request load. A client sends requests to one query router. Most sharded clusters have many query routers.

Config servers store the cluster’s metadata. This data contains a mapping of the cluster’s data set to the shards. The query router uses this metadata to target operations to specific shards. Production sharded clusters have exactly 3 config servers.

[1]
For development and testing purposes only, each shard can be a single mongod instead of a replica set. Do not deploy production clusters without 3 config servers.

Data Partitioning

MongoDB distributes data, or shards, at the collection level. Sharding partitions a collection’s data by the shard key.

Shard Keys

To shard a collection, you need to select a shard key. A shard key is either an indexed field or an indexed compound field that exists in every document in the collection. MongoDB divides the shard key values into chunks and distributes the chunks evenly across the shards. To divide the shard key values into chunks, MongoDB uses either range based partitioning or hash based partitioning. See the Shard Key documentation for more information.

Range Based Sharding

For range-based sharding, MongoDB divides the data set into ranges determined by the shard key values to provide range based partitioning. Consider a numeric shard key: If you visualize a number line that goes from negative infinity to positive infinity, each value of the shard key falls at some point on that line. MongoDB partitions this line into smaller, non-overlapping ranges called chunks where a chunk is range of values from some minimum value to some maximum value.

Given a range based partitioning system, documents with “close” shard key values are likely to be in the same chunk, and therefore on the same shard.

Hash Based Sharding

For hash based partitioning, MongoDB computes a hash of a field’s value, and then uses these hashes to create chunks.

With hash based partitioning, two documents with “close” shard key values are unlikely to be part of the same chunk. This ensures a more random distribution of a collection in the cluster.

Performance Distinctions between Range and Hash Based Partitioning

Range based partitioning supports more efficient range queries. Given a range query on the shard key, the query router can easily determine which chunks overlap that range and route the query to only those shards that contain these chunks.

However, range based partitioning can result in an uneven distribution of data, which may negate some of the benefits of sharding. For example, if the shard key is a linearly increasing field, such as time, then all requests for a given time range will map to the same chunk, and thus the same shard. In this situation, a small set of shards may receive the majority of requests and the system would not scale very well.

Hash based partitioning, by contrast, ensures an even distribution of data at the expense of efficient range queries. Hashed key values results in random distribution of data across chunks and therefore shards. But random distribution makes it more likely that a range query on the shard key will not be able to target a few shards but would more likely query every shard in order to return a result.

Customized Data Distribution with Tag Aware Sharding

MongoDB allows administrators to direct the balancing policy using tag aware sharding. Administrators create and associate tags with ranges of the shard key, and then assign those tags to the shards. Then, the balancer migrates tagged data to the appropriate shards and ensures that the cluster always enforces the distribution of data that the tags describe.

Tags are the primary mechanism to control the behavior of the balancer and the distribution of chunks in a cluster. Most commonly, tag aware sharding serves to improve the locality of data for sharded clusters that span multiple data centers.

See Tag Aware Sharding for more information.

Maintaining a Balanced Data Distribution

The addition of new data or the addition of new servers can result in data distribution imbalances within the cluster, such as a particular shard contains significantly more chunks than another shard or a size of a chunk is significantly greater than other chunk sizes.

MongoDB ensures a balanced cluster using two background process: splitting and the balancer.

Splitting

Splitting is a background process that keeps chunks from growing too large. When a chunk grows beyond a specified chunk size, MongoDB splits the chunk in half. Inserts and updates triggers splits. Splits are an efficient meta-data change. To create splits, MongoDB does not migrate any data or affect the shards.

Balancing

The balancer is a background process that manages chunk migrations. The balancer can run from any the query routers in a cluster.

When the distribution of a sharded collection in a cluster is uneven, the balancer process migrates chunks from the shard that has the largest number of chunks to the shard with the least number of chunks until the collection balances. For example: if collection users has 100 chunks on shard 1 and 50 chunks on shard 2, the balancer will migrate chunks from shard 1 to shard 2 until the collection achieves balance.

The shards manage chunk migrations as a background operation between an origin shard and a destination shard. During a chunk migration, the destination shard is sent all the current documents in the chunk from the origin shard. Next, the destination shard captures and applies all changes made to the data during the migration process. Finally, the metadata regarding the location of the chunk on config server is updated.

If there’s an error during the migration, the balancer aborts the process leaving the chunk unchanged on the origin shard. MongoDB removes the chunk’s data from the origin shard after the migration completes successfully.

Adding and Removing Shards from the Cluster

Adding a shard to a cluster creates an imbalance since the new shard has no chunks. While MongoDB begins migrating data to the new shard immediately, it can take some time before the cluster balances.

When removing a shard, the balancer migrates all chunks from a shard to other shards. After migrating all data and updating the meta data, you can safely remove the shard.

Additional Resources

Sharding Methods for MongoDB (Presentation) [http://www.mongodb.com/presentations/webinar-sharding-methods-mongodb]

Everything You Need to Know About Sharding (Presentation) [http://www.mongodb.com/presentations/webinar-everything-you-need-know-about-sharding]

MongoDB for Time Series Data: Sharding [http://www.mongodb.com/presentations/mongodb-time-series-data-part-3-sharding]

MongoDB Operations Best Practices White Paper [http://www.mongodb.com/lp/white-paper/ops-best-practices]

Talk to a MongoDB Expert About Scaling [http://www.mongodb.com/lp/contact/planning-for-scale]

MongoDB Deployment Topology Consulting Package [https://www.mongodb.com/products/consulting#deployment_topology]

Sharding Concepts

These documents present the details of sharding in MongoDB. These include the components, the architectures, and the behaviors of MongoDB sharded clusters. For an overview of sharding and sharded clusters, see Sharding Introduction.

Sharded Cluster Components

A sharded cluster consists of shards, config servers, and mongos instances.

Shards

A shard is a mongod instance that holds a part of the sharded collection’s data.

Config Servers

Config servers hold the metadata about the cluster, such as the shard location of the data.

Sharded Cluster Architectures

Outlines the requirements for sharded clusters, and provides examples of several possible architectures for sharded clusters.

Sharded Cluster Requirements

Discusses the requirements for sharded clusters in MongoDB.

Production Cluster Architecture

Outlines the components required to deploy a redundant and highly available sharded cluster.

Continue reading from Sharded Cluster Architectures for additional descriptions of sharded cluster deployments.

Sharded Cluster Behavior

Discusses the operations of sharded clusters with regards to the automatic balancing of data in a cluster and other related availability and security considerations.

Shard Keys

MongoDB uses the shard key to divide a collection’s data across the cluster’s shards.

Sharded Cluster High Availability

Sharded clusters provide ways to address some availability concerns.

Sharded Cluster Query Routing

The cluster’s routers, or mongos instances, send reads and writes to the relevant shard or shards.

Sharding Mechanics

Discusses the internal operation and behavior of sharded clusters, including chunk migration, balancing, and the cluster metadata.

Sharded Collection Balancing

Balancing distributes a sharded collection’s data cluster to all of the shards.

Sharded Cluster Metadata

The cluster maintains internal metadata that reflects the location of data within the cluster.

Continue reading from Sharding Mechanics for more documentation of the behavior and operation of sharded clusters.

Sharded Cluster Components

Shards

Config Servers

Sharded Cluster Architectures

Sharded Cluster Requirements

Production Cluster Architecture

Sharded Cluster Test Architecture

Sharded Cluster Behavior

Shard Keys

Sharded Cluster High Availability

Sharded Cluster Query Routing

Sharding Mechanics

Sharded Collection Balancing

Chunk Migration Across Shards

Chunk Splits in a Sharded Cluster

Shard Key Indexes

Sharded Cluster Metadata

Sharded Cluster Components

Sharded clusters implement sharding. A sharded cluster consists of the following components:

Shards

A shard is a MongoDB instance that holds a subset of a collection’s data. Each shard is either a single mongod instance or a replica set. In production, all shards are replica sets. For more information see Shards.

Config Servers

Each config server is a mongod instance that holds metadata about the cluster. The metadata maps chunks to shards. For more information, see Config Servers.

Routing Instances

Each router is a mongos instance that routes the reads and writes from applications to the shards. Applications do not access the shards directly. For more information see Sharded Cluster Query Routing.

Enable sharding in MongoDB on a per-collection basis. For each collection you shard, you will specify a shard key for that collection.

Deploy a sharded cluster, see Deploy a Sharded Cluster.

Shards

Config Servers

Shards

A shard is a replica set or a single mongod that contains a subset of the data for the sharded cluster. Together, the cluster’s shards hold the entire data set for the cluster.

Typically each shard is a replica set. The replica set provides redundancy and high availability for the data in each shard.

Important

MongoDB shards data on a per collection basis. You must access all data in a sharded cluster via the mongos instances. If you connect directly to a shard, you will see only its fraction of the cluster’s data. There is no particular order to the data set on a specific shard. MongoDB does not guarantee that any two contiguous chunks will reside on a single shard.

Primary Shard

Every database has a “primary” [1] shard that holds all the un-sharded collections in that database.

To change the primary shard for a database, use the movePrimary command. The process of migrating the primary shard may take significant time to complete, and you should not access the collections until it completes.

When you deploy a new sharded cluster with shards that were previously used as replica sets, all existing databases continue to reside on their original shard. Databases created subsequently may reside on any shard in the cluster.

[1]
The term “primary” shard has nothing to do with the term primary in the context of replica sets.

Shard Status

Use the sh.status() method in the mongo shell to see an overview of the cluster. This reports includes which shard is primary for the database and the chunk distribution across the shards. See sh.status() method for more details.

Config Servers

Config servers are special mongod instances that store the metadata for a sharded cluster. Config servers use a two-phase commit to ensure immediate consistency and reliability. Config servers do not run as replica sets. All config servers must be available to deploy a sharded cluster or to make any changes to cluster metadata.

A production sharded cluster has exactly three config servers. For testing purposes you may deploy a cluster with a single config server. But to ensure redundancy and safety in production, you should always use three.

Warning

If your cluster has a single config server, then the config server is a single point of failure. If the config server is inaccessible, the cluster is not accessible. If you cannot recover the data on a config server, the cluster will be inoperable.

Always use three config servers for production deployments.

Each sharded cluster must have its own config servers. Do not use the same config servers for different sharded clusters.

Tip

Use CNAMEs to identify your config servers to the cluster so that you can rename and renumber your config servers without downtime.

Config Database

Config servers store the metadata in the config database. The mongos instances cache this data and use it to route reads and writes to shards.

Read and Write Operations on Config Servers

MongoDB only writes data to the config server in the following cases:

To create splits in existing chunks. For more information, see chunk splitting.

To migrate a chunk between shards. For more information, see chunk migration.

MongoDB reads data from the config server data in the following cases:

A new mongos starts for the first time, or an existing mongos restarts.

After a chunk migration, the mongos instances update themselves with the new cluster metadata.

MongoDB also uses the config server to manage distributed locks.

Config Server Availability

If one or two config servers become unavailable, the cluster’s metadata becomes read only. You can still read and write data from the shards, but no chunk migrations or splits will occur until all three servers are available.

If all three config servers are unavailable, you can still use the cluster if you do not restart the mongos instances until after the config servers are accessible again. If you restart the mongos instances before the config servers are available, the mongos will be unable to route reads and writes.

Clusters become inoperable without the cluster metadata. Always, ensure that the config servers remain available and intact. As such, backups of config servers are critical. The data on the config server is small compared to the data stored in a cluster. This means the config server has a relatively low activity load, and the config server does not need to be always available to support a sharded cluster. As a result, it is easy to back up the config servers.

If the name or address that a sharded cluster uses to connect to a config server changes, you must restart every mongod and mongos instance in the sharded cluster. Avoid downtime by using CNAMEs to identify config servers within the MongoDB deployment.

See Renaming Config Servers and Cluster Availability for more information.

Sharded Cluster Architectures

The following documents introduce deployment patterns for sharded clusters.

Sharded Cluster Requirements

Discusses the requirements for sharded clusters in MongoDB.

Production Cluster Architecture

Outlines the components required to deploy a redundant and highly available sharded cluster.

Sharded Cluster Test Architecture

Sharded clusters for testing and development can include fewer components.

Sharded Cluster Requirements

Production Cluster Architecture

Sharded Cluster Test Architecture

Sharded Cluster Requirements

While sharding is a powerful and compelling feature, sharded clusters have significant infrastructure requirements and increases the overall complexity of a deployment. As a result, only deploy sharded clusters when indicated by application and operational requirements

Sharding is the only solution for some classes of deployments. Use sharded clusters if:

your data set approaches or exceeds the storage capacity of a single MongoDB instance.

the size of your system’s active working set will soon exceed the capacity of your system’s maximum RAM.

a single MongoDB instance cannot meet the demands of your write operations, and all other approaches have not reduced contention.

If these attributes are not present in your system, sharding will only add complexity to your system without adding much benefit.

Important

It takes time and resources to deploy sharding. If your system has already reached or exceeded its capacity, it will be difficult to deploy sharding without impacting your application.

As a result, if you think you will need to partition your database in the future, do not wait until your system is over capacity to enable sharding.

When designing your data model, take into consideration your sharding needs.

Data Quantity Requirements

Your cluster should manage a large quantity of data if sharding is to have an effect. The default chunk size is 64 megabytes. And the balancer will not begin moving data across shards until the imbalance of chunks among the shards exceeds the migration threshold. In practical terms, unless your cluster has many hundreds of megabytes of data, your data will remain on a single shard.

In some situations, you may need to shard a small collection of data. But most of the time, sharding a small collection is not worth the added complexity and overhead unless you need additional write capacity. If you have a small data set, a properly configured single MongoDB instance or a replica set will usually be enough for your persistence layer needs.

Chunk size is user configurable. For most deployments, the default value is of 64 megabytes is ideal. See Chunk Size for more information.

Production Cluster Architecture

In a production cluster, you must ensure that data is redundant and that your systems are highly available. To that end, a production cluster must have the following components:

Components

Config Servers

Three config servers. Each config server must be on separate machines. A single sharded cluster must have exclusive use of its config servers. If you have multiple sharded clusters, you will need to have a group of config servers for each cluster.

Shards

Two or more replica sets. These replica sets are the shards. For information on replica sets, see Replication.

Query Routers (mongos)

One or more mongos instances. The mongos instances are the routers for the cluster. Typically, deployments have one mongos instance on each application server.

You may also deploy a group of mongos instances and use a proxy/load balancer between the application and the mongos. In these deployments, you must configure the load balancer for client affinity so that every connection from a single client reaches the same mongos.

Because cursors and other resources are specific to an single mongos instance, each client must interact with only one mongos instance.

Example

Sharded Cluster Test Architecture

Warning

Use the test cluster architecture for testing and development only.

For testing and development, you can deploy a minimal sharded clusters cluster. These non-production clusters have the following components:

One config server.

At least one shard. Shards are either replica sets or a standalone mongod instances.

One mongos instance.

See

Production Cluster Architecture

Sharded Cluster Behavior

These documents address the distribution of data and queries to a sharded cluster as well as specific security and availability considerations for sharded clusters.

Shard Keys

MongoDB uses the shard key to divide a collection’s data across the cluster’s shards.

Sharded Cluster High Availability

Sharded clusters provide ways to address some availability concerns.

Sharded Cluster Query Routing

The cluster’s routers, or mongos instances, send reads and writes to the relevant shard or shards.

Shard Keys

Sharded Cluster High Availability

Sharded Cluster Query Routing

Shard Keys

The shard key determines the distribution of the collection’s documents among the cluster’s shards. The shard key is either an indexed field or an indexed compound field that exists in every document in the collection.

MongoDB partitions data in the collection using ranges of shard key values. Each range, or chunk, defines a non-overlapping range of shard key values. MongoDB distributes the chunks, and their documents, among the shards in the cluster.

When a chunk grows beyond the chunk size, MongoDB attempts to split the chunk into smaller chunks, always based on ranges in the shard key.

Considerations

Shard keys are immutable and cannot be changed after insertion. See the system limits for sharded cluster for more information.

The index on the shard key cannot be a multikey index.

Hashed Shard Keys

New in version 2.4.

Hashed shard keys use a hashed index of a single field as the shard key to partition data across your sharded cluster.

The field you choose as your hashed shard key should have a good cardinality, or large number of different values. Hashed keys work well with fields that increase monotonically like ObjectId values or timestamps.

If you shard an empty collection using a hashed shard key, MongoDB will automatically create and migrate chunks so that each shard has two chunks. You can control how many chunks MongoDB will create with the numInitialChunks parameter to shardCollection or by manually creating chunks on the empty collection using the split command.

To shard a collection using a hashed shard key, see Shard a Collection Using a Hashed Shard Key.

Tip

MongoDB automatically computes the hashes when resolving queries using hashed indexes. Applications do not need to compute hashes.

Impacts of Shard Keys on Cluster Operations

The shard key affects write and query performance by determining how the MongoDB partitions data in the cluster and how effectively the mongos instances can direct operations to the cluster. Consider the following operational impacts of shard key selection:

Write Scaling

Some possible shard keys will allow your application to take advantage of the increased write capacity that the cluster can provide, while others do not. Consider the following example where you shard by the values of the default _id field, which is ObjectId.

MongoDB generates ObjectId values upon document creation to produce a unique identifier for the object. However, the most significant bits of data in this value represent a time stamp, which means that they increment in a regular and predictable pattern. Even though this value has high cardinality, when using this, any date, or other monotonically increasing number as the shard key, all insert operations will be storing data into a single chunk, and therefore, a single shard. As a result, the write capacity of this shard will define the effective write capacity of the cluster.

A shard key that increases monotonically will not hinder performance if you have a very low insert rate, or if most of your write operations are update() operations distributed through your entire data set. Generally, choose shard keys that have both high cardinality and will distribute write operations across the entire cluster.

Typically, a computed shard key that has some amount of “randomness,” such as ones that include a cryptographic hash (i.e. MD5 or SHA1) of other content in the document, will allow the cluster to scale write operations. However, random shard keys do not typically provide query isolation, which is another important characteristic of shard keys.

New in version 2.4: MongoDB makes it possible to shard a collection on a hashed index. This can greatly improve write scaling. See Shard a Collection Using a Hashed Shard Key.

Querying

The mongos provides an interface for applications to interact with sharded clusters that hides the complexity of data partitioning. A mongos receives queries from applications, and uses metadata from the config server, to route queries to the mongod instances with the appropriate data. While the mongos succeeds in making all querying operational in sharded environments, the shard key you select can have a profound affect on query performance.

See also

The Sharded Cluster Query Routing and config server sections for a more general overview of querying in sharded environments.

Query Isolation

Generally, the fastest queries in a sharded environment are those that mongos will route to a single shard, using the shard key and the cluster meta data from the config server. For queries that don’t include the shard key, mongos must query all shards, wait for their responses and then return the result to the application. These “scatter/gather” queries can be long running operations.

If your query includes the first component of a compound shard key [1], the mongos can route the query directly to a single shard, or a small number of shards, which provides better performance. Even if you query values of the shard key that reside in different chunks, the mongos will route queries directly to specific shards.

To select a shard key for a collection:

determine the most commonly included fields in queries for a given application

find which of these operations are most performance dependent.

If this field has low cardinality (i.e not sufficiently selective) you should add a second field to the shard key making a compound shard key. The data may become more splittable with a compound shard key.

See

Sharded Cluster Query Routing for more information on query operations in the context of sharded clusters.

[1]
In many ways, you can think of the shard key a cluster-wide index. However, be aware that sharded systems cannot enforce cluster-wide unique indexes unless the unique field is in the shard key. Consider the Index Concepts page for more information on indexes and compound indexes.

Sorting

In sharded systems, the mongos performs a merge-sort of all sorted query results from the shards. See Sharded Cluster Query Routing and Use Indexes to Sort Query Results for more information.

Indivisible Chunks

An insufficiently granular shard key can result in chunks that are “unsplittable”. See Create a Shard Key that is Easily Divisible for more information.

Additional Information

Considerations for Selecting Shard Keys

Shard a Collection Using a Hashed Shard Key.

Sharded Cluster High Availability

A production cluster has no single point of failure. This section introduces the availability concerns for MongoDB deployments in general and highlights potential failure scenarios and available resolutions.

Application Servers or mongos Instances Become Unavailable

If each application server has its own mongos instance, other application servers can continue access the database. Furthermore, mongos instances do not maintain persistent state, and they can restart and become unavailable without losing any state or data. When a mongos instance starts, it retrieves a copy of the config database and can begin routing queries.

A Single mongod Becomes Unavailable in a Shard

Replica sets provide high availability for shards. If the unavailable mongod is a primary, then the replica set will elect a new primary. If the unavailable mongod is a secondary, and it disconnects the primary and secondary will continue to hold all data. In a three member replica set, even if a single member of the set experiences catastrophic failure, two other members have full copies of the data. [1]

Always investigate availability interruptions and failures. If a system is unrecoverable, replace it and create a new member of the replica set as soon as possible to replace the lost redundancy.

All Members of a Replica Set Become Unavailable

If all members of a replica set within a shard are unavailable, all data held in that shard is unavailable. However, the data on all other shards will remain available, and it’s possible to read and write data to the other shards. However, your application must be able to deal with partial results, and you should investigate the cause of the interruption and attempt to recover the shard as soon as possible.

One or Two Config Databases Become Unavailable

Three distinct mongod instances provide the config database using a special two-phase commits to maintain consistent state between these mongod instances. Cluster operation will continue as normal but chunk migration and the cluster can create no new chunk splits. Replace the config server as soon as possible. If all config databases become unavailable, the cluster can become inoperable.

Note

All config servers must be running and available when you first initiate a sharded cluster.

[1]
If an unavailable secondary becomes available while it still has current oplog entries, it can catch up to the latest state of the set using the normal replication process, otherwise it must perform an initial sync.

Renaming Config Servers and Cluster Availability

If the name or address that a sharded cluster uses to connect to a config server changes, you must restart every mongod and mongos instance in the sharded cluster. Avoid downtime by using CNAMEs to identify config servers within the MongoDB deployment.

To avoid downtime when renaming config servers, use DNS names unrelated to physical or virtual hostnames to refer to your config servers.

Generally, refer to each config server using the DNS alias (e.g. a CNAME record). When specifying the config server connection string to mongos, use these names. These records make it possible to change the IP address or rename config servers without changing the connection string and without having to restart the entire cluster.

Shard Keys and Cluster Availability

The most important consideration when choosing a shard key are:

to ensure that MongoDB will be able to distribute data evenly among shards, and

to scale writes across the cluster, and

to ensure that mongos can isolate most queries to a specific mongod.

Furthermore:

Each shard should be a replica set, if a specific mongod instance fails, the replica set members will elect another to be primary and continue operation. However, if an entire shard is unreachable or fails for some reason, that data will be unavailable.

If the shard key allows the mongos to isolate most operations to a single shard, then the failure of a single shard will only render some data unavailable.

If your shard key distributes data required for every operation throughout the cluster, then the failure of the entire shard will render the entire cluster unavailable.

In essence, this concern for reliability simply underscores the importance of choosing a shard key that isolates query operations to a single shard.

Sharded Cluster Query Routing

MongoDB mongos instances route queries and write operations to shards in a sharded cluster. mongos provide the only interface to a sharded cluster from the perspective of applications. Applications never connect or communicate directly with the shards.

The mongos tracks what data is on which shard by caching the metadata from the config servers. The mongos uses the metadata to route operations from applications and clients to the mongod instances. A mongos has no persistent state and consumes minimal system resources.

The most common practice is to run mongos instances on the same systems as your application servers, but you can maintain mongos instances on the shards or on other dedicated resources.

Note

Changed in version 2.1.

Some aggregation operations using the aggregate command (i.e. db.collection.aggregate()) will cause mongos instances to require more CPU resources than in previous versions. This modified performance profile may dictate alternate architecture decisions if you use the aggregation framework extensively in a sharded environment.

Routing Process

A mongos instance uses the following processes to route queries and return results.

How mongos Determines which Shards Receive a Query

A mongos instance routes a query to a cluster by:

Determining the list of shards that must receive the query.

Establishing a cursor on all targeted shards.

In some cases, when the shard key or a prefix of the shard key is a part of the query, the mongos can route the query to a subset of the shards. Otherwise, the mongos must direct the query to all shards that hold documents for that collection.

Example

Given the following shard key:

{ zipcode: 1, u_id: 1, c_date: 1 }

Depending on the distribution of chunks in the cluster, the mongos may be able to target the query at a subset of shards, if the query contains the following fields:

{ zipcode: 1 }
{ zipcode: 1, u_id: 1 }
{ zipcode: 1, u_id: 1, c_date: 1 }

How mongos Handles Query Modifiers

If the result of the query is not sorted, the mongos instance opens a result cursor that “round robins” results from all cursors on the shards.

Changed in version 2.0.5: In versions prior to 2.0.5, the mongos exhausted each cursor, one by one.

If the query specifies sorted results using the sort() cursor method, the mongos instance passes the $orderby option to the shards. The primary shard for the database receives and performs a merge sort for all results before returning the data to the client via the mongos.

If the query limits the size of the result set using the limit() cursor method, the mongos instance passes that limit to the shards and then re-applies the limit to the result before returning the result to the client.

If the query specifies a number of records to skip using the skip() cursor method, the mongos cannot pass the skip to the shards, but rather retrieves unskipped results from the shards and skips the appropriate number of documents when assembling the complete result. However, when used in conjunction with a limit(), the mongos will pass the limit plus the value of the skip() to the shards to improve the efficiency of these operations.

Detect Connections to mongos Instances

To detect if the MongoDB instance that your client is connected to is mongos, use the isMaster command. When a client connects to a mongos, isMaster returns a document with a msg field that holds the string isdbgrid. For example:

{
   "ismaster" : true,
   "msg" : "isdbgrid",
   "maxBsonObjectSize" : 16777216,
   "ok" : 1
}

If the application is instead connected to a mongod, the returned document does not include the isdbgrid string.

Broadcast Operations and Targeted Operations

In general, operations in a sharded environment are either:

Broadcast to all shards in the cluster that hold documents in a collection

Targeted at a single shard or a limited group of shards, based on the shard key

For best performance, use targeted operations whenever possible. While some operations must broadcast to all shards, you can ensure MongoDB uses targeted operations whenever possible by always including the shard key.

Broadcast Operations

mongos instances broadcast queries to all shards for the collection unless the mongos can determine which shard or subset of shards stores this data.

Multi-update operations are always broadcast operations.

The remove() operation is always a broadcast operation, unless the operation specifies the shard key in full.

Targeted Operations

All insert() operations target to one shard.

All single update() (including upsert operations) and remove() operations must target to one shard.

Important

All update() and remove() operations for a sharded collection that specify the justOne or multi: false option must include the shard key or the _id field in the query specification. update() and remove() operations specifying justOne or multi: false in a sharded collection without the shard key or the _id field return an error.

For queries that include the shard key or portion of the shard key, mongos can target the query at a specific shard or set of shards. This is the case only if the portion of the shard key included in the query is a prefix of the shard key. For example, if the shard key is:

{ a: 1, b: 1, c: 1 }

The mongos program can route queries that include the full shard key or either of the following shard key prefixes at a specific shard or set of shards:

{ a: 1 }
{ a: 1, b: 1 }

Depending on the distribution of data in the cluster and the selectivity of the query, mongos may still have to contact multiple shards [1] to fulfill these queries.

[1]
mongos will route some queries, even some that include the shard key, to all shards, if needed.

Sharded and Non-Sharded Data

Sharding operates on the collection level. You can shard multiple collections within a database or have multiple databases with sharding enabled. [2] However, in production deployments, some databases and collections will use sharding, while other databases and collections will only reside on a single shard.

Regardless of the data architecture of your sharded cluster, ensure that all queries and operations use the mongos router to access the data cluster. Use the mongos even for operations that do not impact the sharded data.

[2]
As you configure sharding, you will use the enableSharding command to enable sharding for a database. This simply makes it possible to use the shardCollection command on a collection within that database.

Sharding Mechanics

The following documents describe sharded cluster processes.

Sharded Collection Balancing

Balancing distributes a sharded collection’s data cluster to all of the shards.

Chunk Migration Across Shards

MongoDB migrates chunks to shards as part of the balancing process.

Chunk Splits in a Sharded Cluster

When a chunk grows beyond the configured size, MongoDB splits the chunk in half.

Shard Key Indexes

Sharded collections must keep an index that starts with the shard key.

Sharded Cluster Metadata

The cluster maintains internal metadata that reflects the location of data within the cluster.

Sharded Collection Balancing

Chunk Migration Across Shards

Chunk Splits in a Sharded Cluster

Shard Key Indexes

Sharded Cluster Metadata

Sharded Collection Balancing

Balancing is the process MongoDB uses to distribute data of a sharded collection evenly across a sharded cluster. When a shard has too many of a sharded collection’s chunks compared to other shards, MongoDB automatically balances the chunks across the shards. The balancing procedure for sharded clusters is entirely transparent to the user and application layer.

Cluster Balancer

The balancer process is responsible for redistributing the chunks of a sharded collection evenly among the shards for every sharded collection. By default, the balancer process is always enabled.

Any mongos instance in the cluster can start a balancing round. When a balancer process is active, the responsible mongos acquires a “lock” by modifying a document in the lock collection in the Config Database.

Note

Changed in version 2.0: Before MongoDB version 2.0, large differences in timekeeping (i.e. clock skew) between mongos instances could lead to failed distributed locks. This carries the possibility of data loss, particularly with skews larger than 5 minutes. Always use the network time protocol (NTP) by running ntpd on your servers to minimize clock skew.

To address uneven chunk distribution for a sharded collection, the balancer migrates chunks from shards with more chunks to shards with a fewer number of chunks. The balancer migrates the chunks, one at a time, until there is an even dispersion of chunks for the collection across the shards.

Chunk migrations carry some overhead in terms of bandwidth and workload, both of which can impact database performance. The balancer attempts to minimize the impact by:

Moving only one chunk at a time. See also Chunk Migration Queuing.

Starting a balancing round only when the difference in the number of chunks between the shard with the greatest number of chunks for a sharded collection and the shard with the lowest number of chunks for that collection reaches the migration threshold.

You may disable the balancer temporarily for maintenance. See Disable the Balancer for details.

You can also limit the window during which the balancer runs to prevent it from impacting production traffic. See Schedule the Balancing Window for details.

Note

The specification of the balancing window is relative to the local time zone of all individual mongos instances in the cluster.

See also

Manage Sharded Cluster Balancer.

Migration Thresholds

To minimize the impact of balancing on the cluster, the balancer will not begin balancing until the distribution of chunks for a sharded collection has reached certain thresholds. The thresholds apply to the difference in number of chunks between the shard with the most chunks for the collection and the shard with the fewest chunks for that collection. The balancer has the following thresholds:

Changed in version 2.2: The following thresholds appear first in 2.2. Prior to this release, a balancing round would only start if the shard with the most chunks had 8 more chunks than the shard with the least number of chunks.

Number of Chunks | Migration Threshold
Fewer than 20 | 2
20-79 | 4
80 and greater | 8

Once a balancing round starts, the balancer will not stop until, for the collection, the difference between the number of chunks on any two shards for that collection is less than two or a chunk migration fails.

Shard Size

By default, MongoDB will attempt to fill all available disk space with data on every shard as the data set grows. To ensure that the cluster always has the capacity to handle data growth, monitor disk usage as well as other performance metrics.

When adding a shard, you may set a “maximum size” for that shard. This prevents the balancer from migrating chunks to the shard when the value of mapped exceeds the “maximum size”. Use the maxSize parameter of the addShard command to set the “maximum size” for the shard.

See also

Change the Maximum Storage Size for a Given Shard and Monitoring for MongoDB.

Chunk Migration Across Shards

Chunk migration moves the chunks of a sharded collection from one shard to another and is part of the balancer process.

Chunk Migration

MongoDB migrates chunks in a sharded cluster to distribute the chunks of a sharded collection evenly among shards. Migrations may be either:

Manual. Only use manual migration in limited cases, such as to distribute data during bulk inserts. See Migrating Chunks Manually for more details.

Automatic. The balancer process automatically migrates chunks when there is an uneven distribution of a sharded collection’s chunks across the shards. See Migration Thresholds for more details.

All chunk migrations use the following procedure:

The balancer process sends the moveChunk command to the source shard.

The source starts the move with an internal moveChunk command. During the migration process, operations to the chunk route to the source shard. The source shard is responsible for incoming write operations for the chunk.

The destination shard builds any indexes required by the source that do not exist on the destination.

The destination shard begins requesting documents in the chunk and starts receiving copies of the data.

After receiving the final document in the chunk, the destination shard starts a synchronization process to ensure that it has the changes to the migrated documents that occurred during the migration.

When fully synchronized, the destination shard connects to the config database and updates the cluster metadata with the new location for the chunk.

After the destination shard completes the update of the metadata, and once there are no open cursors on the chunk, the source shard deletes its copy of the documents.

Changed in version 2.4: If the balancer needs to perform additional chunk migrations from the source shard, the balancer can start the next chunk migration without waiting for the current migration process to finish this deletion step. See:ref:chunk-migration-queuing.

The migration process ensures consistency and maximizes the availability of chunks during balancing.

Chunk Migration Queuing

Changed in version 2.4.

To migrate multiple chunks from a shard, the balancer migrates the chunks one at a time. However, the balancer does not wait for the current migration’s delete phase to complete before starting the next chunk migration. See Chunk Migration for the chunk migration process and the delete phase.

This queuing behavior allows shards to unload chunks more quickly in cases of heavily imbalanced cluster, such as when performing initial data loads without pre-splitting and when adding new shards.

This behavior also affect the moveChunk command, and migration scripts that use the moveChunk command may proceed more quickly.

In some cases, the delete phases may persist longer. If multiple delete phases are queued but not yet complete, a crash of the replica set’s primary can orphan data from multiple migrations.

Chunk Migration and Replication

By default, each document operation during chunk migration propagates to at least one secondary before the balancer proceeds with the next document.

To override this behavior and allow the balancer to continue without waiting for replication to a secondary, set the _secondaryThrottle parameter to false. See Change Replication Behavior for Chunk Migration (Secondary Throttle) to update the _secondaryThrottle parameter for the balancer.

When called directly, moveChunk does not require that operations propagate to shards during operation: its secondaryThrottle defaults to false.

Independent of the secondaryThrottle setting, certain phases of the chunk migration have the following replication policy:

MongoDB briefly pauses all application writes to the source shard before updating the config servers with the new location for the chunk, and resumes the application writes after the update. The chunk move requires all writes to be acknowledged by majority of the members of the replica set both before and after committing the chunk move to config servers.

When an outgoing chunk migration finishes and cleanup occurs, all writes must be replicated to a majority of servers before further cleanup (from other outgoing migrations) or new incoming migrations can proceed.

Changed in version 2.4: In previous versions, the balancer did not wait for the document move to replicate to a secondary. For details, see Secondary Throttle in the v2.2 Manual [http://docs.mongodb.org/v2.2/tutorial/configure-sharded-cluster-balancer/#sharded-cluster-config-secondary-throttle]

Jumbo Chunks

During chunk migration, if the chunk exceeds the specified chunk size or if the number of documents in the chunk exceeds Maximum Number of Documents Per Chunk to Migrate, MongoDB does not migrate the chunk. Instead, MongoDB attempts to split the chunk. If the split is unsuccessful, MongoDB labels the chunk as jumbo to avoid repeated attempts to migrate the chunk.

Chunk Splits in a Sharded Cluster

As chunks grow beyond the specified chunk size a mongos instance will attempt to split the chunk in half. Splits may lead to an uneven distribution of the chunks for a collection across the shards. In such cases, the mongos instances will initiate a round of migrations to redistribute chunks across shards. See Sharded Collection Balancing for more details on balancing chunks across shards.

Chunk Size

The default chunk size in MongoDB is 64 megabytes. You can increase or reduce the chunk size, mindful of its effect on the cluster’s efficiency.

Small chunks lead to a more even distribution of data at the expense of more frequent migrations. This creates expense at the query routing (mongos) layer.

Large chunks lead to fewer migrations. This is more efficient both from the networking perspective and in terms of internal overhead at the query routing layer. But, these efficiencies come at the expense of a potentially more uneven distribution of data.

Chunk size affects the Maximum Number of Documents Per Chunk to Migrate.

For many deployments, it makes sense to avoid frequent and potentially spurious migrations at the expense of a slightly less evenly distributed data set.

Limitations

Changing the chunk size affects when chunks split but there are some limitations to its effects.

Automatic splitting only occurs during inserts or updates. If you lower the chunk size, it may take time for all chunks to split to the new size.

Splits cannot be “undone”. If you increase the chunk size, existing chunks must grow through inserts or updates until they reach the new size.

Note

Chunk ranges are inclusive of the lower boundary and exclusive of the upper boundary.

Indivisible Chunks

In some cases, chunks can grow beyond the specified chunk size but cannot undergo a split; e.g. if a chunk represents a single shard key value. See Considerations for Selecting Shard Keys for considerations for selecting a shard key.

Shard Key Indexes

All sharded collections must have an index that starts with the shard key. If you shard a collection without any documents and without such an index, the shardCollection command will create the index on the shard key. If the collection already has documents, you must create the index before using shardCollection.

Changed in version 2.2: The index on the shard key no longer needs to be only on the shard key. This index can be an index of the shard key itself, or a compound index where the shard key is a prefix of the index.

Important

The index on the shard key cannot be a multikey index.

A sharded collection named people has for its shard key the field zipcode. It currently has the index { zipcode: 1 }. You can replace this index with a compound index { zipcode: 1, username: 1 }, as follows:

Create an index on { zipcode: 1, username: 1 }:

db.people.ensureIndex( { zipcode: 1, username: 1 } );

When MongoDB finishes building the index, you can safely drop the existing index on { zipcode: 1 }:

db.people.dropIndex( { zipcode: 1 } );

Since the index on the shard key cannot be a multikey index, the index { zipcode: 1, username: 1 } can only replace the index { zipcode: 1 } if there are no array values for the username field.

If you drop the last valid index for the shard key, recover by recreating an index on just the shard key.

For restrictions on shard key indexes, see Shard Key Limitations.

Sharded Cluster Metadata

Config servers store the metadata for a sharded cluster. The metadata reflects state and organization of the sharded data sets and system. The metadata includes the list of chunks on every shard and the ranges that define the chunks. The mongos instances cache this data and use it to route read and write operations to shards.

Config servers store the metadata in the Config Database.

Important

Always back up the config database before doing any maintenance on the config server.

To access the config database, issue the following command from the mongo shell:

use config

In general, you should never edit the content of the config database directly. The config database contains the following collections:

changelog

chunks

collections

databases

lockpings

locks

mongos

settings

shards

version

For more information on these collections and their role in sharded clusters, see Config Database. See Read and Write Operations on Config Servers for more information about reads and updates to the metadata.

Sharded Cluster Tutorials

The following tutorials provide instructions for administering sharded clusters. For a higher-level overview, see Sharding.

Sharded Cluster Deployment Tutorials

Instructions for deploying sharded clusters, adding shards, selecting shard keys, and the initial configuration of sharded clusters.

Deploy a Sharded Cluster

Set up a sharded cluster by creating the needed data directories, starting the required MongoDB instances, and configuring the cluster settings.

Considerations for Selecting Shard Keys

Choose the field that MongoDB uses to parse a collection’s documents for distribution over the cluster’s shards. Each shard holds documents with values within a certain range.

Shard a Collection Using a Hashed Shard Key

Shard a collection based on hashes of a field’s values in order to ensure even distribution over the collection’s shards.

Add Shards to a Cluster

Add a shard to add capacity to a sharded cluster.

Continue reading from Sharded Cluster Deployment Tutorials for additional tutorials.

Sharded Cluster Maintenance Tutorials

Procedures and tasks for common operations on active sharded clusters.

View Cluster Configuration

View status information about the cluster’s databases, shards, and chunks.

Remove Shards from an Existing Sharded Cluster

Migrate a single shard’s data and remove the shard.

Migrate Config Servers with Different Hostnames

Migrate a config server to a new system that uses a new hostname. If possible, avoid changing the hostname and instead use the Migrate Config Servers with the Same Hostname procedure.

Manage Shard Tags

Use tags to associate specific ranges of shard key values with specific shards.

Continue reading from Sharded Cluster Maintenance Tutorials for additional tutorials.

Sharded Cluster Data Management

Practices that address common issues in managing large sharded data sets.

Troubleshoot Sharded Clusters

Presents solutions to common issues and concerns relevant to the administration and use of sharded clusters. Refer to FAQ: MongoDB Diagnostics for general diagnostic information.

Sharded Cluster Deployment Tutorials

Deploy a Sharded Cluster

Considerations for Selecting Shard Keys

Shard a Collection Using a Hashed Shard Key

Add Shards to a Cluster

Deploy Three Config Servers for Production Deployments

Convert a Replica Set to a Replicated Sharded Cluster

Convert Sharded Cluster to Replica Set

Sharded Cluster Maintenance Tutorials

View Cluster Configuration

Migrate Config Servers with the Same Hostname

Migrate Config Servers with Different Hostnames

Replace Disabled Config Server

Migrate a Sharded Cluster to Different Hardware

Backup Cluster Metadata

Configure Behavior of Balancer Process in Sharded Clusters

Manage Sharded Cluster Balancer

Remove Shards from an Existing Sharded Cluster

Sharded Cluster Data Management

Create Chunks in a Sharded Cluster

Split Chunks in a Sharded Cluster

Migrate Chunks in a Sharded Cluster

Merge Chunks in a Sharded Cluster

Modify Chunk Size in a Sharded Cluster

Clear jumbo Flag

Tag Aware Sharding

Manage Shard Tags

Enforce Unique Keys for Sharded Collections

Shard GridFS Data Store

Troubleshoot Sharded Clusters

Sharded Cluster Deployment Tutorials

The following tutorials provide information on deploying sharded clusters.

Deploy a Sharded Cluster

Set up a sharded cluster by creating the needed data directories, starting the required MongoDB instances, and configuring the cluster settings.

Considerations for Selecting Shard Keys

Choose the field that MongoDB uses to parse a collection’s documents for distribution over the cluster’s shards. Each shard holds documents with values within a certain range.

Shard a Collection Using a Hashed Shard Key

Shard a collection based on hashes of a field’s values in order to ensure even distribution over the collection’s shards.

Add Shards to a Cluster

Add a shard to add capacity to a sharded cluster.

Deploy Three Config Servers for Production Deployments

Convert a test deployment with one config server to a production deployment with three config servers.

Convert a Replica Set to a Replicated Sharded Cluster

Convert a replica set to a sharded cluster in which each shard is its own replica set.

Convert Sharded Cluster to Replica Set

Replace your sharded cluster with a single replica set.

See also

Enable Authentication in a Sharded Cluster

Deploy a Sharded Cluster

Considerations for Selecting Shard Keys

Shard a Collection Using a Hashed Shard Key

Add Shards to a Cluster

Deploy Three Config Servers for Production Deployments

Convert a Replica Set to a Replicated Sharded Cluster

Convert Sharded Cluster to Replica Set

Deploy a Sharded Cluster

Use the following sequence of tasks to deploy a sharded cluster:

Warning

Sharding and “localhost” Addresses

If you use either “localhost” or 127.0.0.1 as the hostname portion of any host identifier, for example as the host argument to addShard or the value to the --configdb run time option, then you must use “localhost” or 127.0.0.1 for all host settings for any MongoDB instances in the cluster. If you mix localhost addresses and remote host address, MongoDB will error.

Start the Config Server Database Instances

The config server processes are mongod instances that store the cluster’s metadata. You designate a mongod as a config server using the --configsvr option. Each config server stores a complete copy of the cluster’s metadata.

In production deployments, you must deploy exactly three config server instances, each running on different servers to assure good uptime and data safety. In test environments, you can run all three instances on a single server.

Important

All members of a sharded cluster must be able to connect to all other members of a sharded cluster, including all shards and all config servers. Ensure that the network and security systems including all interfaces and firewalls, allow these connections.

Create data directories for each of the three config server instances. By default, a config server stores its data files in the /data/configdb directory. You can choose a different location. To create a data directory, issue a command similar to the following:

mkdir /data/configdb

Start the three config server instances. Start each by issuing a command using the following syntax:

mongod --configsvr --dbpath <path> --port <port>

The default port for config servers is 27019. You can specify a different port. The following example starts a config server using the default port and default data directory:

mongod --configsvr --dbpath /data/configdb --port 27019

For additional command options, see mongod or Configuration File Options.

Note

All config servers must be running and available when you first initiate a sharded cluster.

Start the mongos Instances

The mongos instances are lightweight and do not require data directories. You can run a mongos instance on a system that runs other cluster components, such as on an application server or a server running a mongod process. By default, a mongos instance runs on port 27017.

When you start the mongos instance, specify the hostnames of the three config servers, either in the configuration file or as command line parameters.

Tip

To avoid downtime, give each config server a logical DNS name (unrelated to the server’s physical or virtual hostname). Without logical DNS names, moving or renaming a config server requires shutting down every mongod and mongos instance in the sharded cluster.

To start a mongos instance, issue a command using the following syntax:

mongos --configdb <config server hostnames>

For example, to start a mongos that connects to config server instance running on the following hosts and on the default ports:

cfg0.example.net

cfg1.example.net

cfg2.example.net

You would issue the following command:

mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019

Each mongos in a sharded cluster must use the same configDB string, with identical host names listed in identical order.

If you start a mongos instance with a string that does not exactly match the string used by the other mongos instances in the cluster, the mongos return a Config Database String Error error and refuse to start.

Add Shards to the Cluster

A shard can be a standalone mongod or a replica set. In a production environment, each shard should be a replica set. Use the procedure in Deploy a Replica Set to deploy replica sets for each shard.

From a mongo shell, connect to the mongos instance. Issue a command using the following syntax:

mongo --host <hostname of machine running mongos> --port <port mongos listens on>

For example, if a mongos is accessible at mongos0.example.net on port 27017, issue the following command:

mongo --host mongos0.example.net --port 27017

Add each shard to the cluster using the sh.addShard() method, as shown in the examples below. Issue sh.addShard() separately for each shard. If the shard is a replica set, specify the name of the replica set and specify a member of the set. In production deployments, all shards should be replica sets.

Optional

You can instead use the addShard database command, which lets you specify a name and maximum size for the shard. If you do not specify these, MongoDB automatically assigns a name and maximum size. To use the database command, see addShard.

The following are examples of adding a shard with sh.addShard():

To add a shard for a replica set named rs1 with a member running on port 27017 on mongodb0.example.net, issue the following command:

sh.addShard( "rs1/mongodb0.example.net:27017" )

Changed in version 2.0.3.

For MongoDB versions prior to 2.0.3, you must specify all members of the replica set. For example:

sh.addShard( "rs1/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" )

To add a shard for a standalone mongod on port 27017 of mongodb0.example.net, issue the following command:

sh.addShard( "mongodb0.example.net:27017" )

Note

It might take some time for chunks to migrate to the new shard.

Enable Sharding for a Database

Before you can shard a collection, you must enable sharding for the collection’s database. Enabling sharding for a database does not redistribute data but make it possible to shard the collections in that database.

Once you enable sharding for a database, MongoDB assigns a primary shard for that database where MongoDB stores all data before sharding begins.

From a mongo shell, connect to the mongos instance. Issue a command using the following syntax:

mongo --host <hostname of machine running mongos> --port <port mongos listens on>

Issue the sh.enableSharding() method, specifying the name of the database for which to enable sharding. Use the following syntax:

sh.enableSharding("<database>")

Optionally, you can enable sharding for a database using the enableSharding command, which uses the following syntax:

db.runCommand( { enableSharding: <database> } )

Enable Sharding for a Collection

You enable sharding on a per-collection basis.

Determine what you will use for the shard key. Your selection of the shard key affects the efficiency of sharding. See the selection considerations listed in the Considerations for Selecting Shard Key.

If the collection already contains data you must create an index on the shard key using ensureIndex(). If the collection is empty then MongoDB will create the index as part of the sh.shardCollection() step.

Enable sharding for a collection by issuing the sh.shardCollection() method in the mongo shell. The method uses the following syntax:

sh.shardCollection("<database>.<collection>", shard-key-pattern)

Replace the <database>.<collection> string with the full namespace of your database, which consists of the name of your database, a dot (e.g. .), and the full name of the collection. The shard-key-pattern represents your shard key, which you specify in the same form as you would an index key pattern.

Example

The following sequence of commands shards four collections:

sh.shardCollection("records.people", { "zipcode": 1, "name": 1 } )
sh.shardCollection("people.addresses", { "state": 1, "_id": 1 } )
sh.shardCollection("assets.chairs", { "type": 1, "_id": 1 } )
sh.shardCollection("events.alerts", { "_id": "hashed" } )

In order, these operations shard:

The people collection in the records database using the shard key { "zipcode": 1, "name": 1 }.

This shard key distributes documents by the value of the zipcode field. If a number of documents have the same value for this field, then that chunk will be splittable by the values of the name field.

The addresses collection in the people database using the shard key { "state": 1, "_id": 1 }.

This shard key distributes documents by the value of the state field. If a number of documents have the same value for this field, then that chunk will be splittable by the values of the _id field.

The chairs collection in the assets database using the shard key { "type": 1, "_id": 1 }.

This shard key distributes documents by the value of the type field. If a number of documents have the same value for this field, then that chunk will be splittable by the values of the _id field.

The alerts collection in the events database using the shard key { "_id": "hashed" }.

New in version 2.4.

This shard key distributes documents by a hash of the value of the _id field. MongoDB computes the hash of the _id field for the hashed index, which should provide an even distribution of documents across a cluster.

Considerations for Selecting Shard Keys

Choosing a Shard Key

For many collections there may be no single, naturally occurring key that possesses all the qualities of a good shard key. The following strategies may help construct a useful shard key from existing data:

Compute a more ideal shard key in your application layer, and store this in all of your documents, potentially in the _id field.

Use a compound shard key that uses two or three values from all documents that provide the right mix of cardinality with scalable write operations and query isolation.

Determine that the impact of using a less than ideal shard key is insignificant in your use case, given:

limited write volume,

expected data size, or

application query patterns.

New in version 2.4: Use a hashed shard key. Choose a field that has high cardinality and create a hashed index on that field. MongoDB uses these hashed index values as shard key values, which ensures an even distribution of documents across the shards.

Tip

MongoDB automatically computes the hashes when resolving queries using hashed indexes. Applications do not need to compute hashes.

Considerations for Selecting Shard Key

Choosing the correct shard key can have a great impact on the performance, capability, and functioning of your database and cluster. Appropriate shard key choice depends on the schema of your data and the way that your applications query and write data.

Create a Shard Key that is Easily Divisible

An easily divisible shard key makes it easy for MongoDB to distribute content among the shards. Shard keys that have a limited number of possible values can result in chunks that are “unsplittable”.

For instance, if a chunk represents a single shard key value, then MongoDB cannot split the chunk even when the chunk exceeds the size at which splits occur.

See also

Cardinality

Create a Shard Key that has High Degree of Randomness

A shard key with high degree of randomness prevents any single shard from becoming a bottleneck and will distribute write operations among the cluster.

See also

Write Scaling

Create a Shard Key that Targets a Single Shard

A shard key that targets a single shard makes it possible for the mongos program to return most query operations directly from a single specific mongod instance. Your shard key should be the primary field used by your queries. Fields with a high degree of “randomness” make it difficult to target operations to specific shards.

See also

Query Isolation

Shard Using a Compound Shard Key

The challenge when selecting a shard key is that there is not always an obvious choice. Often, an existing field in your collection may not be the optimal key. In those situations, computing a special purpose shard key into an additional field or using a compound shard key may help produce one that is more ideal.

Cardinality

Cardinality in the context of MongoDB, refers to the ability of the system to partition data into chunks. For example, consider a collection of data such as an “address book” that stores address records:

Consider the use of a state field as a shard key:

The state key’s value holds the US state for a given address document. This field has a low cardinality as all documents that have the same value in the state field must reside on the same shard, even if a particular state’s chunk exceeds the maximum chunk size.

Since there are a limited number of possible values for the state field, MongoDB may distribute data unevenly among a small number of fixed chunks. This may have a number of effects:

If MongoDB cannot split a chunk because all of its documents have the same shard key, migrations involving these un-splittable chunks will take longer than other migrations, and it will be more difficult for your data to stay balanced.

If you have a fixed maximum number of chunks, you will never be able to use more than that number of shards for this collection.

Consider the use of a zipcode field as a shard key:

While this field has a large number of possible values, and thus has potentially higher cardinality, it’s possible that a large number of users could have the same value for the shard key, which would make this chunk of users un-splittable.

In these cases, cardinality depends on the data. If your address book stores records for a geographically distributed contact list (e.g. “Dry cleaning businesses in America,”) then a value like zipcode would be sufficient. However, if your address book is more geographically concentrated (e.g “ice cream stores in Boston Massachusetts,”) then you may have a much lower cardinality.

Consider the use of a phone-number field as a shard key:

Phone number has a high cardinality, because users will generally have a unique value for this field, MongoDB will be able to split as many chunks as needed.

While “high cardinality,” is necessary for ensuring an even distribution of data, having a high cardinality does not guarantee sufficient query isolation or appropriate write scaling.

If you choose a shard key with low cardinality, some chunks may grow too large for MongoDB to migrate. See Jumbo Chunks for more information.

Shard Key Selection Strategy

When selecting a shard key, it is difficult to balance the qualities of an ideal shard key, which sometimes dictate opposing strategies. For instance, it’s difficult to produce a key that has both a high degree randomness for even data distribution and a shard key that allows your application to target specific shards. For some workloads, it’s more important to have an even data distribution, and for others targeted queries are essential.

Therefore, the selection of a shard key is about balancing both your data and the performance characteristics caused by different possible data distributions and system workloads.

Shard a Collection Using a Hashed Shard Key

New in version 2.4.

Hashed shard keys use a hashed index of a field as the shard key to partition data across your sharded cluster.

For suggestions on choosing the right field as your hashed shard key, see Hashed Shard Keys. For limitations on hashed indexes, see Create a Hashed Index.

Note

If chunk migrations are in progress while creating a hashed shard key collection, the initial chunk distribution may be uneven until the balancer automatically balances the collection.

Shard the Collection

To shard a collection using a hashed shard key, use an operation in the mongo that resembles the following:

sh.shardCollection( "records.active", { a: "hashed" } )

This operation shards the active collection in the records database, using a hash of the a field as the shard key.

Specify the Initial Number of Chunks

If you shard an empty collection using a hashed shard key, MongoDB automatically creates and migrates empty chunks so that each shard has two chunks. To control how many chunks MongoDB creates when sharding the collection, use shardCollection with the numInitialChunks parameter.

Important

MongoDB 2.4 adds support for hashed shard keys. After sharding a collection with a hashed shard key, you must use the MongoDB 2.4 or higher mongos and mongod instances in your sharded cluster.

Warning

MongoDB hashed indexes truncate floating point numbers to 64-bit integers before hashing. For example, a hashed index would store the same value for a field that held a value of 2.3, 2.2, and 2.9. To prevent collisions, do not use a hashed index for floating point numbers that cannot be reliably converted to 64-bit integers (and then back to floating point). MongoDB hashed indexes do not support floating point values larger than 2⁵³.

Add Shards to a Cluster

You add shards to a sharded cluster after you create the cluster or any time that you need to add capacity to the cluster. If you have not created a sharded cluster, see Deploy a Sharded Cluster.

In production environments, all shards should be replica sets.

Considerations

Balancing

When you add a shard to a sharded cluster, you affect the balance of chunks among the shards of a cluster for all existing sharded collections. The balancer will begin migrating chunks so that the cluster will achieve balance. See Sharded Collection Balancing for more information.

Capacity Planning

When adding a shard to a cluster, always ensure that the cluster has enough capacity to support the migration required for balancing the cluster without affecting legitimate production traffic.

Add a Shard to a Cluster

You interact with a sharded cluster by connecting to a mongos instance.

From a mongo shell, connect to the mongos instance. For example, if a mongos is accessible at mongos0.example.net on port 27017, issue the following command:

mongo --host mongos0.example.net --port 27017

Add a shard to the cluster using the sh.addShard() method, as shown in the examples below. Issue sh.addShard() separately for each shard. If the shard is a replica set, specify the name of the replica set and specify a member of the set. In production deployments, all shards should be replica sets.

Optional

You can instead use the addShard database command, which lets you specify a name and maximum size for the shard. If you do not specify these, MongoDB automatically assigns a name and maximum size. To use the database command, see addShard.

The following are examples of adding a shard with sh.addShard():

To add a shard for a replica set named rs1 with a member running on port 27017 on mongodb0.example.net, issue the following command:

sh.addShard( "rs1/mongodb0.example.net:27017" )

Changed in version 2.0.3.

For MongoDB versions prior to 2.0.3, you must specify all members of the replica set. For example:

sh.addShard( "rs1/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" )

To add a shard for a standalone mongod on port 27017 of mongodb0.example.net, issue the following command:

sh.addShard( "mongodb0.example.net:27017" )

Note

It might take some time for chunks to migrate to the new shard.

Deploy Three Config Servers for Production Deployments

This procedure converts a test deployment with only one config server to a production deployment with three config servers.

Tip

Use CNAMEs to identify your config servers to the cluster so that you can rename and renumber your config servers without downtime.

For redundancy, all production sharded clusters should deploy three config servers on three different machines. Use a single config server only for testing deployments, never for production deployments. When you shift to production, upgrade immediately to three config servers.

To convert a test deployment with one config server to a production deployment with three config servers:

Shut down all existing MongoDB processes in the cluster. This includes:

all mongod instances or replica sets that provide your shards.

all mongos instances in your cluster.

Copy the entire dbPath file system tree from the existing config server to the two machines that will provide the additional config servers. These commands, issued on the system with the existing Config Database, mongo-config0.example.net may resemble the following:

rsync -az /data/configdb mongo-config1.example.net:/data/configdb
rsync -az /data/configdb mongo-config2.example.net:/data/configdb

Start all three config servers, using the same invocation that you used for the single config server.

mongod --configsvr

Restart all shard mongod and mongos processes.

Convert a Replica Set to a Replicated Sharded Cluster

Overview

This tutorial converts a single three-member replica set to a sharded cluster with two shards. Each shard is an independent three-member replica set. The procedure is as follows:

Create the initial three-member replica set and insert data into a collection. See Set Up Initial Replica Set.

Start the config databases and a mongos. See Deploy Config Databases and mongos.

Add the initial replica set as a shard. See Add Initial Replica Set as a Shard.

Create a second shard and add to the cluster. See Add Second Shard.

Shard the desired collection. See Shard a Collection.

Prerequisites

This tutorial uses a total of ten servers: one server for the mongos and three servers each for the first replica set, the second replica set, and the config servers.

Each server must have a resolvable domain, hostname, or IP address within your system.

The tutorial uses the default data directories (e.g. /data/db and /data/configdb). Create the appropriate directories with appropriate permissions. To use different paths, see Configuration File Options .

The tutorial uses the default ports (e.g. 27017 and 27019). To use different ports, see Configuration File Options.

Considerations

In production deployments, use exactly three config servers. Each config server must be on a separate machine.

In development and testing environments, you can deploy a cluster with a single config server.

Procedures

Set Up Initial Replica Set

This procedure creates the initial three-member replica set rs0. The replica set members are on the following hosts: mongodb0.example.net, mongodb1.example.net, and mongodb2.example.net.

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod, specifying the replica set name through the replSet option. Include any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

mongod --replSet "rs0"

Repeat this step for the other two members of the rs0 replica set.

Step 1: Start each member of the replica set with the appropriate options.

For each member, start a mongod, specifying the replica set name through the replSet option. Include any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

mongod --replSet "rs0"

Repeat this step for the other two members of the rs0 replica set.

2

Connect a mongo shell to a replica set member.

Connect a mongo shell to one member of the replica set (e.g. mongodb0.example.net)

mongo mongodb0.example.net

Step 2: Connect a mongo shell to a replica set member.

Connect a mongo shell to one member of the replica set (e.g. mongodb0.example.net)

mongo mongodb0.example.net

3

Initiate the replica set.

From the mongo shell, run rs.initiate() to initiate a replica set that consists of the current member.

rs.initiate()

Step 3: Initiate the replica set.

From the mongo shell, run rs.initiate() to initiate a replica set that consists of the current member.

rs.initiate()

4

Add the remaining members to the replica set.

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

Step 4: Add the remaining members to the replica set.

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

5

Create and populate a new collection.

The following step adds one million documents to the collection test_collection and can take several minutes depending on your system.

Issue the following operations on the primary of the replica set:

use test
var bulk = db.test_collection.initializeUnorderedBulkOp();
people = ["Marc", "Bill", "George", "Eliot", "Matt", "Trey", "Tracy", "Greg", "Steve", "Kristina", "Katie", "Jeff"];
for(var i=0; i<1000000; i++){
   user_id = i;
   name = people[Math.floor(Math.random()*people.length)];
   number = Math.floor(Math.random()*10001);
   bulk.insert( { "user_id":user_id, "name":name, "number":number });
}
bulk.execute();

Step 5: Create and populate a new collection.

The following step adds one million documents to the collection test_collection and can take several minutes depending on your system.

Issue the following operations on the primary of the replica set:

use test
var bulk = db.test_collection.initializeUnorderedBulkOp();
people = ["Marc", "Bill", "George", "Eliot", "Matt", "Trey", "Tracy", "Greg", "Steve", "Kristina", "Katie", "Jeff"];
for(var i=0; i<1000000; i++){
   user_id = i;
   name = people[Math.floor(Math.random()*people.length)];
   number = Math.floor(Math.random()*10001);
   bulk.insert( { "user_id":user_id, "name":name, "number":number });
}
bulk.execute();

For more information on deploying a replica set, see Deploy a Replica Set.

Deploy Config Databases and mongos

This procedure deploys the three config servers and the mongos. The config servers use the following hosts: mongodb7.example.net, mongodb8.example.net, and mongodb9.example.net; the mongos uses mongodb6.example.net.

1

Start three config databases.

On each mongodb7.example.net, mongodb8.example.net, and mongodb9.example.net server, start the config server using default data directory /data/configdb and the default port 27019:

mongod --configsvr

To modify the default settings or to include additional options specific to your deployment, see Configuration File Options.

Step 1: Start three config databases.

On each mongodb7.example.net, mongodb8.example.net, and mongodb9.example.net server, start the config server using default data directory /data/configdb and the default port 27019:

mongod --configsvr

To modify the default settings or to include additional options specific to your deployment, see Configuration File Options.

2

Start a mongos instance.

On mongodb6.example.net, start the mongos specifying the config servers. The mongos runs on the default port 27017.

This tutorial specifies a small --chunkSize of 1 MB to test sharding with the test_collection created earlier.

Note

In production environments, do not use a small chunkSize size.

mongos --configdb mongodb07.example.net:27019,mongodb08.example.net:27019,mongodb09.example.net:27019 --chunkSize 1

Step 2: Start a mongos instance.

On mongodb6.example.net, start the mongos specifying the config servers. The mongos runs on the default port 27017.

This tutorial specifies a small --chunkSize of 1 MB to test sharding with the test_collection created earlier.

Note

In production environments, do not use a small chunkSize size.

mongos --configdb mongodb07.example.net:27019,mongodb08.example.net:27019,mongodb09.example.net:27019 --chunkSize 1

Add Initial Replica Set as a Shard

The following procedure adds the initial replica set rs0 as a shard.

1

Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

Step 1: Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

2

Add the shard.

Add a shard to the cluster with the sh.addShard method:

sh.addShard( "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" )

Step 2: Add the shard.

Add a shard to the cluster with the sh.addShard method:

sh.addShard( "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" )

Add Second Shard

The following procedure deploys a new replica set rs1 for the second shard and adds it to the cluster. The replica set members are on the following hosts: mongodb3.example.net, mongodb4.example.net, and mongodb5.example.net.

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod, specifying the replica set name through the replSet option. Include any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

mongod --replSet "rs1"

Repeat this step for the other two members of the rs1 replica set.

Step 1: Start each member of the replica set with the appropriate options.

For each member, start a mongod, specifying the replica set name through the replSet option. Include any other parameters specific to your deployment. For replication-specific parameters, see Replication Options.

mongod --replSet "rs1"

Repeat this step for the other two members of the rs1 replica set.

2

Connect a mongo shell to a replica set member.

Connect a mongo shell to one member of the replica set (e.g. mongodb3.example.net)

mongo mongodb3.example.net

Step 2: Connect a mongo shell to a replica set member.

Connect a mongo shell to one member of the replica set (e.g. mongodb3.example.net)

mongo mongodb3.example.net

3

Initiate the replica set.

From the mongo shell, run rs.initiate() to initiate a replica set that consists of the current member.

rs.initiate()

Step 3: Initiate the replica set.

From the mongo shell, run rs.initiate() to initiate a replica set that consists of the current member.

rs.initiate()

4

Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

rs.add("mongodb4.example.net")
rs.add("mongodb5.example.net")

Step 4: Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

rs.add("mongodb4.example.net")
rs.add("mongodb5.example.net")

5

Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

Step 5: Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

6

Add the shard.

In a mongo shell connected to the mongos, add the shard to the cluster with the sh.addShard() method:

sh.addShard( "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" )

Step 6: Add the shard.

In a mongo shell connected to the mongos, add the shard to the cluster with the sh.addShard() method:

sh.addShard( "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" )

Shard a Collection

1

Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

Step 1: Connect a mongo shell to the mongos.

mongo mongodb6.example.net:27017/admin

2

Enable sharding for a database.

Before you can shard a collection, you must first enable sharding for the collection’s database. Enabling sharding for a database does not redistribute data but makes it possible to shard the collections in that database.

The following operation enables sharding on the test database:

sh.enableSharding( "test" )

The operation returns the status of the operation:

{ "ok" : 1 }

Step 2: Enable sharding for a database.

Before you can shard a collection, you must first enable sharding for the collection’s database. Enabling sharding for a database does not redistribute data but makes it possible to shard the collections in that database.

The following operation enables sharding on the test database:

sh.enableSharding( "test" )

The operation returns the status of the operation:

{ "ok" : 1 }

3

Determine the shard key.

For the collection to shard, determine the shard key. The shard key determines how MongoDB distributes the documents between shards. Good shard keys:

have values that are evenly distributed among all documents,

group documents that are often accessed at the same time into contiguous chunks, and

allow for effective distribution of activity among shards.

Once you shard a collection with the specified shard key, you cannot change the shard key. For more information on shard keys, see Shard Keys and Considerations for Selecting Shard Keys.

This procedure will use the number field as the shard key for test_collection.

Step 3: Determine the shard key.

For the collection to shard, determine the shard key. The shard key determines how MongoDB distributes the documents between shards. Good shard keys:

have values that are evenly distributed among all documents,

group documents that are often accessed at the same time into contiguous chunks, and

allow for effective distribution of activity among shards.

Once you shard a collection with the specified shard key, you cannot change the shard key. For more information on shard keys, see Shard Keys and Considerations for Selecting Shard Keys.

This procedure will use the number field as the shard key for test_collection.

4

Create an index on the shard key.

Before sharding a non-empty collection, create an index on the shard key.

use test
db.test_collection.ensureIndex( { number : 1 } )

Step 4: Create an index on the shard key.

Before sharding a non-empty collection, create an index on the shard key.

use test
db.test_collection.ensureIndex( { number : 1 } )

5

Shard the collection.

In the test database, shard the test_collection, specifying number as the shard key.

use test
sh.shardCollection( "test.test_collection", { "number" : 1 } )

The method returns the status of the operation:

{ "collectionsharded" : "test.test_collection", "ok" : 1 }

The balancer will redistribute chunks of documents when it next runs. As clients insert additional documents into this collection, the mongos will route the documents between the shards.

Step 5: Shard the collection.

In the test database, shard the test_collection, specifying number as the shard key.

use test
sh.shardCollection( "test.test_collection", { "number" : 1 } )

The method returns the status of the operation:

{ "collectionsharded" : "test.test_collection", "ok" : 1 }

The balancer will redistribute chunks of documents when it next runs. As clients insert additional documents into this collection, the mongos will route the documents between the shards.

6

Confirm the shard is balancing.

To confirm balancing activity, run db.stats() or db.printShardingStatus() in the test database.

use test
db.stats()
db.printShardingStatus()

Example output of the db.stats():

{
  "raw" : {
      "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" : {
         "db" : "test",
         "collections" : 3,
         "objects" : 989316,
         "avgObjSize" : 111.99974123535857,
         "dataSize" : 110803136,
         "storageSize" : 174751744,
         "numExtents" : 14,
         "indexes" : 2,
         "indexSize" : 57370992,
         "fileSize" : 469762048,
         "nsSizeMB" : 16,
         "dataFileVersion" : {
            "major" : 4,
            "minor" : 5
         },
         "extentFreeList" : {
            "num" : 0,
            "totalSize" : 0
         },
         "ok" : 1
      },
      "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" : {
         "db" : "test",
         "collections" : 3,
         "objects" : 14697,
         "avgObjSize" : 111.98258147921345,
         "dataSize" : 1645808,
         "storageSize" : 2809856,
         "numExtents" : 7,
         "indexes" : 2,
         "indexSize" : 1169168,
         "fileSize" : 67108864,
         "nsSizeMB" : 16,
         "dataFileVersion" : {
            "major" : 4,
            "minor" : 5
         },
         "extentFreeList" : {
            "num" : 0,
            "totalSize" : 0
         },
         "ok" : 1
      }
  },
  "objects" : 1004013,
  "avgObjSize" : 111,
  "dataSize" : 112448944,
  "storageSize" : 177561600,
  "numExtents" : 21,
  "indexes" : 4,
  "indexSize" : 58540160,
  "fileSize" : 536870912,
  "extentFreeList" : {
      "num" : 0,
      "totalSize" : 0
  },
  "ok" : 1
}

Example output of the db.printShardingStatus():

--- Sharding Status ---
sharding version: {
   "_id" : 1,
   "version" : 4,
   "minCompatibleVersion" : 4,
   "currentVersion" : 5,
   "clusterId" : ObjectId("5446970c04ad5132c271597c")
}
shards:
   {  "_id" : "rs0",  "host" : "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" }
   {  "_id" : "rs1",  "host" : "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" }
databases:
   {  "_id" : "admin",  "partitioned" : false,  "primary" : "config" }
   {  "_id" : "test",  "partitioned" : true,  "primary" : "rs0" }

test.test_collection
      shard key: { "number" : 1 }
      chunks:
         rs1    5
         rs0    186
      too many chunks to print, use verbose if you want to force print

Run these commands for a second time to demonstrate that chunks are migrating from rs0 to rs1.

Step 6: Confirm the shard is balancing.

To confirm balancing activity, run db.stats() or db.printShardingStatus() in the test database.

use test
db.stats()
db.printShardingStatus()

Example output of the db.stats():

{
  "raw" : {
      "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" : {
         "db" : "test",
         "collections" : 3,
         "objects" : 989316,
         "avgObjSize" : 111.99974123535857,
         "dataSize" : 110803136,
         "storageSize" : 174751744,
         "numExtents" : 14,
         "indexes" : 2,
         "indexSize" : 57370992,
         "fileSize" : 469762048,
         "nsSizeMB" : 16,
         "dataFileVersion" : {
            "major" : 4,
            "minor" : 5
         },
         "extentFreeList" : {
            "num" : 0,
            "totalSize" : 0
         },
         "ok" : 1
      },
      "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" : {
         "db" : "test",
         "collections" : 3,
         "objects" : 14697,
         "avgObjSize" : 111.98258147921345,
         "dataSize" : 1645808,
         "storageSize" : 2809856,
         "numExtents" : 7,
         "indexes" : 2,
         "indexSize" : 1169168,
         "fileSize" : 67108864,
         "nsSizeMB" : 16,
         "dataFileVersion" : {
            "major" : 4,
            "minor" : 5
         },
         "extentFreeList" : {
            "num" : 0,
            "totalSize" : 0
         },
         "ok" : 1
      }
  },
  "objects" : 1004013,
  "avgObjSize" : 111,
  "dataSize" : 112448944,
  "storageSize" : 177561600,
  "numExtents" : 21,
  "indexes" : 4,
  "indexSize" : 58540160,
  "fileSize" : 536870912,
  "extentFreeList" : {
      "num" : 0,
      "totalSize" : 0
  },
  "ok" : 1
}

Example output of the db.printShardingStatus():

--- Sharding Status ---
sharding version: {
   "_id" : 1,
   "version" : 4,
   "minCompatibleVersion" : 4,
   "currentVersion" : 5,
   "clusterId" : ObjectId("5446970c04ad5132c271597c")
}
shards:
   {  "_id" : "rs0",  "host" : "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" }
   {  "_id" : "rs1",  "host" : "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" }
databases:
   {  "_id" : "admin",  "partitioned" : false,  "primary" : "config" }
   {  "_id" : "test",  "partitioned" : true,  "primary" : "rs0" }

test.test_collection
      shard key: { "number" : 1 }
      chunks:
         rs1    5
         rs0    186
      too many chunks to print, use verbose if you want to force print

Run these commands for a second time to demonstrate that chunks are migrating from rs0 to rs1.

Convert Sharded Cluster to Replica Set

This tutorial describes the process for converting a sharded cluster to a non-sharded replica set. To convert a replica set into a sharded cluster Convert a Replica Set to a Replicated Sharded Cluster. See the Sharding documentation for more information on sharded clusters.

Convert a Cluster with a Single Shard into a Replica Set

In the case of a sharded cluster with only one shard, that shard contains the full data set. Use the following procedure to convert that cluster into a non-sharded replica set:

Reconfigure the application to connect to the primary member of the replica set hosting the single shard that system will be the new replica set.

Optionally remove the --shardsrv option, if your mongod started with this option.

Tip

Changing the --shardsrv option will change the port that mongod listens for incoming connections on.

The single-shard cluster is now a non-sharded replica set that will accept read and write operations on the data set.

You may now decommission the remaining sharding infrastructure.

Convert a Sharded Cluster into a Replica Set

Use the following procedure to transition from a sharded cluster with more than one shard to an entirely new replica set.

With the sharded cluster running, deploy a new replica set in addition to your sharded cluster. The replica set must have sufficient capacity to hold all of the data files from all of the current shards combined. Do not configure the application to connect to the new replica set until the data transfer is complete.

Stop all writes to the sharded cluster. You may reconfigure your application or stop all mongos instances. If you stop all mongos instances, the applications will not be able to read from the database. If you stop all mongos instances, start a temporary mongos instance on that applications cannot access for the data migration procedure.

Use mongodump and mongorestore to migrate the data from the mongos instance to the new replica set.

Note

Not all collections on all databases are necessarily sharded. Do not solely migrate the sharded collections. Ensure that all databases and all collections migrate correctly.

Reconfigure the application to use the non-sharded replica set instead of the mongos instance.

The application will now use the un-sharded replica set for reads and writes. You may now decommission the remaining unused sharded cluster infrastructure.

Sharded Cluster Maintenance Tutorials

The following tutorials provide information in maintaining sharded clusters.

View Cluster Configuration

View status information about the cluster’s databases, shards, and chunks.

Migrate Config Servers with the Same Hostname

Migrate a config server to a new system while keeping the same hostname. This procedure requires changing the DNS entry to point to the new system.

Migrate Config Servers with Different Hostnames

Migrate a config server to a new system that uses a new hostname. If possible, avoid changing the hostname and instead use the Migrate Config Servers with the Same Hostname procedure.

Replace Disabled Config Server

Replaces a config server that has become inoperable. This procedure assumes that the hostname does not change.

Migrate a Sharded Cluster to Different Hardware

Migrate a sharded cluster to a different hardware system, for example, when moving a pre-production environment to production.

Backup Cluster Metadata

Create a backup of a sharded cluster’s metadata while keeping the cluster operational.

Configure Behavior of Balancer Process in Sharded Clusters

Manage the balancer’s behavior by scheduling a balancing window, changing size settings, or requiring replication before migration.

Manage Sharded Cluster Balancer

View balancer status and manage balancer behavior.

Remove Shards from an Existing Sharded Cluster

Migrate a single shard’s data and remove the shard.

View Cluster Configuration

Migrate Config Servers with the Same Hostname

Migrate Config Servers with Different Hostnames

Replace Disabled Config Server

Migrate a Sharded Cluster to Different Hardware

Backup Cluster Metadata

Configure Behavior of Balancer Process in Sharded Clusters

Manage Sharded Cluster Balancer

Remove Shards from an Existing Sharded Cluster

See also

Backup and Restore Sharded Clusters

View Cluster Configuration

List Databases with Sharding Enabled

To list the databases that have sharding enabled, query the databases collection in the Config Database. A database has sharding enabled if the value of the partitioned field is true. Connect to a mongos instance with a mongo shell, and run the following operation to get a full list of databases with sharding enabled:

use config
db.databases.find( { "partitioned": true } )

Example

You can use the following sequence of commands when to return a list of all databases in the cluster:

use config
db.databases.find()

If this returns the following result set:

{ "_id" : "admin", "partitioned" : false, "primary" : "config" }
{ "_id" : "animals", "partitioned" : true, "primary" : "m0.example.net:30001" }
{ "_id" : "farms", "partitioned" : false, "primary" : "m1.example2.net:27017" }

Then sharding is only enabled for the animals database.

List Shards

To list the current set of configured shards, use the listShards command, as follows:

use admin
db.runCommand( { listShards : 1 } )

View Cluster Details

To view cluster details, issue db.printShardingStatus() or sh.status(). Both methods return the same output.

Example

In the following example output from sh.status()

sharding version displays the version number of the shard metadata.

shards displays a list of the mongod instances used as shards in the cluster.

databases displays all databases in the cluster, including database that do not have sharding enabled.

The chunks information for the foo database displays how many chunks are on each shard and displays the range of each chunk.

--- Sharding Status ---
  sharding version: { "_id" : 1, "version" : 3 }
  shards:
    {  "_id" : "shard0000",  "host" : "m0.example.net:30001" }
    {  "_id" : "shard0001",  "host" : "m3.example2.net:50000" }
  databases:
    {  "_id" : "admin",  "partitioned" : false,  "primary" : "config" }
    {  "_id" : "contacts",  "partitioned" : true,  "primary" : "shard0000" }
        foo.contacts
            shard key: { "zip" : 1 }
            chunks:
                shard0001    2
                shard0002    3
                shard0000    2
            { "zip" : { "$minKey" : 1 } } -->> { "zip" : "56000" } on : shard0001 { "t" : 2, "i" : 0 }
            { "zip" : 56000 } -->> { "zip" : "56800" } on : shard0002 { "t" : 3, "i" : 4 }
            { "zip" : 56800 } -->> { "zip" : "57088" } on : shard0002 { "t" : 4, "i" : 2 }
            { "zip" : 57088 } -->> { "zip" : "57500" } on : shard0002 { "t" : 4, "i" : 3 }
            { "zip" : 57500 } -->> { "zip" : "58140" } on : shard0001 { "t" : 4, "i" : 0 }
            { "zip" : 58140 } -->> { "zip" : "59000" } on : shard0000 { "t" : 4, "i" : 1 }
            { "zip" : 59000 } -->> { "zip" : { "$maxKey" : 1 } } on : shard0000 { "t" : 3, "i" : 3 }
    {  "_id" : "test",  "partitioned" : false,  "primary" : "shard0000" }

Migrate Config Servers with the Same Hostname

This procedure migrates a config server in a sharded cluster to a new system that uses the same hostname.

To migrate all the config servers in a cluster, perform this procedure for each config server separately and migrate the config servers in reverse order from how they are listed in the mongos instances’ configDB string. Start with the last config server listed in the configDB string.

Shut down the config server.

This renders all config data for the sharded cluster “read only.”

Change the DNS entry that points to the system that provided the old config server, so that the same hostname points to the new system. How you do this depends on how you organize your DNS and hostname resolution services.

Copy the contents of dbPath from the old config server to the new config server.

For example, to copy the contents of dbPath to a machine named mongodb.config2.example.net, you might issue a command similar to the following:

rsync -az /data/configdb/ mongodb.config2.example.net:/data/configdb

Start the config server instance on the new system. The default invocation is:

mongod --configsvr

When you start the third config server, your cluster will become writable and it will be able to create new splits and migrate chunks as needed.

Migrate Config Servers with Different Hostnames

Overview

Sharded clusters use a group of three config servers to store cluster meta data, and all three config servers must be available to support cluster metadata changes that include chunk splits and migrations. If one of the config servers is unavailable or inoperable, you must replace it as soon as possible.

This procedure migrates a config server in a sharded cluster to a new server that uses a different hostname. Use this procedure only if the config server will not be accessible via the same hostname. If possible, avoid changing the hostname so that you can instead use the procedure to migrate a config server and use the same hostname.

Considerations

Changing a config server’s hostname requires downtime and requires restarting every process in the sharded cluster.

While migrating config servers, always make sure that all mongos instances have three config servers specified in the configDB setting at all times. Also ensure that you specify the config servers in the same order for each mongos instance’s configDB setting.

Procedure

Disable the cluster balancer process temporarily. See Disable the Balancer for more information.

Shut down the config server to migrate.

This renders all config data for the sharded cluster “read only.”

Copy the contents of dbPath from the old config server to the new config server. For example, to copy the contents of dbPath to a machine named mongodb.config2.example.net, use a command that resembles the following:

rsync -az /data/configdb mongodb.config2.example.net:/data/configdb

Start the config server instance on the new system. The default invocation is:

mongod --configsvr

Shut down all existing MongoDB processes. This includes:

the mongod instances for the shards.

the mongod instances for the existing config databases.

the mongos instances.

Restart all shard mongod instances.

Restart the mongod instances for the two existing non-migrated config servers.

Update the configDB setting for each mongos instances.

Restart the mongos instances.

Re-enable the balancer to allow the cluster to resume normal balancing operations. See the Disable the Balancer section for more information on managing the balancer process.

Replace Disabled Config Server

Overview

Sharded clusters use a group of three config servers to store cluster meta data, and all three config servers must be available to support cluster metadata changes that include chunk splits and migrations. If one of the config servers is unavailable or inoperable you must replace it as soon as possible.

This procedure replaces an inoperable config server in a sharded cluster. Use this procedure only to replace a config server that has become inoperable (e.g. hardware failure).

This process assumes that the hostname of the instance will not change. If you must change the hostname of the instance, use the procedure to migrate a config server and use a new hostname.

Considerations

In the course of this procedure never remove a config server from the configDB parameter on any of the mongos instances.

Procedure

1

Provision a new system, with the same IP address and hostname as the previous host.

You will have to ensure the new system has the same IP address and hostname as the system it’s replacing or you will need to modify the DNS records and wait for them to propagate.

Step 1: Provision a new system, with the same IP address and hostname as the previous host.

You will have to ensure the new system has the same IP address and hostname as the system it’s replacing or you will need to modify the DNS records and wait for them to propagate.

2

Shut down one of the remaining config servers.

Copy all of this host’s dbPath path from the current system to the system that will provide the new config server. This command, issued on the system with the data files, may resemble the following:

rsync -az /data/configdb mongodb.config2.example.net:/data/configdb

Step 2: Shut down one of the remaining config servers.

Copy all of this host’s dbPath path from the current system to the system that will provide the new config server. This command, issued on the system with the data files, may resemble the following:

rsync -az /data/configdb mongodb.config2.example.net:/data/configdb

3

If necessary, update DNS and/or networking.

Ensure the new config server is accessible by the same name as the previous config server.

Step 3: If necessary, update DNS and/or networking.

Ensure the new config server is accessible by the same name as the previous config server.

4

Start the new config server.

mongod --configsvr

Step 4: Start the new config server.

mongod --configsvr

Migrate a Sharded Cluster to Different Hardware

This procedure moves the components of the sharded cluster to a new hardware system without downtime for reads and writes.

Important

While the migration is in progress, do not attempt to change to the cluster metadata. Do not use any operation that modifies the cluster metadata in any way. For example, do not create or drop databases, create or drop collections, or use any sharding commands.

If your cluster includes a shard backed by a standalone mongod instance, consider converting the standalone to a replica set to simplify migration and to let you keep the cluster online during future maintenance. Migrating a shard as standalone is a multi-step process that may require downtime.

To migrate a cluster to new hardware, perform the following tasks.

Disable the Balancer

Disable the balancer to stop chunk migration and do not perform any metadata write operations until the process finishes. If a migration is in progress, the balancer will complete the in-progress migration before stopping.

To disable the balancer, connect to one of the cluster’s mongos instances and issue the following method:

sh.stopBalancer()

To check the balancer state, issue the sh.getBalancerState() method.

For more information, see Disable the Balancer.

Migrate Each Config Server Separately

Migrate each config server by starting with the last config server listed in the configDB string. Proceed in reverse order of the configDB string. Migrate and restart a config server before proceeding to the next. Do not rename a config server during this process.

Note

If the name or address that a sharded cluster uses to connect to a config server changes, you must restart every mongod and mongos instance in the sharded cluster. Avoid downtime by using CNAMEs to identify config servers within the MongoDB deployment.

See Migrate Config Servers with Different Hostnames for more information.

Important

Start with the last config server listed in configDB.

Shut down the config server.

This renders all config data for the sharded cluster “read only.”

Change the DNS entry that points to the system that provided the old config server, so that the same hostname points to the new system. How you do this depends on how you organize your DNS and hostname resolution services.

Copy the contents of dbPath from the old config server to the new config server.

For example, to copy the contents of dbPath to a machine named mongodb.config2.example.net, you might issue a command similar to the following:

rsync -az /data/configdb/ mongodb.config2.example.net:/data/configdb

Start the config server instance on the new system. The default invocation is:

mongod --configsvr

Restart the mongos Instances

If the configDB string will change as part of the migration, you must shut down all mongos instances before changing the configDB string. This avoids errors in the sharded cluster over configDB string conflicts.

If the configDB string will remain the same, you can migrate the mongos instances sequentially or all at once.

Shut down the mongos instances using the shutdown command. If the configDB string is changing, shut down all mongos instances.

If the hostname has changed for any of the config servers, update the configDB string for each mongos instance. The mongos instances must all use the same configDB string. The strings must list identical host names in identical order.

Tip

To avoid downtime, give each config server a logical DNS name (unrelated to the server’s physical or virtual hostname). Without logical DNS names, moving or renaming a config server requires shutting down every mongod and mongos instance in the sharded cluster.

Restart the mongos instances being sure to use the updated configDB string if hostnames have changed.

For more information, see Start the mongos Instances.

Migrate the Shards

Migrate the shards one at a time. For each shard, follow the appropriate procedure in this section.

Migrate a Replica Set Shard

To migrate a sharded cluster, migrate each member separately. First migrate the non-primary members, and then migrate the primary last.

If the replica set has two voting members, add an arbiter to the replica set to ensure the set keeps a majority of its votes available during the migration. You can remove the arbiter after completing the migration.

Migrate a Member of a Replica Set Shard

Shut down the mongod process. To ensure a clean shutdown, use the shutdown command.

Move the data directory (i.e., the dbPath) to the new machine.

Restart the mongod process at the new location.

Connect to the replica set’s current primary.

If the hostname of the member has changed, use rs.reconfig() to update the replica set configuration document with the new hostname.

For example, the following sequence of commands updates the hostname for the instance at position 2 in the members array:

cfg = rs.conf()
cfg.members[2].host = "pocatello.example.net:27017"
rs.reconfig(cfg)

For more information on updating the configuration document, see Examples.

To confirm the new configuration, issue rs.conf().

Wait for the member to recover. To check the member’s state, issue rs.status().

Migrate the Primary in a Replica Set Shard

While migrating the replica set’s primary, the set must elect a new primary. This failover process which renders the replica set unavailable to perform reads or accept writes for the duration of the election, which typically completes quickly. If possible, plan the migration during a maintenance window.

Step down the primary to allow the normal failover process. To step down the primary, connect to the primary and issue the either the replSetStepDown command or the rs.stepDown() method. The following example shows the rs.stepDown() method:

rs.stepDown()

Once the primary has stepped down and another member has become PRIMARY state. To migrate the stepped-down primary, follow the Migrate a Member of a Replica Set Shard procedure

You can check the output of rs.status() to confirm the change in status.

Migrate a Standalone Shard

The ideal procedure for migrating a standalone shard is to convert the standalone to a replica set and then use the procedure for migrating a replica set shard. In production clusters, all shards should be replica sets, which provides continued availability during maintenance windows.

Migrating a shard as standalone is a multi-step process during which part of the shard may be unavailable. If the shard is the primary shard for a database,the process includes the movePrimary command. While the movePrimary runs, you should stop modifying data in that database. To migrate the standalone shard, use the Remove Shards from an Existing Sharded Cluster procedure.

Re-Enable the Balancer

To complete the migration, re-enable the balancer to resume chunk migrations.

Connect to one of the cluster’s mongos instances and pass true to the sh.setBalancerState() method:

sh.setBalancerState(true)

To check the balancer state, issue the sh.getBalancerState() method.

For more information, see Enable the Balancer.

Backup Cluster Metadata

This procedure shuts down the mongod instance of a config server in order to create a backup of a sharded cluster’s metadata. The cluster’s config servers store all of the cluster’s metadata, most importantly the mapping from chunks to shards.

When you perform this procedure, the cluster remains operational [1].

Disable the cluster balancer process temporarily. See Disable the Balancer for more information.

Shut down one of the config databases.

Create a full copy of the data files (i.e. the path specified by the dbPath option for the config instance.)

Restart the original configuration server.

Re-enable the balancer to allow the cluster to resume normal balancing operations. See the Disable the Balancer section for more information on managing the balancer process.

See also

MongoDB Backup Methods.

[1]
While one of the three config servers is unavailable, the cluster cannot split any chunks nor can it migrate chunks between shards. Your application will be able to write data to the cluster. See Config Servers for more information.

Configure Behavior of Balancer Process in Sharded Clusters

The balancer is a process that runs on one of the mongos instances in a cluster and ensures that chunks are evenly distributed throughout a sharded cluster. In most deployments, the default balancer configuration is sufficient for normal operation. However, administrators might need to modify balancer behavior depending on application or operational requirements. If you encounter a situation where you need to modify the behavior of the balancer, use the procedures described in this document.

For conceptual information about the balancer, see Sharded Collection Balancing and Cluster Balancer.

Schedule a Window of Time for Balancing to Occur

You can schedule a window of time during which the balancer can migrate chunks, as described in the following procedures:

Schedule the Balancing Window

Remove a Balancing Window Schedule.

The mongos instances use their own local timezones when respecting balancer window.

Configure Default Chunk Size

The default chunk size for a sharded cluster is 64 megabytes. In most situations, the default size is appropriate for splitting and migrating chunks. For information on how chunk size affects deployments, see details, see Chunk Size.

Changing the default chunk size affects chunks that are processes during migrations and auto-splits but does not retroactively affect all chunks.

To configure default chunk size, see Modify Chunk Size in a Sharded Cluster.

Change the Maximum Storage Size for a Given Shard

The maxSize field in the shards collection in the config database sets the maximum size for a shard, allowing you to control whether the balancer will migrate chunks to a shard. If mapped size [1] is above a shard’s maxSize, the balancer will not move chunks to the shard. Also, the balancer will not move chunks off an overloaded shard. This must happen manually. The maxSize value only affects the balancer’s selection of destination shards.

By default, maxSize is not specified, allowing shards to consume the total amount of available space on their machines if necessary.

You can set maxSize both when adding a shard and once a shard is running.

To set maxSize when adding a shard, set the addShard command’s maxSize parameter to the maximum size in megabytes. For example, the following command run in the mongo shell adds a shard with a maximum size of 125 megabytes:

db.runCommand( { addshard : "example.net:34008", maxSize : 125 } )

To set maxSize on an existing shard, insert or update the maxSize field in the shards collection in the config database. Set the maxSize in megabytes.

Example

Assume you have the following shard without a maxSize field:

{ "_id" : "shard0000", "host" : "example.net:34001" }

Run the following sequence of commands in the mongo shell to insert a maxSize of 125 megabytes:

use config
db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 125 } } )

To later increase the maxSize setting to 250 megabytes, run the following:

use config
db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 250 } } )

[1]
This value includes the mapped size of all data files including the``local`` and admin databases. Account for this when setting maxSize.

Change Replication Behavior for Chunk Migration (Secondary Throttle)

The _secondaryThrottle parameter of the balancer and the moveChunk command affects the replication behavior during chunk migration. By default, _secondaryThrottle is true, which means each document move during chunk migration propagates to at least one secondary before the balancer proceeds with its next operation. For more information on the replication behavior during various steps of chunk migration, see Chunk Migration and Replication.

To change the balancer’s _secondaryThrottle value, connect to a mongos instance and directly update the _secondaryThrottle value in the settings collection of the config database. For example, from a mongo shell connected to a mongos, issue the following command:

use config
db.settings.update(
   { "_id" : "balancer" },
   { $set : { "_secondaryThrottle" : false } },
   { upsert : true }
)

The effects of changing the _secondaryThrottle value may not be immediate. To ensure an immediate effect, stop and restart the balancer to enable the selected value of _secondaryThrottle. See Manage Sharded Cluster Balancer for details.

Manage Sharded Cluster Balancer

This page describes common administrative procedures related to balancing. For an introduction to balancing, see Sharded Collection Balancing. For lower level information on balancing, see Cluster Balancer.

See also

Configure Behavior of Balancer Process in Sharded Clusters

Check the Balancer State

The following command checks if the balancer is enabled (i.e. that the balancer is allowed to run). The command does not check if the balancer is active (i.e. if it is actively balancing chunks).

To see if the balancer is enabled in your cluster, issue the following command, which returns a boolean:

sh.getBalancerState()

Check the Balancer Lock

To see if the balancer process is active in your cluster, do the following:

Connect to any mongos in the cluster using the mongo shell.

Issue the following command to switch to the Config Database:

use config

Use the following query to return the balancer lock:

db.locks.find( { _id : "balancer" } ).pretty()

When this command returns, you will see output like the following:

{   "_id" : "balancer",
"process" : "mongos0.example.net:1292810611:1804289383",
  "state" : 2,
     "ts" : ObjectId("4d0f872630c42d1978be8a2e"),
   "when" : "Mon Dec 20 2010 11:41:10 GMT-0500 (EST)",
    "who" : "mongos0.example.net:1292810611:1804289383:Balancer:846930886",
    "why" : "doing balance round" }

This output confirms that:

The balancer originates from the mongos running on the system with the hostname mongos0.example.net.

The value in the state field indicates that a mongos has the lock. For version 2.0 and later, the value of an active lock is 2; for earlier versions the value is 1.

Schedule the Balancing Window

In some situations, particularly when your data set grows slowly and a migration can impact performance, it’s useful to be able to ensure that the balancer is active only at certain times. Use the following procedure to specify a window during which the balancer will be able to migrate chunks:

Connect to any mongos in the cluster using the mongo shell.

Issue the following command to switch to the Config Database:

use config

Issue the following operation to ensure the balancer is not in the stopped state:

sh.setBalancerState( true )

The balancer will not activate if in the stopped state or outside the activeWindow timeframe.

Use an operation modeled on the following example update() operation to modify the balancer’s window:

db.settings.update({ _id : "balancer" }, { $set : { activeWindow : { start : "<start-time>", stop : "<stop-time>" } } }, true )

Replace <start-time> and <end-time> with time values using two digit hour and minute values (e.g HH:MM) that describe the beginning and end boundaries of the balancing window. These times will be evaluated relative to the time zone of each individual mongos instance in the sharded cluster. If your mongos instances are physically located in different time zones, use a common time zone (e.g. GMT) to ensure that the balancer window is interpreted correctly.

For instance, running the following will force the balancer to run between 11PM and 6AM local time only:

db.settings.update({ _id : "balancer" }, { $set : { activeWindow : { start : "23:00", stop : "6:00" } } }, true )

Note

The balancer window must be sufficient to complete the migration of all data inserted during the day.

As data insert rates can change based on activity and usage patterns, it is important to ensure that the balancing window you select will be sufficient to support the needs of your deployment.

Do not use the sh.startBalancer() method when you have set an activeWindow.

Remove a Balancing Window Schedule

If you have set the balancing window and wish to remove the schedule so that the balancer is always running, issue the following sequence of operations:

use config
db.settings.update({ _id : "balancer" }, { $unset : { activeWindow : true } })

Disable the Balancer

By default the balancer may run at any time and only moves chunks as needed. To disable the balancer for a short period of time and prevent all migration, use the following procedure:

Connect to any mongos in the cluster using the mongo shell.

Issue the following operation to disable the balancer:

sh.stopBalancer()

If a migration is in progress, the system will complete the in-progress migration before stopping.

To verify that the balancer will not start, issue the following command, which returns false if the balancer is disabled:

sh.getBalancerState()

Optionally, to verify no migrations are in progress after disabling, issue the following operation in the mongo shell:

use config
while( sh.isBalancerRunning() ) {
          print("waiting...");
          sleep(1000);
}

Note

To disable the balancer from a driver that does not have the sh.stopBalancer() or sh.setBalancerState() helpers, issue the following command from the config database:

db.settings.update( { _id: "balancer" }, { $set : { stopped: true } } , true )

Enable the Balancer

Use this procedure if you have disabled the balancer and are ready to re-enable it:

Connect to any mongos in the cluster using the mongo shell.

Issue one of the following operations to enable the balancer:

From the mongo shell, issue:

sh.setBalancerState(true)

From a driver that does not have the sh.startBalancer() helper, issue the following from the config database:

db.settings.update( { _id: "balancer" }, { $set : { stopped: false } } , true )

Disable Balancing During Backups

If MongoDB migrates a chunk during a backup, you can end with an inconsistent snapshot of your sharded cluster. Never run a backup while the balancer is active. To ensure that the balancer is inactive during your backup operation:

Set the balancing window so that the balancer is inactive during the backup. Ensure that the backup can complete while you have the balancer disabled.

manually disable the balancer for the duration of the backup procedure.

If you turn the balancer off while it is in the middle of a balancing round, the shut down is not instantaneous. The balancer completes the chunk move in-progress and then ceases all further balancing rounds.

Before starting a backup operation, confirm that the balancer is not active. You can use the following command to determine if the balancer is active:

!sh.getBalancerState() && !sh.isBalancerRunning()

When the backup procedure is complete you can reactivate the balancer process.

Disable Balancing on a Collection

You can disable balancing for a specific collection with the sh.disableBalancing() method. You may want to disable the balancer for a specific collection to support maintenance operations or atypical workloads, for example, during data ingestions or data exports.

When you disable balancing on a collection, MongoDB will not interrupt in progress migrations.

To disable balancing on a collection, connect to a mongos with the mongo shell and call the sh.disableBalancing() method.

For example:

sh.disableBalancing("students.grades")

The sh.disableBalancing() method accepts as its parameter the full namespace of the collection.

Enable Balancing on a Collection

You can enable balancing for a specific collection with the sh.enableBalancing() method.

When you enable balancing for a collection, MongoDB will not immediately begin balancing data. However, if the data in your sharded collection is not balanced, MongoDB will be able to begin distributing the data more evenly.

To enable balancing on a collection, connect to a mongos with the mongo shell and call the sh.enableBalancing() method.

For example:

sh.enableBalancing("students.grades")

The sh.enableBalancing() method accepts as its parameter the full namespace of the collection.

Confirm Balancing is Enabled or Disabled

To confirm whether balancing for a collection is enabled or disabled, query the collections collection in the config database for the collection namespace and check the noBalance field. For example:

db.getSiblingDB("config").collections.findOne({_id : "students.grades"}).noBalance;

This operation will return a null error, true, false, or no output:

A null error indicates the collection namespace is incorrect.

If the result is true, balancing is disabled.

If the result is false, balancing is enabled currently but has been disabled in the past for the collection. Balancing of this collection will begin the next time the balancer runs.

If the operation returns no output, balancing is enabled currently and has never been disabled in the past for this collection. Balancing of this collection will begin the next time the balancer runs.

Remove Shards from an Existing Sharded Cluster

To remove a shard you must ensure the shard’s data is migrated to the remaining shards in the cluster. This procedure describes how to safely migrate data and how to remove a shard.

This procedure describes how to safely remove a single shard. Do not use this procedure to migrate an entire cluster to new hardware. To migrate an entire shard to new hardware, migrate individual shards as if they were independent replica sets.

To remove a shard, first connect to one of the cluster’s mongos instances using mongo shell. Then use the sequence of tasks in this document to remove a shard from the cluster.

Ensure the Balancer Process is Enabled

To successfully migrate data from a shard, the balancer process must be enabled. Check the balancer state using the sh.getBalancerState() helper in the mongo shell. For more information, see the section on balancer operations.

Determine the Name of the Shard to Remove

To determine the name of the shard, connect to a mongos instance with the mongo shell and either:

Use the listShards command, as in the following:

db.adminCommand( { listShards: 1 } )

Run either the sh.status() or the db.printShardingStatus() method.

The shards._id field lists the name of each shard.

Remove Chunks from the Shard

From the admin database, run the removeShard command. This begins “draining” chunks from the shard you are removing to other shards in the cluster. For example, for a shard named mongodb0, run:

use admin
db.runCommand( { removeShard: "mongodb0" } )

This operation returns immediately, with the following response:

{
    "msg" : "draining started successfully",
    "state" : "started",
    "shard" : "mongodb0",
    "ok" : 1
}

Depending on your network capacity and the amount of data, this operation can take from a few minutes to several days to complete.

Check the Status of the Migration

To check the progress of the migration at any stage in the process, run removeShard from the admin database again. For example, for a shard named mongodb0, run:

use admin
db.runCommand( { removeShard: "mongodb0" } )

The command returns output similar to the following:

{
     "msg" : "draining ongoing",
    "state" : "ongoing",
    "remaining" : {
        "chunks" : 42,
        "dbs" : 1
    },
    "ok" : 1
}

In the output, the remaining document displays the remaining number of chunks that MongoDB must migrate to other shards and the number of MongoDB databases that have “primary” status on this shard.

Continue checking the status of the removeShard command until the number of chunks remaining is 0. Always run the command on the admin database. If you are on a database other than admin, you can use sh._adminCommand to run the command on admin.

Move Unsharded Data

If the shard is the primary shard for one or more databases in the cluster, then the shard will have unsharded data. If the shard is not the primary shard for any databases, skip to the next task, Finalize the Migration.

In a cluster, a database with unsharded collections stores those collections only on a single shard. That shard becomes the primary shard for that database. (Different databases in a cluster can have different primary shards.)

Warning

Do not perform this procedure until you have finished draining the shard.

To determine if the shard you are removing is the primary shard for any of the cluster’s databases, issue one of the following methods:

sh.status()

db.printShardingStatus()

In the resulting document, the databases field lists each database and its primary shard. For example, the following database field shows that the products database uses mongodb0 as the primary shard:

{  "_id" : "products",  "partitioned" : true,  "primary" : "mongodb0" }

To move a database to another shard, use the movePrimary command. For example, to migrate all remaining unsharded data from mongodb0 to mongodb1, issue the following command:

db.runCommand( { movePrimary: "products", to: "mongodb1" })

This command does not return until MongoDB completes moving all data, which may take a long time. The response from this command will resemble the following:

{ "primary" : "mongodb1", "ok" : 1 }

Finalize the Migration

To clean up all metadata information and finalize the removal, run removeShard again. For example, for a shard named mongodb0, run:

use admin
db.runCommand( { removeShard: "mongodb0" } )

A success message appears at completion:

{
    "msg" : "removeshard completed successfully",
    "state" : "completed",
    "shard" : "mongodb0",
    "ok" : 1
}

Once the value of the state field is “completed”, you may safely stop the processes comprising the mongodb0 shard.

Sharded Cluster Data Management

The following documents provide information in managing data in sharded clusters.

Create Chunks in a Sharded Cluster

Create chunks, or pre-split empty collection to ensure an even distribution of chunks during data ingestion.

Split Chunks in a Sharded Cluster

Manually create chunks in a sharded collection.

Migrate Chunks in a Sharded Cluster

Manually migrate chunks without using the automatic balance process.

Merge Chunks in a Sharded Cluster

Use the mergeChunks to manually combine chunk ranges.

Modify Chunk Size in a Sharded Cluster

Modify the default chunk size in a sharded collection

Clear jumbo Flag

Clear jumbo flag from a shard.

Tag Aware Sharding

Tags associate specific ranges of shard key values with specific shards for use in managing deployment patterns.

Manage Shard Tags

Use tags to associate specific ranges of shard key values with specific shards.

Enforce Unique Keys for Sharded Collections

Ensure that a field is always unique in all collections in a sharded cluster.

Shard GridFS Data Store

Choose whether to shard GridFS data in a sharded collection.

Create Chunks in a Sharded Cluster

Split Chunks in a Sharded Cluster

Migrate Chunks in a Sharded Cluster

Merge Chunks in a Sharded Cluster

Modify Chunk Size in a Sharded Cluster

Clear jumbo Flag

Tag Aware Sharding

Manage Shard Tags

Enforce Unique Keys for Sharded Collections

Shard GridFS Data Store

Create Chunks in a Sharded Cluster

Pre-splitting the chunk ranges in an empty sharded collection allows clients to insert data into an already partitioned collection. In most situations a sharded cluster will create and distribute chunks automatically without user intervention. However, in a limited number of cases, MongoDB cannot create enough chunks or distribute data fast enough to support required throughput. For example:

If you want to partition an existing data collection that resides on a single shard.

If you want to ingest a large volume of data into a cluster that isn’t balanced, or where the ingestion of data will lead to data imbalance. For example, monotonically increasing or decreasing shard keys insert all data into a single chunk.

These operations are resource intensive for several reasons:

Chunk migration requires copying all the data in the chunk from one shard to another.

MongoDB can migrate only a single chunk at a time.

MongoDB creates splits only after an insert operation.

Warning

Only pre-split an empty collection. If a collection already has data, MongoDB automatically splits the collection’s data when you enable sharding for the collection. Subsequent attempts to manually create splits can lead to unpredictable chunk ranges and sizes as well as inefficient or ineffective balancing behavior.

To create chunks manually, use the following procedure:

Split empty chunks in your collection by manually performing the split command on chunks.

Example

To create chunks for documents in the myapp.users collection using the email field as the shard key, use the following operation in the mongo shell:

for ( var x=97; x<97+26; x++ ){
  for( var y=97; y<97+26; y+=6 ) {
    var prefix = String.fromCharCode(x) + String.fromCharCode(y);
    db.runCommand( { split : "myapp.users" , middle : { email : prefix } } );
  }
}

This assumes a collection size of 100 million documents.

For information on the balancer and automatic distribution of chunks across shards, see Cluster Balancer and Chunk Migration. For information on manually migrating chunks, see Migrate Chunks in a Sharded Cluster.

Split Chunks in a Sharded Cluster

Normally, MongoDB splits a chunk after an insert if the chunk exceeds the maximum chunk size. However, you may want to split chunks manually if:

you have a large amount of data in your cluster and very few chunks, as is the case after deploying a cluster using existing data.

you expect to add a large amount of data that would initially reside in a single chunk or shard. For example, you plan to insert a large amount of data with shard key values between 300 and 400, but all values of your shard keys are between 250 and 500 are in a single chunk.

Note

New in version 2.6: MongoDB provides the mergeChunks command to combine contiguous chunk ranges into a single chunk. See Merge Chunks in a Sharded Cluster for more information.

The balancer may migrate recently split chunks to a new shard immediately if mongos predicts future insertions will benefit from the move. The balancer does not distinguish between chunks split manually and those split automatically by the system.

Warning

Be careful when splitting data in a sharded collection to create new chunks. When you shard a collection that has existing data, MongoDB automatically creates chunks to evenly distribute the collection. To split data effectively in a sharded cluster you must consider the number of documents in a chunk and the average document size to create a uniform chunk size. When chunks have irregular sizes, shards may have an equal number of chunks but have very different data sizes. Avoid creating splits that lead to a collection with differently sized chunks.

Use sh.status() to determine the current chunk ranges across the cluster.

To split chunks manually, use the split command with either fields middle or find. The mongo shell provides the helper methods sh.splitFind() and sh.splitAt().

splitFind() splits the chunk that contains the first document returned that matches this query into two equally sized chunks. You must specify the full namespace (i.e. “<database>.<collection>”) of the sharded collection to splitFind(). The query in splitFind() does not need to use the shard key, though it nearly always makes sense to do so.

Example

The following command splits the chunk that contains the value of 63109 for the zipcode field in the people collection of the records database:

sh.splitFind( "records.people", { "zipcode": "63109" } )

Use splitAt() to split a chunk in two, using the queried document as the lower bound in the new chunk:

Example

The following command splits the chunk that contains the value of 63109 for the zipcode field in the people collection of the records database.

sh.splitAt( "records.people", { "zipcode": "63109" } )

Note

splitAt() does not necessarily split the chunk into two equally sized chunks. The split occurs at the location of the document matching the query, regardless of where that document is in the chunk.

Migrate Chunks in a Sharded Cluster

In most circumstances, you should let the automatic balancer migrate chunks between shards. However, you may want to migrate chunks manually in a few cases:

When pre-splitting an empty collection, migrate chunks manually to distribute them evenly across the shards. Use pre-splitting in limited situations to support bulk data ingestion.

If the balancer in an active cluster cannot distribute chunks within the balancing window, then you will have to migrate chunks manually.

To manually migrate chunks, use the moveChunk command. For more information on how the automatic balancer moves chunks between shards, see Cluster Balancer and Chunk Migration.

Example

Migrate a single chunk

The following example assumes that the field username is the shard key for a collection named users in the myapp database, and that the value smith exists within the chunk to migrate. Migrate the chunk using the following command in the mongo shell.

db.adminCommand( { moveChunk : "myapp.users",
                   find : {username : "smith"},
                   to : "mongodb-shard3.example.net" } )

This command moves the chunk that includes the shard key value “smith” to the shard named mongodb-shard3.example.net. The command will block until the migration is complete.

Tip

To return a list of shards, use the listShards command.

Example

Evenly migrate chunks

To evenly migrate chunks for the myapp.users collection, put each prefix chunk on the next shard from the other and run the following commands in the mongo shell:

var shServer = [ "sh0.example.net", "sh1.example.net", "sh2.example.net", "sh3.example.net", "sh4.example.net" ];
for ( var x=97; x<97+26; x++ ){
  for( var y=97; y<97+26; y+=6 ) {
    var prefix = String.fromCharCode(x) + String.fromCharCode(y);
    db.adminCommand({moveChunk : "myapp.users", find : {email : prefix}, to : shServer[(y-97)/6]})
  }
}

See Create Chunks in a Sharded Cluster for an introduction to pre-splitting.

New in version 2.2: The moveChunk command has the: _secondaryThrottle parameter. When set to true, MongoDB ensures that changes to shards as part of chunk migrations replicate to secondaries throughout the migration operation. For more information, see Change Replication Behavior for Chunk Migration (Secondary Throttle).

Changed in version 2.4: In 2.4, _secondaryThrottle is true by default.

Warning

The moveChunk command may produce the following error message:

The collection's metadata lock is already taken.

This occurs when clients have too many open cursors that access the migrating chunk. You may either wait until the cursors complete their operations or close the cursors manually.

Merge Chunks in a Sharded Cluster

Overview

The mergeChunks command allows you to collapse empty chunks into neighboring chunks on the same shard. A chunk is empty if it has no documents associated with its shard key range.

Important

Empty chunks can make the balancer assess the cluster as properly balanced when it is not.

Empty chunks can occur under various circumstances, including:

If a pre-split creates too many chunks, the distribution of data to chunks may be uneven.

If you delete many documents from a sharded collection, some chunks may no longer contain data.

This tutorial explains how to identify chunks available to merge, and how to merge those chunks with neighboring chunks.

Procedure

Note

Examples in this procedure use a users collection in the test database, using the username filed as a shard key.

Identify Chunk Ranges

In the mongo shell, identify the chunk ranges with the following operation:

sh.status()

The output of the sh.status() will resemble the following:

--- Sharding Status ---
sharding version: {
     "_id" : 1,
     "version" : 4,
     "minCompatibleVersion" : 4,
     "currentVersion" : 5,
     "clusterId" : ObjectId("5260032c901f6712dcd8f400")
}
shards:
     {  "_id" : "shard0000",  "host" : "localhost:30000" }
     {  "_id" : "shard0001",  "host" : "localhost:30001" }
  databases:
     {  "_id" : "admin",  "partitioned" : false,  "primary" : "config" }
     {  "_id" : "test",  "partitioned" : true,  "primary" : "shard0001" }
             test.users
                     shard key: { "username" : 1 }
                     chunks:
                             shard0000       7
                             shard0001       7
                     { "username" : { "$minKey" : 1 } } -->> { "username" : "user16643" } on : shard0000 Timestamp(2, 0)
                     { "username" : "user16643" } -->> { "username" : "user2329" } on : shard0000 Timestamp(3, 0)
                     { "username" : "user2329" } -->> { "username" : "user29937" } on : shard0000 Timestamp(4, 0)
                     { "username" : "user29937" } -->> { "username" : "user36583" } on : shard0000 Timestamp(5, 0)
                     { "username" : "user36583" } -->> { "username" : "user43229" } on : shard0000 Timestamp(6, 0)
                     { "username" : "user43229" } -->> { "username" : "user49877" } on : shard0000 Timestamp(7, 0)
                     { "username" : "user49877" } -->> { "username" : "user56522" } on : shard0000 Timestamp(8, 0)
                     { "username" : "user56522" } -->> { "username" : "user63169" } on : shard0001 Timestamp(8, 1)
                     { "username" : "user63169" } -->> { "username" : "user69816" } on : shard0001 Timestamp(1, 8)
                     { "username" : "user69816" } -->> { "username" : "user76462" } on : shard0001 Timestamp(1, 9)
                     { "username" : "user76462" } -->> { "username" : "user83108" } on : shard0001 Timestamp(1, 10)
                     { "username" : "user83108" } -->> { "username" : "user89756" } on : shard0001 Timestamp(1, 11)
                     { "username" : "user89756" } -->> { "username" : "user96401" } on : shard0001 Timestamp(1, 12)
                     { "username" : "user96401" } -->> { "username" : { "$maxKey" : 1 } } on : shard0001 Timestamp(1, 13)

The chunk ranges appear after the chunk counts for each sharded collection, as in the following excerpts:

Chunk counts:

chunks:
        shard0000       7
        shard0001       7

Chunk range:

{ "username" : "user36583" } -->> { "username" : "user43229" } on : shard0000 Timestamp(6, 0)

Verify a Chunk is Empty

The mergeChunks command requires at least one empty input chunk. In the mongo shell, check the amount of data in a chunk using an operation that resembles:

db.runCommand({
   "dataSize": "test.users",
   "keyPattern": { username: 1 },
   "min": { "username": "user36583" },
   "max": { "username": "user43229" }
})

If the input chunk to dataSize is empty, dataSize produces output similar to:

{ "size" : 0, "numObjects" : 0, "millis" : 0, "ok" : 1 }

Merge Chunks

Merge two contiguous chunks on the same shard, where at least one of the contains no data, with an operation that resembles the following:

db.runCommand( { mergeChunks: "test.users",
                 bounds: [ { "username": "user68982" },
                           { "username": "user95197" } ]
             } )

On success, mergeChunks produces the following output:

{ "ok" : 1 }

On any failure condition, mergeChunks returns a document where the value of the ok field is 0.

View Merged Chunks Ranges

After merging all empty chunks, confirm the new chunk, as follows:

sh.status()

The output of sh.status() should resemble:

--- Sharding Status ---
sharding version: {
     "_id" : 1,
     "version" : 4,
     "minCompatibleVersion" : 4,
     "currentVersion" : 5,
     "clusterId" : ObjectId("5260032c901f6712dcd8f400")
}
shards:
     {  "_id" : "shard0000",  "host" : "localhost:30000" }
     {  "_id" : "shard0001",  "host" : "localhost:30001" }
  databases:
     {  "_id" : "admin",  "partitioned" : false,  "primary" : "config" }
     {  "_id" : "test",  "partitioned" : true,  "primary" : "shard0001" }
             test.users
                     shard key: { "username" : 1 }
                     chunks:
                             shard0000       2
                             shard0001       2
                     { "username" : { "$minKey" : 1 } } -->> { "username" : "user16643" } on : shard0000 Timestamp(2, 0)
                     { "username" : "user16643" } -->> { "username" : "user56522" } on : shard0000 Timestamp(3, 0)
                     { "username" : "user56522" } -->> { "username" : "user96401" } on : shard0001 Timestamp(8, 1)
                     { "username" : "user96401" } -->> { "username" : { "$maxKey" : 1 } } on : shard0001 Timestamp(1, 13)

Modify Chunk Size in a Sharded Cluster

When the first mongos connects to a set of config servers, it initializes the sharded cluster with a default chunk size of 64 megabytes. This default chunk size works well for most deployments; however, if you notice that automatic migrations have more I/O than your hardware can handle, you may want to reduce the chunk size. For automatic splits and migrations, a small chunk size leads to more rapid and frequent migrations. The allowed range of the chunk size is between 1 and 1024 megabytes, inclusive.

To modify the chunk size, use the following procedure:

Connect to any mongos in the cluster using the mongo shell.

Issue the following command to switch to the Config Database:

use config

Issue the following save() operation to store the global chunk size configuration value:

db.settings.save( { _id:"chunksize", value: <sizeInMB> } )

Note

The chunkSize and --chunkSize options, passed at runtime to the mongos, do not affect the chunk size after you have initialized the cluster.

To avoid confusion, always set the chunk size using the above procedure instead of the runtime options.

Modifying the chunk size has several limitations:

Automatic splitting only occurs on insert or update.

If you lower the chunk size, it may take time for all chunks to split to the new size.

Splits cannot be undone.

If you increase the chunk size, existing chunks grow only through insertion or updates until they reach the new size.

The allowed range of the chunk size is between 1 and 1024 megabytes, inclusive.

Clear jumbo Flag

If MongoDB cannot split a chunk that exceeds the specified chunk size or contains a number of documents that exceeds the max, MongoDB labels the chunk as jumbo.

If the chunk size no longer hits the limits, MongoDB clears the jumbo flag for the chunk when the mongos reloads or rewrites the chunk metadata.

In cases where you need to clear the flag manually, the following procedures outline the steps to manually clear the jumbo flag.

Procedures

Divisible Chunks

The preferred way to clear the jumbo flag from a chunk is to attempt to split the chunk. If the chunk is divisible, MongoDB removes the flag upon successful split of the chunk.

1

Connect to mongos.

Connect a mongo shell to a mongos.

Step 1: Connect to mongos.

Connect a mongo shell to a mongos.

2

Find the jumbo Chunk.

Run sh.status(true) to find the chunk labeled jumbo.

sh.status(true)

For example, the following output from sh.status(true) shows that chunk with shard key range { "x" : 2 } -->> { "x" : 4 } is jumbo.

--- Sharding Status ---
  sharding version: {
     ...
  }
  shards:
     ...
  databases:
     ...
        test.foo
           shard key: { "x" : 1 }
        chunks:
             shard-b  2
             shard-a  2
        { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shard-b Timestamp(2, 0)
        { "x" : 1 } -->> { "x" : 2 } on : shard-a Timestamp(3, 1)
        { "x" : 2 } -->> { "x" : 4 } on : shard-a Timestamp(2, 2) jumbo
        { "x" : 4 } -->> { "x" : { "$maxKey" : 1 } } on : shard-b Timestamp(3, 0)

Step 2: Find the jumbo Chunk.

Run sh.status(true) to find the chunk labeled jumbo.

sh.status(true)

For example, the following output from sh.status(true) shows that chunk with shard key range { "x" : 2 } -->> { "x" : 4 } is jumbo.

--- Sharding Status ---
  sharding version: {
     ...
  }
  shards:
     ...
  databases:
     ...
        test.foo
           shard key: { "x" : 1 }
        chunks:
             shard-b  2
             shard-a  2
        { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shard-b Timestamp(2, 0)
        { "x" : 1 } -->> { "x" : 2 } on : shard-a Timestamp(3, 1)
        { "x" : 2 } -->> { "x" : 4 } on : shard-a Timestamp(2, 2) jumbo
        { "x" : 4 } -->> { "x" : { "$maxKey" : 1 } } on : shard-b Timestamp(3, 0)

3

Split the jumbo Chunk.

Use either sh.splitAt() or sh.splitFind() to split the jumbo chunk.

sh.splitAt( "test.foo", { x: 3 })

MongoDB removes the jumbo flag upon successful split of the chunk.

Step 3: Split the jumbo Chunk.

Use either sh.splitAt() or sh.splitFind() to split the jumbo chunk.

sh.splitAt( "test.foo", { x: 3 })

MongoDB removes the jumbo flag upon successful split of the chunk.

Indivisible Chunks

In some instances, MongoDB cannot split the no-longer jumbo chunk, such as a chunk with a range of single shard key value, and the preferred method to clear the flag is not applicable. In such cases, you can clear the flag using the following steps.

Important

Only use this method if the preferred method is not applicable.

Before modifying the config database, always back up the config database.

If you clear the jumbo flag for a chunk that still exceeds the chunk size and/or the document number limit, MongoDB will re-label the chunk as jumbo when MongoDB tries to move the chunk.

1

Stop the balancer.

Disable the cluster balancer process temporarily, following the steps outlined in Disable the Balancer.

Step 1: Stop the balancer.

Disable the cluster balancer process temporarily, following the steps outlined in Disable the Balancer.

2

Create a backup of config database.

Use mongodump against a config server to create a backup of the config database. For example:

mongodump --db config --port <config server port> --out <output file>

Step 2: Create a backup of config database.

Use mongodump against a config server to create a backup of the config database. For example:

mongodump --db config --port <config server port> --out <output file>

3

Connect to mongos.

Connect a mongo shell to a mongos.

Step 3: Connect to mongos.

Connect a mongo shell to a mongos.

4

Find the jumbo Chunk.

Run sh.status(true) to find the chunk labeled jumbo.

sh.status(true)

For example, the following output from sh.status(true) shows that chunk with shard key range { "x" : 2 } -->> { "x" : 3 } is jumbo.

--- Sharding Status ---
  sharding version: {
     ...
  }
  shards:
     ...
  databases:
     ...
        test.foo
           shard key: { "x" : 1 }
        chunks:
             shard-b  2
             shard-a  2
        { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shard-b Timestamp(2, 0)
        { "x" : 1 } -->> { "x" : 2 } on : shard-a Timestamp(3, 1)
        { "x" : 2 } -->> { "x" : 3 } on : shard-a Timestamp(2, 2) jumbo
        { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shard-b Timestamp(3, 0)

Step 4: Find the jumbo Chunk.

Run sh.status(true) to find the chunk labeled jumbo.

sh.status(true)

For example, the following output from sh.status(true) shows that chunk with shard key range { "x" : 2 } -->> { "x" : 3 } is jumbo.

--- Sharding Status ---
  sharding version: {
     ...
  }
  shards:
     ...
  databases:
     ...
        test.foo
           shard key: { "x" : 1 }
        chunks:
             shard-b  2
             shard-a  2
        { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shard-b Timestamp(2, 0)
        { "x" : 1 } -->> { "x" : 2 } on : shard-a Timestamp(3, 1)
        { "x" : 2 } -->> { "x" : 3 } on : shard-a Timestamp(2, 2) jumbo
        { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shard-b Timestamp(3, 0)

5

Update chunks collection.

In the chunks collection of the config database, unset the jumbo flag for the chunk. For example,

db.getSiblingDB("config").chunks.update(
   { ns: "test.foo", min: { x: 2 }, jumbo: true },
   { $unset: { jumbo: "" } }
)

Step 5: Update chunks collection.

In the chunks collection of the config database, unset the jumbo flag for the chunk. For example,

db.getSiblingDB("config").chunks.update(
   { ns: "test.foo", min: { x: 2 }, jumbo: true },
   { $unset: { jumbo: "" } }
)

6

Restart the balancer.

Restart the balancer, following the steps in Enable the Balancer.

Step 6: Restart the balancer.

Restart the balancer, following the steps in Enable the Balancer.

7

Optional. Clear current cluster meta information.

To ensure that mongos instances update their cluster information cache, run flushRouterConfig in the admin database.

db.adminCommand({ flushRouterConfig: 1 } )

Step 7: Optional. Clear current cluster meta information.

To ensure that mongos instances update their cluster information cache, run flushRouterConfig in the admin database.

db.adminCommand({ flushRouterConfig: 1 } )

Tag Aware Sharding

MongoDB supports tagging a range of shard key values to associate that range with a shard or group of shards. Those shards receive all inserts within the tagged range.

The balancer obeys tagged range associations, which enables the following deployment patterns:

isolate a specific subset of data on a specific set of shards.

ensure that the most relevant data reside on shards that are geographically closest to the application servers.

This document describes the behavior, operation, and use of tag aware sharding in MongoDB deployments.

Considerations

Shard key range tags are distinct from replica set member tags.

Hash-based sharding only supports tag-aware sharding on entire collection.

Shard ranges are always inclusive of the lower value and exclusive of the upper boundary.

Behavior and Operations

The balancer migrates chunks of documents in a sharded collections to the shards associated with a tag that has a shard key range with an upper bound greater than the chunk’s lower bound.

During balancing rounds, if the balancer detects that any chunks violate configured tags, the balancer migrates chunks in tagged ranges to shards associated with those tags.

After configuring tags with a shard key range, and associating it with a shard or shards, the cluster may take some time to balance the data among the shards. This depends on the division of chunks and the current distribution of data in the cluster.

Once configured, the balancer respects tag ranges during future balancing rounds.

See also

Manage Shard Tags

Additional Resource

MongoDB Multi-Data Center Deployments Whitepaper [http://www.mongodb.com/lp/white-paper/multi-dc]

Manage Shard Tags

In a sharded cluster, you can use tags to associate specific ranges of a shard key with a specific shard or subset of shards.

Tag a Shard

Associate tags with a particular shard using the sh.addShardTag() method when connected to a mongos instance. A single shard may have multiple tags, and multiple shards may also have the same tag.

Example

The following example adds the tag NYC to two shards, and the tags SFO and NRT to a third shard:

sh.addShardTag("shard0000", "NYC")
sh.addShardTag("shard0001", "NYC")
sh.addShardTag("shard0002", "SFO")
sh.addShardTag("shard0002", "NRT")

You may remove tags from a particular shard using the sh.removeShardTag() method when connected to a mongos instance, as in the following example, which removes the NRT tag from a shard:

sh.removeShardTag("shard0002", "NRT")

Tag a Shard Key Range

To assign a tag to a range of shard keys use the sh.addTagRange() method when connected to a mongos instance. Any given shard key range may only have one assigned tag. You cannot overlap defined ranges, or tag the same range more than once.

Example

Given a collection named users in the records database, sharded by the zipcode field. The following operations assign:

two ranges of zip codes in Manhattan and Brooklyn the NYC tag

one range of zip codes in San Francisco the SFO tag

sh.addTagRange("records.users", { zipcode: "10001" }, { zipcode: "10281" }, "NYC")
sh.addTagRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC")
sh.addTagRange("records.users", { zipcode: "94102" }, { zipcode: "94135" }, "SFO")

Note

Shard ranges are always inclusive of the lower value and exclusive of the upper boundary.

Remove a Tag From a Shard Key Range

The mongod does not provide a helper for removing a tag range. You may delete tag assignment from a shard key range by removing the corresponding document from the tags collection of the config database.

Each document in the tags holds the namespace of the sharded collection and a minimum shard key value.

Example

The following example removes the NYC tag assignment for the range of zip codes within Manhattan:

use config
db.tags.remove({ _id: { ns: "records.users", min: { zipcode: "10001" }}, tag: "NYC" })

View Existing Shard Tags

The output from sh.status() lists tags associated with a shard, if any, for each shard. A shard’s tags exist in the shard’s document in the shards collection of the config database. To return all shards with a specific tag, use a sequence of operations that resemble the following, which will return only those shards tagged with NYC:

use config
db.shards.find({ tags: "NYC" })

You can find tag ranges for all namespaces in the tags collection of the config database. The output of sh.status() displays all tag ranges. To return all shard key ranges tagged with NYC, use the following sequence of operations:

use config
db.tags.find({ tags: "NYC" })

Additional Resource

MongoDB Multi-Data Center Deployments Whitepaper [http://www.mongodb.com/lp/white-paper/multi-dc]

Enforce Unique Keys for Sharded Collections

Overview

The unique constraint on indexes ensures that only one document can have a value for a field in a collection. For sharded collections these unique indexes cannot enforce uniqueness because insert and indexing operations are local to each shard.

MongoDB does not support creating new unique indexes in sharded collections and will not allow you to shard collections with unique indexes on fields other than the _id field.

If you need to ensure that a field is always unique in a sharded collection, there are three options:

Enforce uniqueness of the shard key.

MongoDB can enforce uniqueness for the shard key. For compound shard keys, MongoDB will enforce uniqueness on the entire key combination, and not for a specific component of the shard key.

You cannot specify a unique constraint on a hashed index.

Use a secondary collection to enforce uniqueness.

Create a minimal collection that only contains the unique field and a reference to a document in the main collection. If you always insert into a secondary collection before inserting to the main collection, MongoDB will produce an error if you attempt to use a duplicate key.

If you have a small data set, you may not need to shard this collection and you can create multiple unique indexes. Otherwise you can shard on a single unique key.

Use guaranteed unique identifiers.

Universally unique identifiers (i.e. UUID) like the ObjectId are guaranteed to be unique.

Procedures

Unique Constraints on the Shard Key

Process

To shard a collection using the unique constraint, specify the shardCollection command in the following form:

db.runCommand( { shardCollection : "test.users" , key : { email : 1 } , unique : true } );

Remember that the _id field index is always unique. By default, MongoDB inserts an ObjectId into the _id field. However, you can manually insert your own value into the _id field and use this as the shard key. To use the _id field as the shard key, use the following operation:

db.runCommand( { shardCollection : "test.users" } )

Limitations

You can only enforce uniqueness on one single field in the collection using this method.

If you use a compound shard key, you can only enforce uniqueness on the combination of component keys in the shard key.

In most cases, the best shard keys are compound keys that include elements that permit write scaling and query isolation, as well as high cardinality. These ideal shard keys are not often the same keys that require uniqueness and enforcing unique values in these collections requires a different approach.

Unique Constraints on Arbitrary Fields

If you cannot use a unique field as the shard key or if you need to enforce uniqueness over multiple fields, you must create another collection to act as a “proxy collection”. This collection must contain both a reference to the original document (i.e. its ObjectId) and the unique key.

If you must shard this “proxy” collection, then shard on the unique key using the above procedure; otherwise, you can simply create multiple unique indexes on the collection.

Process

Consider the following for the “proxy collection:”

{
  "_id" : ObjectId("...")
  "email" ": "..."
}

The _id field holds the ObjectId of the document it reflects, and the email field is the field on which you want to ensure uniqueness.

To shard this collection, use the following operation using the email field as the shard key:

db.runCommand( { shardCollection : "records.proxy" ,
                 key : { email : 1 } ,
                 unique : true } );

If you do not need to shard the proxy collection, use the following command to create a unique index on the email field:

db.proxy.ensureIndex( { "email" : 1 }, { unique : true } )

You may create multiple unique indexes on this collection if you do not plan to shard the proxy collection.

To insert documents, use the following procedure in the JavaScript shell:

db = db.getSiblingDB('records');

var primary_id = ObjectId();

db.proxy.insert({
   "_id" : primary_id
   "email" : "example@example.net"
})

// if: the above operation returns successfully,
// then continue:

db.information.insert({
   "_id" : primary_id
   "email": "example@example.net"
   // additional information...
})

You must insert a document into the proxy collection first. If this operation succeeds, the email field is unique, and you may continue by inserting the actual document into the information collection.

See

The full documentation of: ensureIndex() and shardCollection.

Considerations

Your application must catch errors when inserting documents into the “proxy” collection and must enforce consistency between the two collections.

If the proxy collection requires sharding, you must shard on the single field on which you want to enforce uniqueness.

To enforce uniqueness on more than one field using sharded proxy collections, you must have one proxy collection for every field for which to enforce uniqueness. If you create multiple unique indexes on a single proxy collection, you will not be able to shard proxy collections.

Use Guaranteed Unique Identifier

The best way to ensure a field has unique values is to generate universally unique identifiers (UUID,) such as MongoDB’s ‘ObjectId values.

This approach is particularly useful for the``_id`` field, which must be unique: for collections where you are not sharding by the _id field the application is responsible for ensuring that the _id field is unique.

Shard GridFS Data Store

When sharding a GridFS store, consider the following:

files Collection

Most deployments will not need to shard the files collection. The files collection is typically small, and only contains metadata. None of the required keys for GridFS lend themselves to an even distribution in a sharded situation. If you must shard the files collection, use the _id field possibly in combination with an application field.

Leaving files unsharded means that all the file metadata documents live on one shard. For production GridFS stores you must store the files collection on a replica set.

chunks Collection

To shard the chunks collection by { files_id : 1 , n : 1 }, issue commands similar to the following:

db.fs.chunks.ensureIndex( { files_id : 1 , n : 1 } )

db.runCommand( { shardCollection : "test.fs.chunks" , key : { files_id : 1 , n : 1 } } )

You may also want to shard using just the file_id field, as in the following operation:

db.runCommand( { shardCollection : "test.fs.chunks" , key : {  files_id : 1 } } )

Important

{ files_id : 1 , n : 1 } and {  files_id : 1 } are the only supported shard keys for the chunks collection of a GridFS store.

Note

Changed in version 2.2.

Before 2.2, you had to create an additional index on files_id to shard using only this field.

The default files_id value is an ObjectId, as a result the values of files_id are always ascending, and applications will insert all new GridFS data to a single chunk and shard. If your write load is too high for a single server to handle, consider a different shard key or use a different value for _id in the files collection.

Troubleshoot Sharded Clusters

This section describes common strategies for troubleshooting sharded cluster deployments.

Config Database String Error

Start all mongos instances in a sharded cluster with an identical configDB string. If a mongos instance tries to connect to the sharded cluster with a configDB string that does not exactly match the string used by the other mongos instances, including the order of the hosts, the following errors occur:

could not initialize sharding on connection

And:

mongos specified a different config database string

To solve the issue, restart the mongos with the correct string.

Cursor Fails Because of Stale Config Data

A query returns the following warning when one or more of the mongos instances has not yet updated its cache of the cluster’s metadata from the config database:

could not initialize cursor across all shards because : stale config detected

This warning should not propagate back to your application. The warning will repeat until all the mongos instances refresh their caches. To force an instance to refresh its cache, run the flushRouterConfig command.

Avoid Downtime when Moving Config Servers

Use CNAMEs to identify your config servers to the cluster so that you can rename and renumber your config servers without downtime.

Sharding Reference

Sharding Methods in the mongo Shell

Name | Description
sh._adminCommand | Runs a database command against the admin database, like db.runCommand(), but can confirm that it is issued against a mongos.
sh._checkFullName() | Tests a namespace to determine if its well formed.
sh._checkMongos() | Tests to see if the mongo shell is connected to a mongos instance.
sh._lastMigration() | Reports on the last chunk migration.
sh.addShard() | Adds a shard to a sharded cluster.
sh.addShardTag() | Associates a shard with a tag, to support tag aware sharding.
sh.addTagRange() | Associates range of shard keys with a shard tag, to support tag aware sharding.
sh.disableBalancing() | Disable 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 sh.disableBalancing().
sh.enableSharding() | Enables sharding on a specific database.
sh.getBalancerHost() | Returns the name of a mongos that’s responsible for the balancer process.
sh.getBalancerState() | Returns a boolean to report if the balancer is currently enabled.
sh.help() | Returns help text for the sh methods.
sh.isBalancerRunning() | Returns a boolean to report if the balancer process is currently migrating chunks.
sh.moveChunk() | Migrates a chunk in a sharded cluster.
sh.removeShardTag() | Removes the association between a shard and a shard tag.
sh.setBalancerState() | Enables or disables the balancer which migrates chunks between shards.
sh.shardCollection() | Enables sharding for a collection.
sh.splitAt() | Divides an existing chunk into two chunks using a specific value of the shard key as the dividing point.
sh.splitFind() | Divides an existing chunk that contains a document matching a query into two approximately equal chunks.
sh.startBalancer() | Enables the balancer and waits for balancing to start.
sh.status() | Reports on the status of a sharded cluster, as db.printShardingStatus().
sh.stopBalancer() | Disables the balancer and waits for any in progress balancing rounds to complete.
sh.waitForBalancer() | Internal. Waits for the balancer state to change.
sh.waitForBalancerOff() | Internal. Waits until the balancer stops running.
sh.waitForDLock() | Internal. Waits for a specified distributed sharded cluster lock.
sh.waitForPingChange() | Internal. Waits for a change in ping state from one of the mongos in the sharded cluster.

Sharding Database Commands

The following database commands support sharded clusters.

Name | Description
flushRouterConfig | Forces an update to the cluster metadata cached by a mongos.
addShard | Adds a shard to a sharded cluster.
cleanupOrphaned | Removes orphaned data with shard key values outside of the ranges of the chunks owned by a shard.
checkShardingIndex | Internal command that validates index on shard key.
enableSharding | Enables sharding on a specific database.
listShards | Returns a list of configured shards.
removeShard | Starts the process of removing a shard from a sharded cluster.
getShardMap | Internal command that reports on the state of a sharded cluster.
getShardVersion | Internal command that returns the config server version.
mergeChunks | Provides the ability to combine chunks on a single shard.
setShardVersion | Internal command to sets the config server version.
shardCollection | Enables the sharding functionality for a collection, allowing the collection to be sharded.
shardingState | Reports whether the mongod is a member of a sharded cluster.
unsetSharding | Internal command that affects connections between instances in a MongoDB deployment.
split | Creates a new chunk.
splitChunk | Internal command to split chunk. Instead use the methods sh.splitFind() and sh.splitAt().
splitVector | Internal command that determines split points.
medianKey | Deprecated internal command. See splitVector.
moveChunk | Internal command that migrates chunks between shards.
movePrimary | Reassigns the primary shard when removing a shard from a sharded cluster.
isdbgrid | Verifies that a process is a mongos.

Reference Documentation

Config Database

Complete documentation of the content of the local database that MongoDB uses to store sharded cluster metadata.

Config Database

Config Database

The config database supports sharded cluster operation. See the Sharding section of this manual for full documentation of sharded clusters.

Important

Consider the schema of the config database internal and may change between releases of MongoDB. The config database is not a dependable API, and users should not write data to the config database in the course of normal operation or maintenance.

Warning

Modification of the config database on a functioning system may lead to instability or inconsistent data sets. If you must modify the config database, use mongodump to create a full backup of the config database.

To access the config database, connect to a mongos instance in a sharded cluster, and use the following helper:

use config

You can return a list of the collections, with the following helper:

show collections

Collections

config

config.changelog

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The changelog collection stores a document for each change to the metadata of a sharded collection.

Example

The following example displays a single record of a chunk split from a changelog collection:

{
 "_id" : "<hostname>-<timestamp>-<increment>",
 "server" : "<hostname><:port>",
 "clientAddr" : "127.0.0.1:63381",
 "time" : ISODate("2012-12-11T14:09:21.039Z"),
 "what" : "split",
 "ns" : "<database>.<collection>",
 "details" : {
    "before" : {
       "min" : {
          "<database>" : { $minKey : 1 }
       },
       "max" : {
          "<database>" : { $maxKey : 1 }
       },
       "lastmod" : Timestamp(1000, 0),
       "lastmodEpoch" : ObjectId("000000000000000000000000")
    },
    "left" : {
       "min" : {
          "<database>" : { $minKey : 1 }
       },
       "max" : {
          "<database>" : "<value>"
       },
       "lastmod" : Timestamp(1000, 1),
       "lastmodEpoch" : ObjectId(<...>)
    },
    "right" : {
       "min" : {
          "<database>" : "<value>"
       },
       "max" : {
          "<database>" : { $maxKey : 1 }
       },
       "lastmod" : Timestamp(1000, 2),
       "lastmodEpoch" : ObjectId("<...>")
    }
 }
}

Each document in the changelog collection contains the following fields:

config.changelog._id

The value of changelog._id is: <hostname>-<timestamp>-<increment>.

config.changelog.server

The hostname of the server that holds this data.

config.changelog.clientAddr

A string that holds the address of the client, a mongos instance that initiates this change.

config.changelog.time

A ISODate timestamp that reflects when the change occurred.

config.changelog.what

Reflects the type of change recorded. Possible values are:

dropCollection

dropCollection.start

dropDatabase

dropDatabase.start

moveChunk.start

moveChunk.commit

split

multi-split

config.changelog.ns

Namespace where the change occurred.

config.changelog.details

A document that contains additional details regarding the change. The structure of the details document depends on the type of change.

config.chunks

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The chunks collection stores a document for each chunk in the cluster. Consider the following example of a document for a chunk named records.pets-animal_\"cat\":

{
   "_id" : "mydb.foo-a_\"cat\"",
   "lastmod" : Timestamp(1000, 3),
   "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc"),
   "ns" : "mydb.foo",
   "min" : {
         "animal" : "cat"
   },
   "max" : {
         "animal" : "dog"
   },
   "shard" : "shard0004"
}

These documents store the range of values for the shard key that describe the chunk in the min and max fields. Additionally the shard field identifies the shard in the cluster that “owns” the chunk.

config.collections

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The collections collection stores a document for each sharded collection in the cluster. Given a collection named pets in the records database, a document in the collections collection would resemble the following:

{
   "_id" : "records.pets",
   "lastmod" : ISODate("1970-01-16T15:00:58.107Z"),
   "dropped" : false,
   "key" : {
         "a" : 1
   },
   "unique" : false,
   "lastmodEpoch" : ObjectId("5078407bd58b175c5c225fdc")
}

config.databases

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The databases collection stores a document for each database in the cluster, and tracks if the database has sharding enabled. databases represents each database in a distinct document. When a databases have sharding enabled, the primary field holds the name of the primary shard.

{ "_id" : "admin", "partitioned" : false, "primary" : "config" }
{ "_id" : "mydb", "partitioned" : true, "primary" : "shard0000" }

config.lockpings

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The lockpings collection keeps track of the active components in the sharded cluster. Given a cluster with a mongos running on example.com:30000, the document in the lockpings collection would resemble:

{ "_id" : "example.com:30000:1350047994:16807", "ping" : ISODate("2012-10-12T18:32:54.892Z") }

config.locks

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The locks collection stores a distributed lock. This ensures that only one mongos instance can perform administrative tasks on the cluster at once. The mongos acting as balancer takes a lock by inserting a document resembling the following into the locks collection.

{
    "_id" : "balancer",
    "process" : "example.net:40000:1350402818:16807",
    "state" : 2,
    "ts" : ObjectId("507daeedf40e1879df62e5f3"),
    "when" : ISODate("2012-10-16T19:01:01.593Z"),
    "who" : "example.net:40000:1350402818:16807:Balancer:282475249",
    "why" : "doing balance round"
}

If a mongos holds the balancer lock, the state field has a value of 2, which means that balancer is active. The when field indicates when the balancer began the current operation.

Changed in version 2.0: The value of the state field was 1 before MongoDB 2.0.

config.mongos

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The mongos collection stores a document for each mongos instance affiliated with the cluster. mongos instances send pings to all members of the cluster every 30 seconds so the cluster can verify that the mongos is active. The ping field shows the time of the last ping, while the up field reports the uptime of the mongos as of the last ping. The cluster maintains this collection for reporting purposes.

The following document shows the status of the mongos running on example.com:30000.

{ "_id" : "example.com:30000", "ping" : ISODate("2012-10-12T17:08:13.538Z"), "up" : 13699, "waiting" : true }

config.settings

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The settings collection holds the following sharding configuration settings:

Chunk size. To change chunk size, see Modify Chunk Size in a Sharded Cluster.

Balancer status. To change status, see Disable the Balancer.

The following is an example settings collection:

{ "_id" : "chunksize", "value" : 64 }
{ "_id" : "balancer", "stopped" : false }

config.shards

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The shards collection represents each shard in the cluster in a separate document. If the shard is a replica set, the host field displays the name of the replica set, then a slash, then the hostname, as in the following example:

{ "_id" : "shard0000", "host" : "shard1/localhost:30000" }

If the shard has tags assigned, this document has a tags field, that holds an array of the tags, as in the following example:

{ "_id" : "shard0001", "host" : "localhost:30001", "tags": [ "NYC" ] }

config.tags

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The tags collection holds documents for each tagged shard key range in the cluster. The documents in the tags collection resemble the following:

{
    "_id" : { "ns" : "records.users", "min" : { "zipcode" : "10001" } },
    "ns" : "records.users",
    "min" : { "zipcode" : "10001" },
    "max" : { "zipcode" : "10281" },
    "tag" : "NYC"
}

config.version

Internal MongoDB Metadata

The config database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation.

The version collection holds the current metadata version number. This collection contains only one document:

To access the version collection you must use the db.getCollection() method. For example, to display the collection’s document:

mongos> db.getCollection("version").find()
{ "_id" : 1, "version" : 3 }

Note

Like all databases in MongoDB, the config database contains a system.indexes collection contains metadata for all indexes in the database for information on indexes, see Indexes.

Frequently Asked Questions

FAQ: MongoDB Fundamentals

What kind of database is MongoDB?

Do MongoDB databases have tables?

Do MongoDB databases have schemas?

What languages can I use to work with MongoDB?

Does MongoDB support SQL?

What are typical uses for MongoDB?

Does MongoDB support ACID transactions?

Does MongoDB require a lot of RAM?

How do I configure the cache size?

Does MongoDB require a separate caching layer for application-level caching?

Does MongoDB handle caching?

Are writes written to disk immediately, or lazily?

What language is MongoDB written in?

What are the limitations of 32-bit versions of MongoDB?

FAQ: MongoDB for Application Developers

What is a namespace in MongoDB?

How do you copy all objects from one collection to another?

If you remove a document, does MongoDB remove it from disk?

When does MongoDB write updates to disk?

How do I do transactions and locking in MongoDB?

How do you aggregate data with MongoDB?

Why does MongoDB log so many “Connection Accepted” events?

Does MongoDB run on Amazon EBS?

Why are MongoDB’s data files so large?

How do I optimize storage use for small documents?

When should I use GridFS?

How does MongoDB address SQL or Query injection?

How does MongoDB provide concurrency?

What is the compare order for BSON types?

When multiplying values of mixed types, what type conversion rules apply?

How do I query for fields that have null values?

Are there any restrictions on the names of Collections?

How do I isolate cursors from intervening write operations?

When should I embed documents within other documents?

Where can I learn more about data modeling in MongoDB?

Can I manually pad documents to prevent moves during updates?

FAQ: The mongo Shell

How can I enter multi-line operations in the mongo shell?

How can I access different databases temporarily?

Does the mongo shell support tab completion and other keyboard shortcuts?

How can I customize the mongo shell prompt?

Can I edit long shell operations with an external text editor?

FAQ: Concurrency

What type of locking does MongoDB use?

How granular are locks in MongoDB?

How do I see the status of locks on my mongod instances?

Does a read or write operation ever yield the lock?

Which operations lock the database?

Which administrative commands lock the database?

Does a MongoDB operation ever lock more than one database?

How does sharding affect concurrency?

How does concurrency affect a replica set primary?

How does concurrency affect secondaries?

What kind of concurrency does MongoDB provide for JavaScript operations?

FAQ: Sharding with MongoDB

Is sharding appropriate for a new deployment?

How does sharding work with replication?

Can I change the shard key after sharding a collection?

What happens to unsharded collections in sharded databases?

How does MongoDB distribute data across shards?

What happens if a client updates a document in a chunk during a migration?

What happens to queries if a shard is inaccessible or slow?

How does MongoDB distribute queries among shards?

How does MongoDB sort queries in sharded environments?

How does MongoDB ensure unique _id field values when using a shard key other than _id?

I’ve enabled sharding and added a second shard, but all the data is still on one server. Why?

Is it safe to remove old files in the moveChunk directory?

How does mongos use connections?

Why does mongos hold connections open?

Where does MongoDB report on connections used by mongos?

What does writebacklisten in the log mean?

How should administrators deal with failed migrations?

What is the process for moving, renaming, or changing the number of config servers?

When do the mongos servers detect config server changes?

Is it possible to quickly update mongos servers after updating a replica set configuration?

What does the maxConns setting on mongos do?

How do indexes impact queries in sharded systems?

Can shard keys be randomly generated?

Can shard keys have a non-uniform distribution of values?

Can you shard on the _id field?

What do moveChunk commit failed errors mean?

How does draining a shard affect the balancing of uneven chunk distribution?

FAQ: Replication and Replica Sets

What kinds of replication does MongoDB support?

What do the terms “primary” and “master” mean?

What do the terms “secondary” and “slave” mean?

How long does replica set failover take?

Does replication work over the Internet and WAN connections?

Can MongoDB replicate over a “noisy” connection?

What is the preferred replication method: master/slave or replica sets?

What is the preferred replication method: replica sets or replica pairs?

Why use journaling if replication already provides data redundancy?

Are write operations durable if write concern does not acknowledge writes?

How many arbiters do replica sets need?

What information do arbiters exchange with the rest of the replica set?

Which members of a replica set vote in elections?

Do hidden members vote in replica set elections?

Is it normal for replica set members to use different amounts of disk space?

FAQ: MongoDB Storage

What are memory mapped files?

How do memory mapped files work?

How does MongoDB work with memory mapped files?

What are page faults?

What is the difference between soft and hard page faults?

What tools can I use to investigate storage use in MongoDB?

What is the working set?

Why are the files in my data directory larger than the data in my database?

How can I check the size of a collection?

How can I check the size of indexes?

How do I know when the server runs out of disk space?

FAQ: Indexes

Should you run ensureIndex() after every insert?

How do you know what indexes exist in a collection?

How do you determine the size of an index?

What happens if an index does not fit into RAM?

How do you know what index a query used?

How do you determine what fields to index?

How do write operations affect indexes?

Will building a large index affect database performance?

Can I use index keys to constrain query matches?

Using $ne and $nin in a query is slow. Why?

Can I use a multi-key index to support a query for a whole array?

How can I effectively use indexes strategy for attribute lookups?

FAQ: MongoDB Diagnostics

Where can I find information about a mongod process that stopped running unexpectedly?

Does TCP keepalive time affect sharded clusters and replica sets?

What tools are available for monitoring MongoDB?

Memory Diagnostics

Sharded Cluster Diagnostics

FAQ: MongoDB Fundamentals

This document addresses basic high level questions about MongoDB and its use.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

What kind of database is MongoDB?

MongoDB is a document-oriented DBMS. Think of MySQL but with JSON-like objects comprising the data model, rather than RDBMS tables. Significantly, MongoDB supports neither joins nor transactions. However, it features secondary indexes, an expressive query language, atomic writes on a per-document level, and fully-consistent reads.

Operationally, MongoDB features master-slave replication with automated failover and built-in horizontal scaling via automated range-based partitioning.

Note

MongoDB uses BSON, a binary object format similar to, but more expressive than JSON.

Do MongoDB databases have tables?

Instead of tables, a MongoDB database stores its data in collections, which are the rough equivalent of RDBMS tables. A collection holds one or more documents, which corresponds to a record or a row in a relational database table, and each document has one or more fields, which corresponds to a column in a relational database table.

Collections have important differences from RDBMS tables. Documents in a single collection may have a unique combination and set of fields. Documents need not have identical fields. You can add a field to some documents in a collection without adding that field to all documents in the collection.

See

SQL to MongoDB Mapping Chart

Do MongoDB databases have schemas?

MongoDB uses dynamic schemas. You can create collections without defining the structure, i.e. the fields or the types of their values, of the documents in the collection. You can change the structure of documents simply by adding new fields or deleting existing ones. Documents in a collection need not have an identical set of fields.

In practice, it is common for the documents in a collection to have a largely homogeneous structure; however, this is not a requirement. MongoDB’s flexible schemas mean that schema migration and augmentation are very easy in practice, and you will rarely, if ever, need to write scripts that perform “alter table” type operations, which simplifies and facilitates iterative software development with MongoDB.

See

SQL to MongoDB Mapping Chart

What languages can I use to work with MongoDB?

MongoDB client drivers exist for all of the most popular programming languages, and many other ones. See the latest list of drivers [http://docs.mongodb.org/ecosystem/drivers] for details.

See also

MongoDB Drivers and Client Libraries.

Does MongoDB support SQL?

No.

However, MongoDB does support a rich, ad-hoc query language of its own.

See also

Operators

What are typical uses for MongoDB?

MongoDB has a general-purpose design, making it appropriate for a large number of use cases. Examples include content management systems, mobile applications, gaming, e-commerce, analytics, archiving, and logging.

Do not use MongoDB for systems that require SQL, joins, and multi-object transactions.

Does MongoDB support ACID transactions?

MongoDB does not support multi-document transactions.

However, MongoDB does provide atomic operations on a single document. Often these document-level atomic operations are sufficient to solve problems that would require ACID transactions in a relational database.

For example, in MongoDB, you can embed related data in nested arrays or nested documents within a single document and update the entire document in a single atomic operation. Relational databases might represent the same kind of data with multiple tables and rows, which would require transaction support to update the data atomically.

MongoDB allows clients to read documents inserted or modified before it commits these modifications to disk, regardless of write concern level or journaling configuration. As a result, applications may observe two classes of behaviors:

For systems with multiple concurrent readers and writers, MongoDB will allow clients to read the results of a write operation before the write operation returns.

If the mongod terminates before the journal commits, even if a write returns successfully, queries may have read data that will not exist after the mongod restarts.

Other database systems refer to these isolation semantics as read uncommitted. For all inserts and updates, MongoDB modifies each document in isolation: clients never see documents in intermediate states. For multi-document operations, MongoDB does not provide any multi-document transactions or isolation.

When mongod returns a successful journaled write concern, the data is fully committed to disk and will be available after mongod restarts.

For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of the voting members of the set. [1] MongoDB regularly commits data to the journal regardless of journaled write concern: use the commitIntervalMs to control how often a mongod commits the journal.

[1]
For the purposes of write concern, w:majority refers to a majority of all the members in the set. As a result, arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

Does MongoDB require a lot of RAM?

Not necessarily. It’s certainly possible to run MongoDB on a machine with a small amount of free RAM.

MongoDB automatically uses all free memory on the machine as its cache. System resource monitors show that MongoDB uses a lot of memory, but its usage is dynamic. If another process suddenly needs half the server’s RAM, MongoDB will yield cached memory to the other process.

Technically, the operating system’s virtual memory subsystem manages MongoDB’s memory. This means that MongoDB will use as much free memory as it can, swapping to disk as needed. Deployments with enough memory to fit the application’s working data set in RAM will achieve the best performance.

See also

FAQ: MongoDB Diagnostics for answers to additional questions about MongoDB and Memory use.

How do I configure the cache size?

MongoDB has no configurable cache. MongoDB uses all free memory on the system automatically by way of memory-mapped files. Operating systems use the same approach with their file system caches.

Does MongoDB require a separate caching layer for application-level caching?

No. In MongoDB, a document’s representation in the database is similar to its representation in application memory. This means the database already stores the usable form of data, making the data usable in both the persistent store and in the application cache. This eliminates the need for a separate caching layer in the application.

This differs from relational databases, where caching data is more expensive. Relational databases must transform data into object representations that applications can read and must store the transformed data in a separate cache: if these transformation from data to application objects require joins, this process increases the overhead related to using the database which increases the importance of the caching layer.

Does MongoDB handle caching?

Yes. MongoDB keeps all of the most recently used data in RAM. If you have created indexes for your queries and your working data set fits in RAM, MongoDB serves all queries from memory.

MongoDB does not implement a query cache: MongoDB serves all queries directly from the indexes and/or data files.

Are writes written to disk immediately, or lazily?

Writes are physically written to the journal within 100 milliseconds, by default. At that point, the write is “durable” in the sense that after a pull-plug-from-wall event, the data will still be recoverable after a hard restart. See commitIntervalMs for more information on the journal commit window.

While the journal commit is nearly instant, MongoDB writes to the data files lazily. MongoDB may wait to write data to the data files for as much as one minute by default. This does not affect durability, as the journal has enough information to ensure crash recovery. To change the interval for writing to the data files, see syncPeriodSecs.

What language is MongoDB written in?

MongoDB is implemented in C++. Drivers and client libraries are typically written in their respective languages, although some drivers use C extensions for better performance.

What are the limitations of 32-bit versions of MongoDB?

MongoDB uses memory-mapped files. When running a 32-bit build of MongoDB, the total storage size for the server, including data and indexes, is 2 gigabytes. For this reason, do not deploy MongoDB to production on 32-bit machines.

If you’re running a 64-bit build of MongoDB, there’s virtually no limit to storage size. For production deployments, 64-bit builds and operating systems are strongly recommended.

See also

“Blog Post: 32-bit Limitations [http://blog.mongodb.org/post/137788967/32-bit-limitations]“

Note

32-bit builds disable journaling by default because journaling further limits the maximum amount of data that the database can store.

FAQ: MongoDB for Application Developers

This document answers common questions about application development using MongoDB.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

What is a namespace in MongoDB?

A “namespace” is the concatenation of the database name and the collection names [1] with a period character in between.

Collections are containers for documents that share one or more indexes. Databases are groups of collections stored on disk using a single set of data files. [2]

For an example acme.users namespace, acme is the database name and users is the collection name. Period characters can occur in collection names, so that acme.user.history is a valid namespace, with acme as the database name, and user.history as the collection name.

While data models like this appear to support nested collections, the collection namespace is flat, and there is no difference from the perspective of MongoDB between acme, acme.users, and acme.records.

[1]
Each index also has its own namespace.

[2]
MongoDB database have a configurable limit on the number of namespaces in a database.

How do you copy all objects from one collection to another?

In the mongo shell, you can use the following operation to duplicate the entire collection:

db.source.copyTo(newCollection)

Warning

When using db.collection.copyTo() check field types to ensure that the operation does not remove type information from documents during the translation from BSON to JSON.

The db.collection.copyTo() method uses the eval command internally. As a result, the db.collection.copyTo() operation takes a global lock that blocks all other read and write operations until the db.collection.copyTo() completes.

Also consider the cloneCollection command that may provide some of this functionality.

If you remove a document, does MongoDB remove it from disk?

Yes.

When you use remove(), the object will no longer exist in MongoDB’s on-disk data storage.

When does MongoDB write updates to disk?

MongoDB flushes writes to disk on a regular interval. In the default configuration, MongoDB writes data to the main data files on disk every 60 seconds and commits the journal roughly every 100 milliseconds. These values are configurable with the commitIntervalMs and syncPeriodSecs.

These values represent the maximum amount of time between the completion of a write operation and the point when the write is durable in the journal, if enabled, and when MongoDB flushes data to the disk. In many cases MongoDB and the operating system flush data to disk more frequently, so that the above values represents a theoretical maximum.

However, by default, MongoDB uses a “lazy” strategy to write to disk. This is advantageous in situations where the database receives a thousand increments to an object within one second, MongoDB only needs to flush this data to disk once. In addition to the aforementioned configuration options, you can also use fsync and Write Concern Reference to modify this strategy.

How do I do transactions and locking in MongoDB?

MongoDB does not have support for traditional locking or complex transactions with rollback. MongoDB aims to be lightweight, fast, and predictable in its performance. This is similar to the MySQL MyISAM autocommit model. By keeping transaction support extremely simple, MongoDB can provide greater performance especially for partitioned or replicated systems with a number of database server processes.

MongoDB does have support for atomic operations within a single document. Given the possibilities provided by nested documents, this feature provides support for a large number of use-cases.

See also

The Atomicity and Transactions page.

How do you aggregate data with MongoDB?

In version 2.1 and later, you can use the new aggregation framework, with the aggregate command.

MongoDB also supports map-reduce with the mapReduce command, as well as basic aggregation with the group, count, and distinct. commands.

See also

The Aggregation page.

Why does MongoDB log so many “Connection Accepted” events?

If you see a very large number connection and re-connection messages in your MongoDB log, then clients are frequently connecting and disconnecting to the MongoDB server. This is normal behavior for applications that do not use request pooling, such as CGI. Consider using FastCGI, an Apache Module, or some other kind of persistent application server to decrease the connection overhead.

If these connections do not impact your performance you can use the run-time quiet option or the command-line option --quiet to suppress these messages from the log.

Does MongoDB run on Amazon EBS?

Yes.

MongoDB users of all sizes have had a great deal of success using MongoDB on the EC2 platform using EBS disks.

See also

Amazon EC2 [http://docs.mongodb.org/ecosystem/platforms/amazon-ec2]

Why are MongoDB’s data files so large?

MongoDB aggressively preallocates data files to reserve space and avoid file system fragmentation. You can use the storage.smallFiles setting to modify the file preallocation strategy.

See also

Why are the files in my data directory larger than the data in my database?

How do I optimize storage use for small documents?

Each MongoDB document contains a certain amount of overhead. This overhead is normally insignificant but becomes significant if all documents are just a few bytes, as might be the case if the documents in your collection only have one or two fields.

Consider the following suggestions and strategies for optimizing storage utilization for these collections:

Use the _id field explicitly.

MongoDB clients automatically add an _id field to each document and generate a unique 12-byte ObjectId for the _id field. Furthermore, MongoDB always indexes the _id field. For smaller documents this may account for a significant amount of space.

To optimize storage use, users can specify a value for the _id field explicitly when inserting documents into the collection. This strategy allows applications to store a value in the _id field that would have occupied space in another portion of the document.

You can store any value in the _id field, but because this value serves as a primary key for documents in the collection, it must uniquely identify them. If the field’s value is not unique, then it cannot serve as a primary key as there would be collisions in the collection.

Use shorter field names.

MongoDB stores all field names in every document. For most documents, this represents a small fraction of the space used by a document; however, for small documents the field names may represent a proportionally large amount of space. Consider a collection of documents that resemble the following:

{ last_name : "Smith", best_score: 3.9 }

If you shorten the field named last_name to lname and the field named best_score to score, as follows, you could save 9 bytes per document.

{ lname : "Smith", score : 3.9 }

Shortening field names reduces expressiveness and does not provide considerable benefit for larger documents and where document overhead is not of significant concern. Shorter field names do not reduce the size of indexes, because indexes have a predefined structure.

In general it is not necessary to use short field names.

Embed documents.

In some cases you may want to embed documents in other documents and save on the per-document overhead.

When should I use GridFS?

For documents in a MongoDB collection, you should always use GridFS for storing files larger than 16 MB.

In some situations, storing large files may be more efficient in a MongoDB database than on a system-level filesystem.

If your filesystem limits the number of files in a directory, you can use GridFS to store as many files as needed.

When you want to keep your files and metadata automatically synced and deployed across a number of systems and facilities. When using geographically distributed replica sets MongoDB can distribute files and their metadata automatically to a number of mongod instances and facilities.

When you want to access information from portions of large files without having to load whole files into memory, you can use GridFS to recall sections of files without reading the entire file into memory.

Do not use GridFS if you need to update the content of the entire file atomically. As an alternative you can store multiple versions of each file and specify the current version of the file in the metadata. You can update the metadata field that indicates “latest” status in an atomic update after uploading the new version of the file, and later remove previous versions if needed.

Furthermore, if your files are all smaller the 16 MB BSON Document Size limit, consider storing the file manually within a single document. You may use the BinData data type to store the binary data. See your drivers documentation for details on using BinData.

For more information on GridFS, see GridFS.

How does MongoDB address SQL or Query injection?

BSON

As a client program assembles a query in MongoDB, it builds a BSON object, not a string. Thus traditional SQL injection attacks are not a problem. More details and some nuances are covered below.

MongoDB represents queries as BSON objects. Typically client libraries provide a convenient, injection free, process to build these objects. Consider the following C++ example:

BSONObj my_query = BSON( "name" << a_name );
auto_ptr<DBClientCursor> cursor = c.query("tutorial.persons", my_query);

Here, my_query then will have a value such as { name : "Joe" }. If my_query contained special characters, for example ,, :, and {, the query simply wouldn’t match any documents. For example, users cannot hijack a query and convert it to a delete.

JavaScript

Note

You can disable all server-side execution of JavaScript, by passing the --noscripting option on the command line or setting security.javascriptEnabled in a configuration file.

All of the following MongoDB operations permit you to run arbitrary JavaScript expressions directly on the server:

$where

db.eval()

mapReduce

group

You must exercise care in these cases to prevent users from submitting malicious JavaScript.

Fortunately, you can express most queries in MongoDB without JavaScript and for queries that require JavaScript, you can mix JavaScript and non-JavaScript in a single query. Place all the user-supplied fields directly in a BSON field and pass JavaScript code to the $where field.

If you need to pass user-supplied values in a $where clause, you may escape these values with the CodeWScope mechanism. When you set user-submitted values as variables in the scope document, you can avoid evaluating them on the database server.

If you need to use db.eval() with user supplied values, you can either use a CodeWScope or you can supply extra arguments to your function. For instance:

db.eval(function(userVal){...},
        user_value);

This will ensure that your application sends user_value to the database server as data rather than code.

Dollar Sign Operator Escaping

Field names in MongoDB’s query language have semantic meaning. The dollar sign (i.e $) is a reserved character used to represent operators (i.e. $inc.) Thus, you should ensure that your application’s users cannot inject operators into their inputs.

In some cases, you may wish to build a BSON object with a user-provided key. In these situations, keys will need to substitute the reserved $ and . characters. Any character is sufficient, but consider using the Unicode full width equivalents: U+FF04 (i.e. “＄”) and U+FF0E (i.e. “．”).

Consider the following example:

BSONObj my_object = BSON( a_key << a_name );

The user may have supplied a $ value in the a_key value. At the same time, my_object might be { $where : "things" }. Consider the following cases:

Insert. Inserting this into the database does no harm. The insert process does not evaluate the object as a query.

Note

MongoDB client drivers, if properly implemented, check for reserved characters in keys on inserts.

Update. The update() operation permits $ operators in the update argument but does not support the $where operator. Still, some users may be able to inject operators that can manipulate a single document only. Therefore your application should escape keys, as mentioned above, if reserved characters are possible.

Query Generally this is not a problem for queries that resemble { x : user_obj }: dollar signs are not top level and have no effect. Theoretically it may be possible for the user to build a query themselves. But checking the user-submitted content for $ characters in key names may help protect against this kind of injection.

Driver-Specific Issues

See the “PHP MongoDB Driver Security Notes [http://us.php.net/manual/en/mongo.security.php]” page in the PHP driver documentation for more information

How does MongoDB provide concurrency?

MongoDB implements a readers-writer lock. This means that at any one time, only one client may be writing or any number of clients may be reading, but that reading and writing cannot occur simultaneously.

In standalone and replica sets the lock’s scope applies to a single mongod instance or primary instance. In a sharded cluster, locks apply to each individual shard, not to the whole cluster.

For more information, see FAQ: Concurrency.

What is the compare order for BSON types?

MongoDB permits documents within a single collection to have fields with different BSON types. For instance, the following documents may exist within a single collection.

{ x: "string" }
{ x: 42 }

When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:

MinKey (internal type)

Null

Numbers (ints, longs, doubles)

Symbol, String

Object

Array

BinData

ObjectId

Boolean

Date, Timestamp

Regular Expression

MaxKey (internal type)

MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.

The comparison treats a non-existent field as it would an empty BSON Object. As such, a sort on the a field in documents { } and { a: null } would treat the documents as equivalent in sort order.

With arrays, a less-than comparison or an ascending sort compares the smallest element of arrays, and a greater-than comparison or a descending sort compares the largest element of the arrays. As such, when comparing a field whose value is a single-element array (e.g. [ 1 ]) with non-array fields (e.g. 2), the comparison is between 1 and 2. A comparison of an empty array (e.g. [ ]) treats the empty array as less than null or a missing field.

MongoDB sorts BinData in the following order:

First, the length or size of the data.

Then, by the BSON one-byte subtype.

Finally, by the data, performing a byte-by-byte comparison.

Consider the following mongo example:

db.test.insert( {x : 3 } );
db.test.insert( {x : 2.9 } );
db.test.insert( {x : new Date() } );
db.test.insert( {x : true } );

db.test.find().sort({x:1});
{ "_id" : ObjectId("4b03155dce8de6586fb002c7"), "x" : 2.9 }
{ "_id" : ObjectId("4b03154cce8de6586fb002c6"), "x" : 3 }
{ "_id" : ObjectId("4b031566ce8de6586fb002c9"), "x" : true }
{ "_id" : ObjectId("4b031563ce8de6586fb002c8"), "x" : "Tue Nov 17 2009 16:28:03 GMT-0500 (EST)" }

The $type operator provides access to BSON type comparison in the MongoDB query syntax. See the documentation on BSON types and the $type operator for additional information.

Warning

Data models that associate a field name with different data types within a collection are strongly discouraged.

Without internal consistency complicates application code, and can lead to unnecessary complexity for application developers.

See also

The Tailable Cursors page for an example of a C++ use of MinKey.

When multiplying values of mixed types, what type conversion rules apply?

The $mul multiplies the numeric value of a field by a number. For multiplication with values of mixed numeric types (32-bit integer, 64-bit integer, float), the following type conversion rules apply:

| 32-bit Integer | 64-bit Integer | Float
32-bit Integer | 32-bit or 64-bit Integer | 64-bit Integer | Float
64-bit Integer | 64-bit Integer | 64-bit Integer | Float
Float | Float | Float | Float

Note

If the product of two 32-bit integers exceeds the maximum value for a 32-bit integer, the result is a 64-bit integer.

Integer operations of any type that exceed the maximum value for a 64-bit integer produce an error.

How do I query for fields that have null values?

Different query operators treat null values differently.

Consider the collection test with the following documents:

{ _id: 1, cancelDate: null }
{ _id: 2 }

Comparison with Null

The { cancelDate : null } query matches documents that either contain the cancelDate field whose value is null or that do not contain the cancelDate field. If the queried index is sparse, however, then the query will only match null values, not missing fields.

Changed in version 2.6: If using the sparse index results in an incomplete result, MongoDB will not use the index unless a hint() explicitly specifies the index. See Sparse Indexes for more information.

Given the following query:

db.test.find( { cancelDate: null } )

The query returns both documents:

{ "_id" : 1, "cancelDate" : null }
{ "_id" : 2 }

Type Check

The { cancelDate : { $type: 10 } } query matches documents that contains the cancelDate field whose value is null only; i.e. the value of the cancelDate field is of BSON Type Null (i.e. 10) :

db.test.find( { cancelDate : { $type: 10 } } )

The query returns only the document that contains the null value:

{ "_id" : 1, "cancelDate" : null }

Existence Check

The { cancelDate : { $exists: false } } query matches documents that do not contain the cancelDate field:

db.test.find( { cancelDate : { $exists: false } } )

The query returns only the document that does not contain the cancelDate field:

{ "_id" : 2 }

See also

The reference documentation for the $type and $exists operators.

Are there any restrictions on the names of Collections?

Collection names can be any UTF-8 string with the following exceptions:

A collection name should begin with a letter or an underscore.

The empty string ("") is not a valid collection name.

Collection names cannot contain the $ character. (version 2.2 only)

Collection names cannot contain the null character: \0

Do not name a collection using the system. prefix. MongoDB reserves system. for system collections, such as the system.indexes collection.

The maximum size of a collection name is 128 characters, including the name of the database. However, for maximum flexibility, collections should have names less than 80 characters.

If your collection name includes special characters, such as the underscore character, then to access the collection use the db.getCollection() method or a similar method for your driver [http://api.mongodb.org/].

Example

To create a collection _foo and insert the { a : 1 } document, use the following operation:

db.getCollection("_foo").insert( { a : 1 } )

To perform a query, use the find() method, in as the following:

db.getCollection("_foo").find()

How do I isolate cursors from intervening write operations?

MongoDB cursors can return the same document more than once in some situations. [3] You can use the snapshot() method on a cursor to isolate the operation for a very specific case.

snapshot() traverses the index on the _id field and guarantees that the query will return each document (with respect to the value of the _id field) no more than once. [4]

The snapshot() does not guarantee that the data returned by the query will reflect a single moment in time nor does it provide isolation from insert or delete operations.

Warning

You cannot use snapshot() with sharded collections.

You cannot use snapshot() with sort() or hint() cursor methods.

As an alternative, if your collection has a field or fields that are never modified, you can use a unique index on this field or these fields to achieve a similar result as the snapshot(). Query with hint() to explicitly force the query to use that index.

[3]
As a cursor returns documents other operations may interleave with the query: if some of these operations are updates that cause the document to move (in the case of a table scan, caused by document growth) or that change the indexed field on the index used by the query; then the cursor will return the same document more than once.

[4]
MongoDB does not permit changes to the value of the _id field; it is not possible for a cursor that transverses this index to pass the same document more than once.

When should I embed documents within other documents?

When modeling data in MongoDB, embedding is frequently the choice for:

“contains” relationships between entities.

one-to-many relationships when the “many” objects always appear with or are viewed in the context of their parents.

You should also consider embedding for performance reasons if you have a collection with a large number of small documents. Nevertheless, if small, separate documents represent the natural model for the data, then you should maintain that model.

If, however, you can group these small documents by some logical relationship and you frequently retrieve the documents by this grouping, you might consider “rolling-up” the small documents into larger documents that contain an array of embedded documents. Keep in mind that if you often only need to retrieve a subset of the documents within the group, then “rolling-up” the documents may not provide better performance.

“Rolling up” these small documents into logical groupings means that queries to retrieve a group of documents involve sequential reads and fewer random disk accesses.

Additionally, “rolling up” documents and moving common fields to the larger document benefit the index on these fields. There would be fewer copies of the common fields and there would be fewer associated key entries in the corresponding index. See Index Concepts for more information on indexes.

Where can I learn more about data modeling in MongoDB?

Begin by reading the documents in the Data Models section. These documents contain a high level introduction to data modeling considerations in addition to practical examples of data models targeted at particular issues.

Additionally, consider the following external resources that provide additional examples:

Schema Design by Example [http://www.mongodb.com/presentations/mongodb-melbourne-2012/schema-design-example]

Dynamic Schema Blog Post [http://dmerr.tumblr.com/post/6633338010/schemaless]

MongoDB Data Modeling and Rails [http://docs.mongodb.org/ecosystem/tutorial/model-data-for-ruby-on-rails/]

Ruby Example of Materialized Paths [http://github.com/banker/newsmonger/blob/master/app/models/comment.rb]

Sean Cribs Blog Post [http://seancribbs.com/tech/2009/09/28/modeling-a-tree-in-a-document-database] which was the source for much of the Model Tree Structures in MongoDB content.

Can I manually pad documents to prevent moves during updates?

An update can cause a document to move on disk if the document grows in size. To minimize document movements, MongoDB uses padding.

You should not have to pad manually because MongoDB adds padding automatically and can adaptively adjust the amount of padding added to documents to prevent document relocations following updates. You can change the default paddingFactor calculation by using the collMod command with the usePowerOf2Sizes flag. The usePowerOf2Sizes flag ensures that MongoDB allocates document space in sizes that are powers of 2, which helps ensure that MongoDB can efficiently reuse free space created by document deletion or relocation.

However, if you must pad a document manually, you can add a temporary field to the document and then $unset the field, as in the following example.

Warning

Do not manually pad documents in a capped collection. Applying manual padding to a document in a capped collection can break replication. Also, the padding is not preserved if you re-sync the MongoDB instance.

var myTempPadding = [ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"];

db.myCollection.insert( { _id: 5, paddingField: myTempPadding } );

db.myCollection.update( { _id: 5 },
                        { $unset: { paddingField: "" } }
                      )

db.myCollection.update( { _id: 5 },
                        { $set: { realField: "Some text that I might have needed padding for" } }
                      )

See also

Record Allocation Strategies

FAQ: The mongo Shell

How can I enter multi-line operations in the mongo shell?

If you end a line with an open parenthesis ('('), an open brace ('{'), or an open bracket ('['), then the subsequent lines start with ellipsis ("...") until you enter the corresponding closing parenthesis (')'), the closing brace ('}') or the closing bracket (']'). The mongo shell waits for the closing parenthesis, closing brace, or the closing bracket before evaluating the code, as in the following example:

> if ( x > 0 ) {
... count++;
... print (x);
... }

You can exit the line continuation mode if you enter two blank lines, as in the following example:

> if (x > 0
...
...
>

How can I access different databases temporarily?

You can use db.getSiblingDB() method to access another database without switching databases, as in the following example which first switches to the test database and then accesses the sampleDB database from the test database:

use test

db.getSiblingDB('sampleDB').getCollectionNames();

Does the mongo shell support tab completion and other keyboard shortcuts?

The mongo shell supports keyboard shortcuts. For example,

Use the up/down arrow keys to scroll through command history. See .dbshell documentation for more information on the .dbshell file.

Use <Tab> to autocomplete or to list the completion possibilities, as in the following example which uses <Tab> to complete the method name starting with the letter 'c':

db.myCollection.c<Tab>

Because there are many collection methods starting with the letter 'c', the <Tab> will list the various methods that start with 'c'.

For a full list of the shortcuts, see Shell Keyboard Shortcuts

How can I customize the mongo shell prompt?

New in version 1.9.

You can change the mongo shell prompt by setting the prompt variable. This makes it possible to display additional information in the prompt.

Set prompt to any string or arbitrary JavaScript code that returns a string, consider the following examples:

Set the shell prompt to display the hostname and the database issued:

var host = db.serverStatus().host;
var prompt = function() { return db+"@"+host+"> "; }

The mongo shell prompt should now reflect the new prompt:

test@my-machine.local>

Set the shell prompt to display the database statistics:

var prompt = function() {
                return "Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > ";
             }

The mongo shell prompt should now reflect the new prompt:

Uptime:1052 Documents:25024787 >

You can add the logic for the prompt in the .mongorc.js file to set the prompt each time you start up the mongo shell.

Can I edit long shell operations with an external text editor?

You can use your own editor in the mongo shell by setting the EDITOR environment variable before starting the mongo shell. Once in the mongo shell, you can edit with the specified editor by typing edit <variable> or edit <function>, as in the following example:

Set the EDITOR variable from the command line prompt:

EDITOR=vim

Start the mongo shell:

mongo

Define a function myFunction:

function myFunction () { }

Edit the function using your editor:

edit myFunction

The command should open the vim edit session. Remember to save your changes.

Type myFunction to see the function definition:

myFunction

The result should be the changes from your saved edit:

function myFunction() {
    print("This was edited");
}

FAQ: Concurrency

Changed in version 2.2.

MongoDB allows multiple clients to read and write a single corpus of data using a locking system to ensure that all clients receive the same view of the data and to prevent multiple applications from modifying the exact same pieces of data at the same time. Locks help guarantee that all writes to a single document occur either in full or not at all.

See also

Presentation on Concurrency and Internals in 2.2 [http://www.mongodb.com/presentations/concurrency-internals-mongodb-2-2]

What type of locking does MongoDB use?

MongoDB uses a readers-writer [1] lock that allows concurrent reads access to a database but gives exclusive access to a single write operation.

When a read lock exists, many read operations may use this lock. However, when a write lock exists, a single write operation holds the lock exclusively, and no other read or write operations may share the lock.

Locks are “writer greedy,” which means write locks have preference over reads. When both a read and write are waiting for a lock, MongoDB grants the lock to the write.

[1]
You may be familiar with a “readers-writer” lock as “multi-reader” or “shared exclusive” lock. See the Wikipedia page on Readers-Writer Locks [http://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock] for more information.

How granular are locks in MongoDB?

Changed in version 2.2.

Beginning with version 2.2, MongoDB implements locks on a per-database basis for most read and write operations. Some global operations, typically short lived operations involving multiple databases, still require a global “instance” wide lock. Before 2.2, there is only one “global” lock per mongod instance.

For example, if you have six databases and one takes a database-level write lock, the other five are still available for read and write. A global lock makes all six databases unavailable during the operation.

How do I see the status of locks on my mongod instances?

For reporting on lock utilization information on locks, use any of the following methods:

db.serverStatus(),

db.currentOp(),

mongotop,

mongostat, and/or

the MongoDB Management Service (MMS) [https://mms.mongodb.com/]

Specifically, the locks document in the output of serverStatus, or the locks field in the current operation reporting provides insight into the type of locks and amount of lock contention in your mongod instance.

To terminate an operation, use db.killOp().

Does a read or write operation ever yield the lock?

In some situations, read and write operations can yield their locks.

Long running read and write operations, such as queries, updates, and deletes, yield under many conditions. MongoDB uses an adaptive algorithms to allow operations to yield locks based on predicted disk access patterns (i.e. page faults.)

MongoDB operations can also yield locks between individual document modification in write operations that affect multiple documents like update() with the multi parameter.

MongoDB uses heuristics based on its access pattern to predict whether data is likely in physical memory before performing a read. If MongoDB predicts that the data is not in physical memory an operation will yield its lock while MongoDB loads the data to memory. Once data is available in memory, the operation will reacquire the lock to complete the operation.

Changed in version 2.6: MongoDB does not yield locks when scanning an index even if it predicts that the index is not in memory.

Which operations lock the database?

Changed in version 2.2.

The following table lists common database operations and the types of locks they use.

Operation
Lock Type

Issue a query
Read lock

Get more data from a cursor
Read lock

Insert data
Write lock

Remove data
Write lock

Update data
Write lock

Map-reduce
Read lock and write lock, unless operations are specified as non-atomic. Portions of map-reduce jobs can run concurrently.

Create an index
Building an index in the foreground, which is the default, locks the database for extended periods of time.

db.eval()
Write lock. The db.eval() method takes a global write lock while evaluating the JavaScript function. To avoid taking this global write lock, you can use the eval command with nolock: true.

eval
Write lock. By default, eval command takes a global write lock while evaluating the JavaScript function. If used with nolock: true, the eval command does not take a global write lock while evaluating the JavaScript function. However, the logic within the JavaScript function may take write locks for write operations.

aggregate()
Read lock

Which administrative commands lock the database?

Certain administrative commands can exclusively lock the database for extended periods of time. In some deployments, for large databases, you may consider taking the mongod instance offline so that clients are not affected. For example, if a mongod is part of a replica set, take the mongod offline and let other members of the set service load while maintenance is in progress.

The following administrative operations require an exclusive (i.e. write) lock on the database for extended periods:

db.collection.ensureIndex(), when issued without setting background to true,

reIndex,

compact,

db.repairDatabase(),

db.createCollection(), when creating a very large (i.e. many gigabytes) capped collection,

db.collection.validate(), and

db.copyDatabase(). This operation may lock all databases. See Does a MongoDB operation ever lock more than one database?.

The following administrative commands lock the database but only hold the lock for a very short time:

db.collection.dropIndex(),

db.getLastError(),

db.isMaster(),

rs.status() (i.e. replSetGetStatus),

db.serverStatus(),

db.auth(), and

db.addUser().

Does a MongoDB operation ever lock more than one database?

The following MongoDB operations lock multiple databases:

db.copyDatabase() must lock the entire mongod instance at once.

db.repairDatabase() obtains a global write lock and will block other operations until it finishes.

Journaling, which is an internal operation, locks all databases for short intervals. All databases share a single journal.

User authentication requires a read lock on the admin database for deployments using 2.6 user credentials. For deployments using the 2.4 schema for user credentials, authentication locks the admin database as well as the database the user is accessing.

All writes to a replica set’s primary lock both the database receiving the writes and then the local database for a short time. The lock for the local database allows the mongod to write to the primary’s oplog and accounts for a small portion of the total time of the operation.

How does sharding affect concurrency?

Sharding improves concurrency by distributing collections over multiple mongod instances, allowing shard servers (i.e. mongos processes) to perform any number of operations concurrently to the various downstream mongod instances.

Each mongod instance is independent of the others in the shard cluster and uses the MongoDB readers-writer lock. The operations on one mongod instance do not block the operations on any others.

How does concurrency affect a replica set primary?

In replication, when MongoDB writes to a collection on the primary, MongoDB also writes to the primary’s oplog, which is a special collection in the local database. Therefore, MongoDB must lock both the collection’s database and the local database. The mongod must lock both databases at the same time to keep the database consistent and ensure that write operations, even with replication, are “all-or-nothing” operations.

How does concurrency affect secondaries?

In replication, MongoDB does not apply writes serially to secondaries. Secondaries collect oplog entries in batches and then apply those batches in parallel. Secondaries do not allow reads while applying the write operations, and apply write operations in the order that they appear in the oplog.

MongoDB can apply several writes in parallel on replica set secondaries, in two phases:

During the first prefer phase, under a read lock, the mongod ensures that all documents affected by the operations are in memory. During this phase, other clients may execute queries against this member.

A thread pool using write locks applies all write operations in the batch as part of a coordinated write phase.

What kind of concurrency does MongoDB provide for JavaScript operations?

Changed in version 2.4: The V8 JavaScript engine added in 2.4 allows multiple JavaScript operations to run at the same time. Prior to 2.4, a single mongod could only run a single JavaScript operation at once.

FAQ: Sharding with MongoDB

This document answers common questions about horizontal scaling using MongoDB’s sharding.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

Is sharding appropriate for a new deployment?

Sometimes.

If your data set fits on a single server, you should begin with an unsharded deployment.

Converting an unsharded database to a sharded cluster is easy and seamless, so there is little advantage in configuring sharding while your data set is small.

Still, all production deployments should use replica sets to provide high availability and disaster recovery.

How does sharding work with replication?

To use replication with sharding, deploy each shard as a replica set.

Can I change the shard key after sharding a collection?

No.

There is no automatic support in MongoDB for changing a shard key after sharding a collection. This reality underscores the importance of choosing a good shard key. If you must change a shard key after sharding a collection, the best option is to:

dump all data from MongoDB into an external format.

drop the original sharded collection.

configure sharding using a more ideal shard key.

pre-split the shard key range to ensure initial even distribution.

restore the dumped data into MongoDB.

See shardCollection, sh.shardCollection(), the Shard Key, Deploy a Sharded Cluster, and SERVER-4000 [https://jira.mongodb.org/browse/SERVER-4000] for more information.

What happens to unsharded collections in sharded databases?

In the current implementation, all databases in a sharded cluster have a “primary shard.” All unsharded collection within that database will reside on the same shard.

How does MongoDB distribute data across shards?

Sharding must be specifically enabled on a collection. After enabling sharding on the collection, MongoDB will assign various ranges of collection data to the different shards in the cluster. The cluster automatically corrects imbalances between shards by migrating ranges of data from one shard to another.

What happens if a client updates a document in a chunk during a migration?

The mongos routes the operation to the “old” shard, where it will succeed immediately. Then the shard mongod instances will replicate the modification to the “new” shard before the sharded cluster updates that chunk’s “ownership,” which effectively finalizes the migration process.

What happens to queries if a shard is inaccessible or slow?

If a shard is inaccessible or unavailable, queries will return with an error.

However, a client may set the partial query bit, which will then return results from all available shards, regardless of whether a given shard is unavailable.

If a shard is responding slowly, mongos will merely wait for the shard to return results.

How does MongoDB distribute queries among shards?

Changed in version 2.0.

The exact method for distributing queries to shards in a cluster depends on the nature of the query and the configuration of the sharded cluster. Consider a sharded collection, using the shard key user_id, that has last_login and email attributes:

For a query that selects one or more values for the user_id key:

mongos determines which shard or shards contains the relevant data, based on the cluster metadata, and directs a query to the required shard or shards, and returns those results to the client.

For a query that selects user_id and also performs a sort:

mongos can make a straightforward translation of this operation into a number of queries against the relevant shards, ordered by user_id. When the sorted queries return from all shards, the mongos merges the sorted results and returns the complete result to the client.

For queries that select on last_login:

These queries must run on all shards: mongos must parallelize the query over the shards and perform a merge-sort on the email of the documents found.

How does MongoDB sort queries in sharded environments?

If you call the cursor.sort() method on a query in a sharded environment, the mongod for each shard will sort its results, and the mongos merges each shard’s results before returning them to the client.

How does MongoDB ensure unique _id field values when using a shard key other than _id?

If you do not use _id as the shard key, then your application/client layer must be responsible for keeping the _id field unique. It is problematic for collections to have duplicate _id values.

If you’re not sharding your collection by the _id field, then you should be sure to store a globally unique identifier in that field. The default BSON ObjectId works well in this case.

I’ve enabled sharding and added a second shard, but all the data is still on one server. Why?

First, ensure that you’ve declared a shard key for your collection. Until you have configured the shard key, MongoDB will not create chunks, and sharding will not occur.

Next, keep in mind that the default chunk size is 64 MB. As a result, in most situations, the collection needs to have at least 64 MB of data before a migration will occur.

Additionally, the system which balances chunks among the servers attempts to avoid superfluous migrations. Depending on the number of shards, your shard key, and the amount of data, systems often require at least 10 chunks of data to trigger migrations.

You can run db.printShardingStatus() to see all the chunks present in your cluster.

Is it safe to remove old files in the moveChunk directory?

Yes. mongod creates these files as backups during normal shard balancing operations. If some error occurs during a migration, these files may be helpful in recovering documents affected during the migration.

Once the migration has completed successfully and there is no need to recover documents from these files, you may safely delete these files. Or, if you have an existing backup of the database that you can use for recovery, you may also delete these files after migration.

To determine if all migrations are complete, run sh.isBalancerRunning() while connected to a mongos instance.

How does mongos use connections?

Each client maintains a connection to a mongos instance. Each mongos instance maintains a pool of connections to the members of a replica set supporting the sharded cluster. Clients use connections between mongos and mongod instances one at a time. Requests are not multiplexed or pipelined. When client requests complete, the mongos returns the connection to the pool.

See the System Resource Utilization section of the UNIX ulimit Settings document.

Why does mongos hold connections open?

mongos uses a set of connection pools to communicate with each shard. These pools do not shrink when the number of clients decreases.

This can lead to an unused mongos with a large number of open connections. If the mongos is no longer in use, it is safe to restart the process to close existing connections.

Where does MongoDB report on connections used by mongos?

Connect to the mongos with the mongo shell, and run the following command:

db._adminCommand("connPoolStats");

What does writebacklisten in the log mean?

The writeback listener is a process that opens a long poll to relay writes back from a mongod or mongos after migrations to make sure they have not gone to the wrong server. The writeback listener sends writes back to the correct server if necessary.

These messages are a key part of the sharding infrastructure and should not cause concern.

How should administrators deal with failed migrations?

Failed migrations require no administrative intervention. Chunk migrations always preserve a consistent state. If a migration fails to complete for some reason, the cluster retries the operation. When the migration completes successfully, the data resides only on the new shard.

What is the process for moving, renaming, or changing the number of config servers?

See Sharded Cluster Tutorials for information on migrating and replacing config servers.

When do the mongos servers detect config server changes?

mongos instances maintain a cache of the config database that holds the metadata for the sharded cluster. This metadata includes the mapping of chunks to shards.

mongos updates its cache lazily by issuing a request to a shard and discovering that its metadata is out of date. There is no way to control this behavior from the client, but you can run the flushRouterConfig command against any mongos to force it to refresh its cache.

Is it possible to quickly update mongos servers after updating a replica set configuration?

The mongos instances will detect these changes without intervention over time. However, if you want to force the mongos to reload its configuration, run the flushRouterConfig command against to each mongos directly.

What does the maxConns setting on mongos do?

The maxIncomingConnections option limits the number of connections accepted by mongos.

If your client driver or application creates a large number of connections but allows them to time out rather than closing them explicitly, then it might make sense to limit the number of connections at the mongos layer.

Set maxIncomingConnections to a value slightly higher than the maximum number of connections that the client creates, or the maximum size of the connection pool. This setting prevents the mongos from causing connection spikes on the individual shards. Spikes like these may disrupt the operation and memory allocation of the sharded cluster.

How do indexes impact queries in sharded systems?

If the query does not include the shard key, the mongos must send the query to all shards as a “scatter/gather” operation. Each shard will, in turn, use either the shard key index or another more efficient index to fulfill the query.

If the query includes multiple sub-expressions that reference the fields indexed by the shard key and the secondary index, the mongos can route the queries to a specific shard and the shard will use the index that will allow it to fulfill most efficiently. See this presentation [http://www.slideshare.net/mongodb/how-queries-work-with-sharding] for more information.

Can shard keys be randomly generated?

Shard keys can be random. Random keys ensure optimal distribution of data across the cluster.

Sharded clusters, attempt to route queries to specific shards when queries include the shard key as a parameter, because these directed queries are more efficient. In many cases, random keys can make it difficult to direct queries to specific shards.

Can shard keys have a non-uniform distribution of values?

Yes. There is no requirement that documents be evenly distributed by the shard key.

However, documents that have the same shard key must reside in the same chunk and therefore on the same server. If your sharded data set has too many documents with the exact same shard key you will not be able to distribute those documents across your sharded cluster.

Can you shard on the _id field?

You can use any field for the shard key. The _id field is a common shard key.

Be aware that ObjectId() values, which are the default value of the _id field, increment as a timestamp. As a result, when used as a shard key, all new documents inserted into the collection will initially belong to the same chunk on a single shard. Although the system will eventually divide this chunk and migrate its contents to distribute data more evenly, at any moment the cluster can only direct insert operations at a single shard. This can limit the throughput of inserts. If most of your write operations are updates, this limitation should not impact your performance. However, if you have a high insert volume, this may be a limitation.

To address this issue, MongoDB 2.4 provides hashed shard keys.

What do moveChunk commit failed errors mean?

At the end of a chunk migration, the shard must connect to the config database to update the chunk’s record in the cluster metadata. If the shard fails to connect to the config database, MongoDB reports the following error:

ERROR: moveChunk commit failed: version is at <n>|<nn> instead of
<N>|<NN>" and "ERROR: TERMINATING"

When this happens, the primary member of the shard’s replica set then terminates to protect data consistency. If a secondary member can access the config database, data on the shard becomes accessible again after an election.

The user will need to resolve the chunk migration failure independently. If you encounter this issue, contact the MongoDB User Group [http://groups.google.com/group/mongodb-user] or MongoDB Support [http://www.mongodb.org/about/support] to address this issue.

How does draining a shard affect the balancing of uneven chunk distribution?

The sharded cluster balancing process controls both migrating chunks from decommissioned shards (i.e. draining) and normal cluster balancing activities. Consider the following behaviors for different versions of MongoDB in situations where you remove a shard in a cluster with an uneven chunk distribution:

After MongoDB 2.2, the balancer first removes the chunks from the draining shard and then balances the remaining uneven chunk distribution.

Before MongoDB 2.2, the balancer handles the uneven chunk distribution and then removes the chunks from the draining shard.

FAQ: Replication and Replica Sets

This document answers common questions about database replication in MongoDB.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

What kinds of replication does MongoDB support?

MongoDB supports master-slave replication and a variation on master-slave replication known as replica sets. Replica sets are the recommended replication topology.

What do the terms “primary” and “master” mean?

Primary and master nodes are the nodes that can accept writes. MongoDB’s replication is “single-master:” only one node can accept write operations at a time.

In a replica set, if the current “primary” node fails or becomes inaccessible, the other members can autonomously elect one of the other members of the set to be the new “primary”.

By default, clients send all reads to the primary; however, read preference is configurable at the client level on a per-connection basis, which makes it possible to send reads to secondary nodes instead.

What do the terms “secondary” and “slave” mean?

Secondary and slave nodes are read-only nodes that replicate from the primary.

Replication operates by way of an oplog, from which secondary/slave members apply new operations to themselves. This replication process is asynchronous, so secondary/slave nodes may not always reflect the latest writes to the primary. But usually, the gap between the primary and secondary nodes is just few milliseconds on a local network connection.

How long does replica set failover take?

It varies, but a replica set will select a new primary within a minute.

It may take 10-30 seconds for the members of a replica set to declare a primary inaccessible. This triggers an election. During the election, the cluster is unavailable for writes.

The election itself may take another 10-30 seconds.

Note

Eventually consistent reads, like the ones that will return from a replica set are only possible with a write concern that permits reads from secondary members.

Does replication work over the Internet and WAN connections?

Yes.

For example, a deployment may maintain a primary and secondary in an East-coast data center along with a secondary member for disaster recovery in a West-coast data center.

See also

Deploy a Geographically Redundant Replica Set

Can MongoDB replicate over a “noisy” connection?

Yes, but not without connection failures and the obvious latency.

Members of the set will attempt to reconnect to the other members of the set in response to networking flaps. This does not require administrator intervention. However, if the network connections among the nodes in the replica set are very slow, it might not be possible for the members of the node to keep up with the replication.

If the TCP connection between the secondaries and the primary instance breaks, a replica set will automatically elect one of the secondary members of the set as primary.

What is the preferred replication method: master/slave or replica sets?

New in version 1.8.

Replica sets are the preferred replication mechanism in MongoDB. However, if your deployment requires more than 12 nodes, you must use master/slave replication.

What is the preferred replication method: replica sets or replica pairs?

Deprecated since version 1.6.

Replica sets replaced replica pairs in version 1.6. Replica sets are the preferred replication mechanism in MongoDB.

Why use journaling if replication already provides data redundancy?

Journaling facilitates faster crash recovery. Prior to journaling, crashes often required database repairs or full data resync. Both were slow, and the first was unreliable.

Journaling is particularly useful for protection against power failures, especially if your replica set resides in a single data center or power circuit.

When a replica set runs with journaling, mongod instances can safely restart without any administrator intervention.

Note

Journaling requires some resource overhead for write operations. Journaling has no effect on read performance, however.

Journaling is enabled by default on all 64-bit builds of MongoDB v2.0 and greater.

Are write operations durable if write concern does not acknowledge writes?

Yes.

However, if you want confirmation that a given write has arrived at the server, use write concern.

After the default write concern change, the default write concern acknowledges all write operations, and unacknowledged writes must be explicitly configured. See the MongoDB Drivers and Client Libraries documentation for your driver for more information.

Changed in version 2.6: The mongo shell now defaults to use safe writes. See Write Method Acknowledgements for more information.

A new protocol for write operations integrates write concerns with the write operations. Previous versions issued a getLastError command after a write to specify a write concern.

How many arbiters do replica sets need?

Some configurations do not require any arbiter instances. Arbiters vote in elections for primary but do not replicate the data like secondary members.

Replica sets require a majority of the remaining nodes present to elect a primary. Arbiters allow you to construct this majority without the overhead of adding replicating nodes to the system.

There are many possible replica set architectures.

A replica set with an odd number of voting nodes does not need an arbiter.

A common configuration consists of two replicating nodes that include a primary and a secondary, as well as an arbiter for the third node. This configuration makes it possible for the set to elect a primary in the event of failure, without requiring three replicating nodes.

You may also consider adding an arbiter to a set if it has an equal number of nodes in two facilities and network partitions between the facilities are possible. In these cases, the arbiter will break the tie between the two facilities and allow the set to elect a new primary.

See also

Replica Set Deployment Architectures

What information do arbiters exchange with the rest of the replica set?

Arbiters never receive the contents of a collection but do exchange the following data with the rest of the replica set:

Credentials used to authenticate the arbiter with the replica set. All MongoDB processes within a replica set use keyfiles. These exchanges are encrypted.

Replica set configuration data and voting data. This information is not encrypted. Only credential exchanges are encrypted.

If your MongoDB deployment uses SSL, then all communications between arbiters and the other members of the replica set are secure. See the documentation for Configure mongod and mongos for SSL for more information. Run all arbiters on secure networks, as with all MongoDB components.

See

The overview of Arbiter Members of Replica Sets.

Which members of a replica set vote in elections?

All members of a replica set, unless the value of votes is equal to 0, vote in elections. This includes all delayed, hidden and secondary-only members, as well as the arbiters.

Additionally, the state of the voting members also determine whether the member can vote. Only voting members in the following states are eligible to vote:

PRIMARY

SECONDARY

RECOVERING

ARBITER

ROLLBACK

See also

Replica Set Elections

Do hidden members vote in replica set elections?

Hidden members of replica sets do vote in elections. To exclude a member from voting in an election, change the value of the member’s votes configuration to 0.

See also

Replica Set Elections

Is it normal for replica set members to use different amounts of disk space?

Yes.

Factors including: different oplog sizes, different levels of storage fragmentation, and MongoDB’s data file pre-allocation can lead to some variation in storage utilization between nodes. Storage use disparities will be most pronounced when you add members at different times.

FAQ: MongoDB Storage

This document addresses common questions regarding MongoDB’s storage system.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

What are memory mapped files?

A memory-mapped file is a file with data that the operating system places in memory by way of the mmap() system call. mmap() thus maps the file to a region of virtual memory. Memory-mapped files are the critical piece of the storage engine in MongoDB. By using memory mapped files MongoDB can treat the contents of its data files as if they were in memory. This provides MongoDB with an extremely fast and simple method for accessing and manipulating data.

How do memory mapped files work?

Memory mapping assigns files to a block of virtual memory with a direct byte-for-byte correlation. Once mapped, the relationship between file and memory allows MongoDB to interact with the data in the file as if it were memory.

How does MongoDB work with memory mapped files?

MongoDB uses memory mapped files for managing and interacting with all data. MongoDB memory maps data files to memory as it accesses documents. Data that isn’t accessed is not mapped to memory.

What are page faults?

Page faults can occur as MongoDB reads from or writes data to parts of its data files that are not currently located in physical memory. In contrast, operating system page faults happen when physical memory is exhausted and pages of physical memory are swapped to disk.

If there is free memory, then the operating system can find the page on disk and load it to memory directly. However, if there is no free memory, the operating system must:

find a page in memory that is stale or no longer needed, and write the page to disk.

read the requested page from disk and load it into memory.

This process, particularly on an active system can take a long time, particularly in comparison to reading a page that is already in memory.

See Page Faults for more information.

What is the difference between soft and hard page faults?

Page faults occur when MongoDB needs access to data that isn’t currently in active memory. A “hard” page fault refers to situations when MongoDB must access a disk to access the data. A “soft” page fault, by contrast, merely moves memory pages from one list to another, such as from an operating system file cache. In production, MongoDB will rarely encounter soft page faults.

See Page Faults for more information.

What tools can I use to investigate storage use in MongoDB?

The db.stats() method in the mongo shell, returns the current state of the “active” database. The dbStats command document describes the fields in the db.stats() output.

What is the working set?

Working set represents the total body of data that the application uses in the course of normal operation. Often this is a subset of the total data size, but the specific size of the working set depends on actual moment-to-moment use of the database.

If you run a query that requires MongoDB to scan every document in a collection, the working set will expand to include every document. Depending on physical memory size, this may cause documents in the working set to “page out,” or to be removed from physical memory by the operating system. The next time MongoDB needs to access these documents, MongoDB may incur a hard page fault.

If you run a query that requires MongoDB to scan every document in a collection, the working set includes every active document in memory.

For best performance, the majority of your active set should fit in RAM.

Why are the files in my data directory larger than the data in my database?

The data files in your data directory, which is the /data/db directory in default configurations, might be larger than the data set inserted into the database. Consider the following possible causes:

Preallocated data files.

In the data directory, MongoDB preallocates data files to a particular size, in part to prevent file system fragmentation. MongoDB names the first data file <databasename>.0, the next <databasename>.1, etc. The first file mongod allocates is 64 megabytes, the next 128 megabytes, and so on, up to 2 gigabytes, at which point all subsequent files are 2 gigabytes. The data files include files with allocated space but that hold no data. mongod may allocate a 1 gigabyte data file that may be 90% empty. For most larger databases, unused allocated space is small compared to the database.

The oplog.

If this mongod is a member of a replica set, the data directory includes the oplog.rs file, which is a preallocated capped collection in the local database. The default allocation is approximately 5% of disk space on 64-bit installations, see Oplog Sizing for more information. In most cases, you should not need to resize the oplog. However, if you do, see Change the Size of the Oplog.

The journal.

The data directory contains the journal files, which store write operations on disk prior to MongoDB applying them to databases. See Journaling Mechanics.

Empty records.

MongoDB maintains lists of empty records in data files when deleting documents and collections. MongoDB can reuse this space, but will never return this space to the operating system.

To de-fragment allocated storage, use compact, which de-fragments allocated space. By de-fragmenting storage, MongoDB can effectively use the allocated space. compact requires up to 2 gigabytes of extra disk space to run. Do not use compact if you are critically low on disk space.

Important

compact only removes fragmentation from MongoDB data files and does not return any disk space to the operating system.

To reclaim deleted space, use repairDatabase, which rebuilds the database which de-fragments the storage and may release space to the operating system. repairDatabase requires up to 2 gigabytes of extra disk space to run. Do not use repairDatabase if you are critically low on disk space.

Warning

repairDatabase requires enough free disk space to hold both the old and new database files while the repair is running. Be aware that repairDatabase will block all other operations and may take a long time to complete.

How can I check the size of a collection?

To view the size of a collection and other information, use the db.collection.stats() method from the mongo shell. The following example issues db.collection.stats() for the orders collection:

db.orders.stats();

To view specific measures of size, use these methods:

db.collection.dataSize(): data size in bytes for the collection.

db.collection.storageSize(): allocation size in bytes, including unused space.

db.collection.totalSize(): the data size plus the index size in bytes.

db.collection.totalIndexSize(): the index size in bytes.

Also, the following scripts print the statistics for each database and collection:

db._adminCommand("listDatabases").databases.forEach(function (d) {mdb = db.getSiblingDB(d.name); printjson(mdb.stats())})

db._adminCommand("listDatabases").databases.forEach(function (d) {mdb = db.getSiblingDB(d.name); mdb.getCollectionNames().forEach(function(c) {s = mdb[c].stats(); printjson(s)})})

How can I check the size of indexes?

To view the size of the data allocated for an index, use one of the following procedures in the mongo shell:

Use the db.collection.stats() method using the index namespace. To retrieve a list of namespaces, issue the following command:

db.system.namespaces.find()

Check the value of indexSizes in the output of the db.collection.stats() command.

Example

Issue the following command to retrieve index namespaces:

db.system.namespaces.find()

The command returns a list similar to the following:

{"name" : "test.orders"}
{"name" : "test.system.indexes"}
{"name" : "test.orders.$_id_"}

View the size of the data allocated for the orders.$_id_ index with the following sequence of operations:

use test
db.orders.$_id_.stats().indexSizes

How do I know when the server runs out of disk space?

If your server runs out of disk space for data files, you will see something like this in the log:

Thu Aug 11 13:06:09 [FileAllocator] allocating new data file dbms/test.13, filling with zeroes...
Thu Aug 11 13:06:09 [FileAllocator] error failed to allocate new file: dbms/test.13 size: 2146435072 errno:28 No space left on device
Thu Aug 11 13:06:09 [FileAllocator]     will try again in 10 seconds
Thu Aug 11 13:06:19 [FileAllocator] allocating new data file dbms/test.13, filling with zeroes...
Thu Aug 11 13:06:19 [FileAllocator] error failed to allocate new file: dbms/test.13 size: 2146435072 errno:28 No space left on device
Thu Aug 11 13:06:19 [FileAllocator]     will try again in 10 seconds

The server remains in this state forever, blocking all writes including deletes. However, reads still work. To delete some data and compact, using the compact command, you must restart the server first.

If your server runs out of disk space for journal files, the server process will exit. By default, mongod creates journal files in a sub-directory of dbPath named journal. You may elect to put the journal files on another storage device using a filesystem mount or a symlink.

Note

If you place the journal files on a separate storage device you will not be able to use a file system snapshot tool to capture a valid snapshot of your data files and journal files.

FAQ: Indexes

This document addresses common questions regarding MongoDB indexes.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user]. See also Indexing Tutorials.

Should you run ensureIndex() after every insert?

No. You only need to create an index once for a single collection. After initial creation, MongoDB automatically updates the index as data changes.

While running ensureIndex() is usually ok, if an index doesn’t exist because of ongoing administrative work, a call to ensureIndex() may disrupt database availability. Running ensureIndex() can render a replica set inaccessible as the index creation is happening. See Build Indexes on Replica Sets.

How do you know what indexes exist in a collection?

To list a collection’s indexes, use the db.collection.getIndexes() method or a similar method for your driver [http://api.mongodb.org/].

How do you determine the size of an index?

To check the sizes of the indexes on a collection, use db.collection.stats().

What happens if an index does not fit into RAM?

When an index is too large to fit into RAM, MongoDB must read the index from disk, which is a much slower operation than reading from RAM. Keep in mind an index fits into RAM when your server has RAM available for the index combined with the rest of the working set.

In certain cases, an index does not need to fit entirely into RAM. For details, see Indexes that Hold Only Recent Values in RAM.

How do you know what index a query used?

To inspect how MongoDB processes a query, use the explain() method in the mongo shell, or in your application driver.

How do you determine what fields to index?

A number of factors determine what fields to index, including selectivity, fitting indexes into RAM, reusing indexes in multiple queries when possible, and creating indexes that can support all the fields in a given query. For detailed documentation on choosing which fields to index, see Indexing Tutorials.

How do write operations affect indexes?

Any write operation that alters an indexed field requires an update to the index in addition to the document itself. If you update a document that causes the document to grow beyond the allotted record size, then MongoDB must update all indexes that include this document as part of the update operation.

Therefore, if your application is write-heavy, creating too many indexes might affect performance.

Will building a large index affect database performance?

Building an index can be an IO-intensive operation, especially if you have a large collection. This is true on any database system that supports secondary indexes, including MySQL. If you need to build an index on a large collection, consider building the index in the background. See Index Creation.

If you build a large index without the background option, and if doing so causes the database to stop responding, do one of the following:

Wait for the index to finish building.

Kill the current operation (see db.killOp()). The partial index will be deleted.

Can I use index keys to constrain query matches?

You can use the min() and max() methods to constrain the results of the cursor returned from find() by using index keys.

Using $ne and $nin in a query is slow. Why?

The $ne and $nin operators are not selective. See Create Queries that Ensure Selectivity. If you need to use these, it is often best to make sure that an additional, more selective criterion is part of the query.

Can I use a multi-key index to support a query for a whole array?

Not entirely. The index can partially support these queries because it can speed the selection of the first element of the array; however, comparing all subsequent items in the array cannot use the index and must scan the documents individually.

How can I effectively use indexes strategy for attribute lookups?

For simple attribute lookups that don’t require sorted result sets or range queries, consider creating a field that contains an array of documents where each document has a field (e.g. attrib ) that holds a specific type of attribute. You can index this attrib field.

For example, the attrib field in the following document allows you to add an unlimited number of attributes types:

{ _id : ObjectId(...),
  attrib : [
            { k: "color", v: "red" },
            { k: "shape": v: "rectangle" },
            { k: "color": v: "blue" },
            { k: "avail": v: true }
           ]
}

Both of the following queries could use the same { "attrib.k": 1, "attrib.v": 1 } index:

db.mycollection.find( { attrib: { $elemMatch : { k: "color", v: "blue" } } } )
db.mycollection.find( { attrib: { $elemMatch : { k: "avail", v: true } } } )

FAQ: MongoDB Diagnostics

This document provides answers to common diagnostic questions and issues.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB User Mailing List [https://groups.google.com/forum/?fromgroups#!forum/mongodb-user].

Where can I find information about a mongod process that stopped running unexpectedly?

If mongod shuts down unexpectedly on a UNIX or UNIX-based platform, and if mongod fails to log a shutdown or error message, then check your system logs for messages pertaining to MongoDB. For example, for logs located in /var/log/messages, use the following commands:

sudo grep mongod /var/log/messages
sudo grep score /var/log/messages

Does TCP keepalive time affect sharded clusters and replica sets?

If you experience socket errors between members of a sharded cluster or replica set, that do not have other reasonable causes, check the TCP keep alive value, which Linux systems store as the tcp_keepalive_time value. A common keep alive period is 7200 seconds (2 hours); however, different distributions and OS X may have different settings. For MongoDB, you will have better experiences with shorter keepalive periods, on the order of 300 seconds (five minutes).

On Linux systems you can use the following operation to check the value of tcp_keepalive_time:

cat /proc/sys/net/ipv4/tcp_keepalive_time

You can change the tcp_keepalive_time value with the following operation:

echo 300 > /proc/sys/net/ipv4/tcp_keepalive_time

The new tcp_keepalive_time value takes effect without requiring you to restart the mongod or mongos servers. When you reboot or restart your system you will need to set the new tcp_keepalive_time value, or see your operating system’s documentation for setting the TCP keepalive value persistently.

For OS X systems, issue the following command to view the keep alive setting:

sysctl net.inet.tcp.keepinit

To set a shorter keep alive period use the following invocation:

sysctl -w net.inet.tcp.keepinit=300

If your replica set or sharded cluster experiences keepalive-related issues, you must alter the tcp_keepalive_time value on all machines hosting MongoDB processes. This includes all machines hosting mongos or mongod servers.

Windows users should consider the Windows Server Technet Article on KeepAliveTime configuration [http://technet.microsoft.com/en-us/library/dd349797.aspx#BKMK_2] for more information on setting keep alive for MongoDB deployments on Windows systems.

What tools are available for monitoring MongoDB?

The MongoDB Management Service [https://mms.mongodb.com/] includes monitoring functionality, which collects data from running MongoDB deployments and provides visualization and alerts based on that data.

A full list of third-party tools is available as part of the Monitoring for MongoDB documentation. Also consider the MMS Documentation [https://docs.mms.mongodb.com/].

Memory Diagnostics

Do I need to configure swap space?

Always configure systems to have swap space. Without swap, your system may not be reliant in some situations with extreme memory constraints, memory leaks, or multiple programs using the same memory. Think of the swap space as something like a steam release valve that allows the system to release extra pressure without affecting the overall functioning of the system.

Nevertheless, systems running MongoDB do not need swap for routine operation. Database files are memory-mapped and should constitute most of your MongoDB memory use. Therefore, it is unlikely that mongod will ever use any swap space in normal operation. The operating system will release memory from the memory mapped files without needing swap and MongoDB can write data to the data files without needing the swap system.

What is “working set” and how can I estimate its size?

The working set for a MongoDB database is the portion of your data that clients access most often. You can estimate size of the working set, using the workingSet document in the output of serverStatus. To return serverStatus with the workingSet document, issue a command in the following form:

db.runCommand( { serverStatus: 1, workingSet: 1 } )

Must my working set size fit RAM?

Your working set should stay in memory to achieve good performance. Otherwise many random disk IO’s will occur, and unless you are using SSD, this can be quite slow.

One area to watch specifically in managing the size of your working set is index access patterns. If you are inserting into indexes at random locations (as would happen with id’s that are randomly generated by hashes), you will continually be updating the whole index. If instead you are able to create your id’s in approximately ascending order (for example, day concatenated with a random id), all the updates will occur at the right side of the b-tree and the working set size for index pages will be much smaller.

It is fine if databases and thus virtual size are much larger than RAM.

How do I calculate how much RAM I need for my application?

The amount of RAM you need depends on several factors, including but not limited to:

The relationship between database storage and working set.

The operating system’s cache strategy for LRU (Least Recently Used)

The impact of journaling

The number or rate of page faults and other MMS gauges to detect when you need more RAM

Each database connection thread will need up to 1 MB of RAM.

MongoDB defers to the operating system when loading data into memory from disk. It simply memory maps all its data files and relies on the operating system to cache data. The OS typically evicts the least-recently-used data from RAM when it runs low on memory. For example if clients access indexes more frequently than documents, then indexes will more likely stay in RAM, but it depends on your particular usage.

To calculate how much RAM you need, you must calculate your working set size, or the portion of your data that clients use most often. This depends on your access patterns, what indexes you have, and the size of your documents. Because MongoDB uses a thread per connection model, each database connection also will need up to 1MB of RAM, whether active or idle.

If page faults are infrequent, your working set fits in RAM. If fault rates rise higher than that, you risk performance degradation. This is less critical with SSD drives than with spinning disks.

How do I read memory statistics in the UNIX top command

Because mongod uses memory-mapped files, the memory statistics in top require interpretation in a special way. On a large database, VSIZE (virtual bytes) tends to be the size of the entire database. If the mongod doesn’t have other processes running, RSIZE (resident bytes) is the total memory of the machine, as this counts file system cache contents.

For Linux systems, use the vmstat command to help determine how the system uses memory. On OS X systems use vm_stat.

Sharded Cluster Diagnostics

The two most important factors in maintaining a successful sharded cluster are:

choosing an appropriate shard key and

sufficient capacity to support current and future operations.

You can prevent most issues encountered with sharding by ensuring that you choose the best possible shard key for your deployment and ensure that you are always adding additional capacity to your cluster well before the current resources become saturated. Continue reading for specific issues you may encounter in a production environment.

In a new sharded cluster, why does all data remains on one shard?

Your cluster must have sufficient data for sharding to make sense. Sharding works by migrating chunks between the shards until each shard has roughly the same number of chunks.

The default chunk size is 64 megabytes. MongoDB will not begin migrations until the imbalance of chunks in the cluster exceeds the migration threshold. While the default chunk size is configurable with the chunkSize setting, these behaviors help prevent unnecessary chunk migrations, which can degrade the performance of your cluster as a whole.

If you have just deployed a sharded cluster, make sure that you have enough data to make sharding effective. If you do not have sufficient data to create more than eight 64 megabyte chunks, then all data will remain on one shard. Either lower the chunk size setting, or add more data to the cluster.

As a related problem, the system will split chunks only on inserts or updates, which means that if you configure sharding and do not continue to issue insert and update operations, the database will not create any chunks. You can either wait until your application inserts data or split chunks manually.

Finally, if your shard key has a low cardinality, MongoDB may not be able to create sufficient splits among the data.

Why would one shard receive a disproportion amount of traffic in a sharded cluster?

In some situations, a single shard or a subset of the cluster will receive a disproportionate portion of the traffic and workload. In almost all cases this is the result of a shard key that does not effectively allow write scaling.

It’s also possible that you have “hot chunks.” In this case, you may be able to solve the problem by splitting and then migrating parts of these chunks.

In the worst case, you may have to consider re-sharding your data and choosing a different shard key to correct this pattern.

What can prevent a sharded cluster from balancing?

If you have just deployed your sharded cluster, you may want to consider the troubleshooting suggestions for a new cluster where data remains on a single shard.

If the cluster was initially balanced, but later developed an uneven distribution of data, consider the following possible causes:

You have deleted or removed a significant amount of data from the cluster. If you have added additional data, it may have a different distribution with regards to its shard key.

Your shard key has low cardinality and MongoDB cannot split the chunks any further.

Your data set is growing faster than the balancer can distribute data around the cluster. This is uncommon and typically is the result of:

a balancing window that is too short, given the rate of data growth.

an uneven distribution of write operations that requires more data migration. You may have to choose a different shard key to resolve this issue.

poor network connectivity between shards, which may lead to chunk migrations that take too long to complete. Investigate your network configuration and interconnections between shards.

Why do chunk migrations affect sharded cluster performance?

If migrations impact your cluster or application’s performance, consider the following options, depending on the nature of the impact:

If migrations only interrupt your clusters sporadically, you can limit the balancing window to prevent balancing activity during peak hours. Ensure that there is enough time remaining to keep the data from becoming out of balance again.

If the balancer is always migrating chunks to the detriment of overall cluster performance:

You may want to attempt decreasing the chunk size to limit the size of the migration.

Your cluster may be over capacity, and you may want to attempt to add one or two shards to the cluster to distribute load.

It’s also possible that your shard key causes your application to direct all writes to a single shard. This kind of activity pattern can require the balancer to migrate most data soon after writing it. Consider redeploying your cluster with a shard key that provides better write scaling.

Reference

Operators

Documentation of query, update, projection, and aggregation framework operators.

Database Commands

Documentation of all MongoDB database commands operations, syntax, and use.

mongo Shell Methods

Documentation of all JavaScript methods and helpers in the mongo shell.

MongoDB Package Components

Documentation of mongod and mongos and all other tools distributed with MongoDB.

Configuration File Options

Full documentation of the configuration file and available run-time operations.

MongoDB Server Parameters

Documentation of all mongod and mongos parameters that are available in the setParameter (command) and setParameter run-time interface.

MongoDB Limits and Thresholds

A list of important limits and thresholds imposed by MongoDB.

Connection String URI Format

The complete specification of the MongoDB connection string format that the drivers use to describe connections to MongoDB deployments.

MongoDB Extended JSON

Describes the JSON super set used to express BSON documents in the mongo shell and other MongoDB tools.

Glossary

A glossary of common terms and concepts specific to MongoDB.

See also

The Index may provide useful insight into the reference material in this manual. The MongoDB CRUD Reference Data Model Reference, Sharding Reference, Replication Reference, and Security Reference contain additional reference material.

Operators

Query and Projection Operators

Comparison Query Operators

$gt

$gte

$lt

$lte

$ne

$in

$nin

Logical Query Operators

$or

$and

$not

$nor

Element Query Operators

$exists

$type

Evaluation Query Operators

$mod

$regex

$text

$where

Geospatial Query Operators

$geoWithin

$geoIntersects

$near

$nearSphere

$geometry

$minDistance

$maxDistance

$center

$centerSphere

$box

$polygon

$uniqueDocs

Query Operator Array

$all

$elemMatch (query)

$size

$comment

Projection Operators

$ (projection)

$elemMatch (projection)

$meta

$slice (projection)

Update Operators

Field Update Operators

$inc

$mul

$rename

$setOnInsert

$set

$unset

$min

$max

$currentDate

Array Update Operators

$ (update)

$addToSet

$pop

$pullAll

$pull

$pushAll

$push

$each

$slice

$sort

$position

Bitwise Update Operator

$bit

Isolation Update Operator

$isolated

Aggregation Pipeline Operators

Pipeline Aggregation Stages

$project (aggregation)

$match (aggregation)

$redact (aggregation)

$limit (aggregation)

$skip (aggregation)

$unwind (aggregation)

$group (aggregation)

$sort (aggregation)

$geoNear (aggregation)

$out (aggregation)

Boolean Aggregation Operators

$and (aggregation)

$or (aggregation)

$not (aggregation)

Set Operators (Aggregation)

$setEquals (aggregation)

$setIntersection (aggregation)

$setUnion (aggregation)

$setDifference (aggregation)

$setIsSubset (aggregation)

$anyElementTrue (aggregation)

$allElementsTrue (aggregation)

Comparison Aggregation Operators

$cmp (aggregation)

$eq (aggregation)

$gt (aggregation)

$gte (aggregation)

$lt (aggregation)

$lte (aggregation)

$ne (aggregation)

Arithmetic Aggregation Operators

$add (aggregation)

$subtract (aggregation)

$multiply (aggregation)

$divide (aggregation)

$mod (aggregation)

String Aggregation Operators

$concat (aggregation)

$substr (aggregation)

$toLower (aggregation)

$toUpper (aggregation)

$strcasecmp (aggregation)

Text Search Aggregation Operators

$meta (aggregation)

Array Aggregation Operators

$size (aggregation)

Aggregation Variable Operators

$map (aggregation)

$let (aggregation)

Aggregation Literal Operators

$literal (aggregation)

Date Aggregation Operators

$dayOfYear (aggregation)

$dayOfMonth (aggregation)

$dayOfWeek (aggregation)

$year (aggregation)

$month (aggregation)

$week (aggregation)

$hour (aggregation)

$minute (aggregation)

$second (aggregation)

$millisecond (aggregation)

Conditional Aggregation Operators

$cond (aggregation)

$ifNull (aggregation)

Group Accumulator Operators

$sum (aggregation)

$avg (aggregation)

$first (aggregation)

$last (aggregation)

$max (aggregation)

$min (aggregation)

$push (aggregation)

$addToSet (aggregation)

Query Modifiers

$comment

$explain

$hint

$maxScan

$maxTimeMS

$max

$min

$orderby

$returnKey

$showDiskLoc

$snapshot

$query

$natural

Database Commands

Aggregation Commands

aggregate

count

distinct

group

mapReduce

Geospatial Commands

geoNear

geoSearch

geoWalk

Query and Write Operation Commands

insert

update

delete

findAndModify

text

getLastError

getPrevError

resetError

eval

parallelCollectionScan

Query Plan Cache Commands

planCacheListFilters

planCacheSetFilter

planCacheClearFilters

planCacheListQueryShapes

planCacheListPlans

planCacheClear

Authentication Commands

logout

authenticate

copydbgetnonce

getnonce

authSchemaUpgrade

User Management Commands

createUser

updateUser

dropUser

dropAllUsersFromDatabase

grantRolesToUser

revokeRolesFromUser

usersInfo

Role Management Commands

createRole

updateRole

dropRole

dropAllRolesFromDatabase

grantPrivilegesToRole

revokePrivilegesFromRole

grantRolesToRole

revokeRolesFromRole

rolesInfo

invalidateUserCache

Replication Commands

replSetFreeze

replSetGetStatus

replSetInitiate

replSetMaintenance

replSetReconfig

replSetStepDown

replSetSyncFrom

resync

applyOps

isMaster

getoptime

Sharding Commands

flushRouterConfig

addShard

cleanupOrphaned

checkShardingIndex

enableSharding

listShards

removeShard

getShardMap

getShardVersion

mergeChunks

setShardVersion

shardCollection

shardingState

unsetSharding

split

splitChunk

splitVector

medianKey

moveChunk

movePrimary

isdbgrid

Administration Commands

renameCollection

copydb

dropDatabase

drop

create

clone

cloneCollection

cloneCollectionAsCapped

closeAllDatabases

convertToCapped

filemd5

createIndexes

dropIndexes

fsync

clean

connPoolSync

connectionStatus

compact

collMod

reIndex

setParameter

getParameter

repairDatabase

touch

shutdown

logRotate

Diagnostic Commands

listDatabases

dbHash

driverOIDTest

listCommands

availableQueryOptions

buildInfo

collStats

connPoolStats

shardConnPoolStats

dbStats

cursorInfo

dataSize

diagLogging

getCmdLineOpts

netstat

ping

profile

validate

top

indexStats

whatsmyuri

getLog

hostInfo

serverStatus

features

isSelf

Internal Commands

handshake

recvChunkAbort

recvChunkCommit

recvChunkStart

recvChunkStatus

replSetFresh

mapreduce.shardedfinish

transferMods

replSetHeartbeat

replSetGetRBID

migrateClone

replSetElect

writeBacksQueued

writebacklisten

Testing Commands

testDistLockWithSkew

testDistLockWithSyncCluster

captrunc

emptycapped

godinsert

_hashBSONElement

journalLatencyTest

sleep

replSetTest

forceerror

skewClockCommand

configureFailPoint

System Events Auditing Commands

logApplicationMessage

mongo Shell Methods

Collection Methods

db.collection.aggregate()

db.collection.count()

db.collection.copyTo()

db.collection.createIndex()

db.collection.getIndexStats()

db.collection.indexStats()

db.collection.dataSize()

db.collection.distinct()

db.collection.drop()

db.collection.dropIndex()

db.collection.dropIndexes()

db.collection.ensureIndex()

db.collection.find()

db.collection.findAndModify()

db.collection.findOne()

db.collection.getIndexes()

db.collection.getShardDistribution()

db.collection.getShardVersion()

db.collection.group()

db.collection.insert()

db.collection.isCapped()

db.collection.mapReduce()

db.collection.reIndex()

db.collection.remove()

db.collection.renameCollection()

db.collection.save()

db.collection.stats()

db.collection.storageSize()

db.collection.totalSize()

db.collection.totalIndexSize()

db.collection.update()

db.collection.validate()

Cursor Methods

cursor.addOption()

cursor.batchSize()

cursor.count()

cursor.explain()

cursor.forEach()

cursor.hasNext()

cursor.hint()

cursor.limit()

cursor.map()

cursor.maxTimeMS()

cursor.max()

cursor.min()

cursor.next()

cursor.objsLeftInBatch()

cursor.readPref()

cursor.showDiskLoc()

cursor.size()

cursor.skip()

cursor.snapshot()

cursor.sort()

cursor.toArray()

Database Methods

db.addUser()

db.auth()

db.changeUserPassword()

db.cloneCollection()

db.cloneDatabase()

db.commandHelp()

db.copyDatabase()

db.createCollection()

db.currentOp()

db.dropDatabase()

db.eval()

db.fsyncLock()

db.fsyncUnlock()

db.getCollection()

db.getCollectionNames()

db.getLastError()

db.getLastErrorObj()

db.getMongo()

db.getName()

db.getPrevError()

db.getProfilingLevel()

db.getProfilingStatus()

db.getReplicationInfo()

db.getSiblingDB()

db.help()

db.hostInfo()

db.isMaster()

db.killOp()

db.listCommands()

db.loadServerScripts()

db.logout()

db.printCollectionStats()

db.printReplicationInfo()

db.printShardingStatus()

db.printSlaveReplicationInfo()

db.removeUser()

db.repairDatabase()

db.resetError()

db.runCommand()

db.serverBuildInfo()

db.serverCmdLineOpts()

db.serverStatus()

db.setProfilingLevel()

db.shutdownServer()

db.stats()

db.version()

db.upgradeCheck()

db.upgradeCheckAllDBs()

Query Plan Cache Methods

db.collection.getPlanCache()

PlanCache.help()

PlanCache.listQueryShapes()

PlanCache.getPlansByQuery()

PlanCache.clearPlansByQuery()

PlanCache.clear()

Bulk Operation Methods

Bulk()

db.collection.initializeOrderedBulkOp()

db.collection.initializeUnorderedBulkOp()

Bulk.insert()

Bulk.find()

Bulk.find.removeOne()

Bulk.find.remove()

Bulk.find.replaceOne()

Bulk.find.updateOne()

Bulk.find.update()

Bulk.find.upsert()

Bulk.execute()

Bulk.getOperations()

Bulk.tojson()

Bulk.toString()

User Management Methods

db.createUser()

db.addUser()

db.updateUser()

db.changeUserPassword()

db.removeUser()

db.dropAllUsers()

db.dropUser()

db.grantRolesToUser()

db.revokeRolesFromUser()

db.getUser()

db.getUsers()

Role Management Methods

db.createRole()

db.updateRole()

db.dropRole()

db.dropAllRoles()

db.grantPrivilegesToRole()

db.revokePrivilegesFromRole()

db.grantRolesToRole()

db.revokeRolesFromRole()

db.getRole()

db.getRoles()

Replication Methods

rs.add()

rs.addArb()

rs.conf()

rs.freeze()

rs.help()

rs.initiate()

rs.printReplicationInfo()

rs.printSlaveReplicationInfo()

rs.reconfig()

rs.remove()

rs.slaveOk()

rs.status()

rs.stepDown()

rs.syncFrom()

Sharding Methods

sh._adminCommand()

sh._checkFullName()

sh._checkMongos()

sh._lastMigration()

sh.addShard()

sh.addShardTag()

sh.addTagRange()

sh.disableBalancing()

sh.enableBalancing()

sh.enableSharding()

sh.getBalancerHost()

sh.getBalancerState()

sh.help()

sh.isBalancerRunning()

sh.moveChunk()

sh.removeShardTag()

sh.setBalancerState()

sh.shardCollection()

sh.splitAt()

sh.splitFind()

sh.startBalancer()

sh.status()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.waitForDLock()

sh.waitForPingChange()

Subprocess Methods

clearRawMongoProgramOutput()

rawMongoProgramOutput()

run()

runMongoProgram()

runProgram()

startMongoProgram()

stopMongoProgram()

stopMongoProgramByPid()

stopMongod()

waitMongoProgramOnPort()

waitProgram()

Object Constructors and Methods

Date()

UUID()

ObjectId.getTimestamp()

ObjectId.toString()

ObjectId.valueOf()

WriteResult()

WriteResult.hasWriteError()

WriteResult.hasWriteConcernError()

BulkWriteResult()

Connection Methods

Mongo.getDB()

Mongo.getReadPrefMode()

Mongo.getReadPrefTagSet()

Mongo.setReadPref()

mongo.setSlaveOk()

Mongo()

connect()

Native Methods

cat()

version()

cd()

copyDbpath()

resetDbpath()

fuzzFile()

getHostName()

getMemInfo()

hostname()

_isWindows()

listFiles()

load()

ls()

md5sumFile()

mkdir()

pwd()

quit()

rand()

removeFile()

_srand()

MongoDB Package Components

mongod

mongos

mongo

mongod.exe

mongos.exe

mongodump

mongorestore

bsondump

mongooplog

mongoimport

mongoexport

mongostat

mongotop

mongosniff

mongoperf

mongofiles

Configuration File Options

MongoDB Server Parameters

MongoDB Limits and Thresholds

Connection String URI Format

MongoDB Extended JSON

Glossary

Operators

Query and Projection Operators

Query operators provide ways to locate data within the database and projection operators modify how data is presented.

Update Operators

Update operators are operators that enable you to modify the data in your database or add additional data.

Aggregation Pipeline Operators

Aggregation pipeline operations have a collection of operators available to define and manipulate documents in pipeline stages.

Query Modifiers

Query modifiers determine the way that queries will be executed.

Query and Projection Operators

Comparison Query Operators

$gt

$gte

$lt

$lte

$ne

$in

$nin

Logical Query Operators

$or

$and

$not

$nor

Element Query Operators

$exists

$type

Evaluation Query Operators

$mod

$regex

$text

$where

Geospatial Query Operators

$geoWithin

$geoIntersects

$near

$nearSphere

$geometry

$minDistance

$maxDistance

$center

$centerSphere

$box

$polygon

$uniqueDocs

Query Operator Array

$all

$elemMatch (query)

$size

$comment

Projection Operators

$ (projection)

$elemMatch (projection)

$meta

$slice (projection)

Update Operators

Field Update Operators

$inc

$mul

$rename

$setOnInsert

$set

$unset

$min

$max

$currentDate

Array Update Operators

$ (update)

$addToSet

$pop

$pullAll

$pull

$pushAll

$push

$each

$slice

$sort

$position

Bitwise Update Operator

$bit

Isolation Update Operator

$isolated

Aggregation Pipeline Operators

Pipeline Aggregation Stages

$project (aggregation)

$match (aggregation)

$redact (aggregation)

$limit (aggregation)

$skip (aggregation)

$unwind (aggregation)

$group (aggregation)

$sort (aggregation)

$geoNear (aggregation)

$out (aggregation)

Boolean Aggregation Operators

$and (aggregation)

$or (aggregation)

$not (aggregation)

Set Operators (Aggregation)

$setEquals (aggregation)

$setIntersection (aggregation)

$setUnion (aggregation)

$setDifference (aggregation)

$setIsSubset (aggregation)

$anyElementTrue (aggregation)

$allElementsTrue (aggregation)

Comparison Aggregation Operators

$cmp (aggregation)

$eq (aggregation)

$gt (aggregation)

$gte (aggregation)

$lt (aggregation)

$lte (aggregation)

$ne (aggregation)

Arithmetic Aggregation Operators

$add (aggregation)

$subtract (aggregation)

$multiply (aggregation)

$divide (aggregation)

$mod (aggregation)

String Aggregation Operators

$concat (aggregation)

$substr (aggregation)

$toLower (aggregation)

$toUpper (aggregation)

$strcasecmp (aggregation)

Text Search Aggregation Operators

$meta (aggregation)

Array Aggregation Operators

$size (aggregation)

Aggregation Variable Operators

$map (aggregation)

$let (aggregation)

Aggregation Literal Operators

$literal (aggregation)

Date Aggregation Operators

$dayOfYear (aggregation)

$dayOfMonth (aggregation)

$dayOfWeek (aggregation)

$year (aggregation)

$month (aggregation)

$week (aggregation)

$hour (aggregation)

$minute (aggregation)

$second (aggregation)

$millisecond (aggregation)

Conditional Aggregation Operators

$cond (aggregation)

$ifNull (aggregation)

Group Accumulator Operators

$sum (aggregation)

$avg (aggregation)

$first (aggregation)

$last (aggregation)

$max (aggregation)

$min (aggregation)

$push (aggregation)

$addToSet (aggregation)

Query Modifiers

$comment

$explain

$hint

$maxScan

$maxTimeMS

$max

$min

$orderby

$returnKey

$showDiskLoc

$snapshot

$query

$natural

Query and Projection Operators

Query Selectors

Comparison

Comparison Query Operators

$gt

$gte

$lt

$lte

$ne

$in

$nin

Logical

Logical Query Operators

$or

$and

$not

$nor

Element

Element Query Operators

$exists

$type

Evaluation

Evaluation Query Operators

$mod

$regex

$text

$where

Geospatial

Geospatial Query Operators

$geoWithin

$geoIntersects

$near

$nearSphere

$geometry

$minDistance

$maxDistance

$center

$centerSphere

$box

$polygon

$uniqueDocs

Array

Query Operator Array

$all

$elemMatch (query)

$size

Comments

$comment

Projection Operators

Projection Operators

$ (projection)

$elemMatch (projection)

$meta

$slice (projection)

Comparison Query Operators

For comparison of different BSON type values, see the specified BSON comparison order.

Name | Description
$gt | Matches values that are greater than the value specified in the query.
$gte | Matches values that are greater than or equal to the value specified in the query.
$lt | Matches values that are less than the value specified in the query.
$lte | Matches values that are less than or equal to the value specified in the query.
$ne | Matches all values that are not equal to the value specified in the query.
$in | Matches any of the values that exist in an array specified in the query.
$nin | Matches values that do not exist in an array specified to the query.

$gt

$gte

$lt

$lte

$ne

$in

$nin

$gt

$gt

Syntax: {field: {$gt: value} }

$gt selects those documents where the value of the field is greater than (i.e. >) the specified value.

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following example:

db.inventory.find( { qty: { $gt: 20 } } )

This query will select all documents in the inventory collection where the qty field value is greater than 20.

Consider the following example that uses the $gt operator with a field from an embedded document:

db.inventory.update( { "carrier.fee": { $gt: 2 } }, { $set: { price: 9.99 } } )

This update() operation will set the value of the price field in the first document found containing the embedded document carrier whose fee field value is greater than 2.

To set the value of the price field in all documents containing the embedded document carrier whose fee field value is greater than 2, specify the multi:true option in the update() method:

db.inventory.update( { "carrier.fee": { $gt: 2 } },
                     { $set: { price: 9.99 },
                     { multi: true }
                  )

See also

find(), update(), $set.

$gte

$gte

Syntax: {field: {$gte: value} }

$gte selects the documents where the value of the field is greater than or equal to (i.e. >=) a specified value (e.g. value.)

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following example:

db.inventory.find( { qty: { $gte: 20 } } )

This query would select all documents in inventory where the qty field value is greater than or equal to 20.

Consider the following example which uses the $gte operator with a field from an embedded document:

db.inventory.update( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } )

This update() operation will set the value of the price field that contain the embedded document carrier whose fee field value is greater than or equal to 2.

See also

find(), update(), $set.

$lt

$lt

Syntax: {field: {$lt: value} }

$lt selects the documents where the value of the field is less than (i.e. <) the specified value.

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following example:

db.inventory.find( { qty: { $lt: 20 } } )

This query will select all documents in the inventory collection where the qty field value is less than 20.

Consider the following example which uses the $lt operator with a field from an embedded document:

db.inventory.update( { "carrier.fee": { $lt: 20 } }, { $set: { price: 9.99 } } )

This update() operation will set the price field value in the documents that contain the embedded document carrier whose fee field value is less than 20.

See also

find(), update(), $set.

$lte

$lte

Syntax: { field: { $lte: value} }

$lte selects the documents where the value of the field is less than or equal to (i.e. <=) the specified value.

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following example:

db.inventory.find( { qty: { $lte: 20 } } )

This query will select all documents in the inventory collection where the qty field value is less than or equal to 20.

Consider the following example which uses the $lt operator with a field from an embedded document:

db.inventory.update( { "carrier.fee": { $lte: 5 } }, { $set: { price: 9.99 } } )

This update() operation will set the price field value in the documents that contain the embedded document carrier whose fee field value is less than or equal to 5.

See also

find(), update(), $set.

$ne

$ne

Syntax: {field: {$ne: value} }

$ne selects the documents where the value of the field is not equal (i.e. !=) to the specified value. This includes documents that do not contain the field.

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following example:

db.inventory.find( { qty: { $ne: 20 } } )

This query will select all documents in the inventory collection where the qty field value does not equal 20, including those documents that do not contain the qty field.

Consider the following example which uses the $ne operator with a field in an embedded document:

db.inventory.update( { "carrier.state": { $ne: "NY" } }, { $set: { qty: 20 } } )

This update() operation will set the qty field value in the documents that contain the embedded document carrier whose state field value does not equal “NY”, or where the state field or the carrier embedded document do not exist.

See also

find(), update(), $set.

$in

$in

The $in operator selects the documents where the value of a field equals any value in the specified array. To specify an $in expression, use the following prototype:

For comparison of different BSON type values, see the specified BSON comparison order.

{ field: { $in: [<value1>, <value2>, ... <valueN> ] } }

If the field holds an array, then the $in operator selects the documents whose field holds an array that contains at least one element that matches a value in the specified array (e.g. <value1>, <value2>, etc.)

Changed in version 2.6: MongoDB 2.6 removes the combinatorial limit for the $in operator that exists for earlier versions [http://docs.mongodb.org/v2.4/reference/operator/query/in] of the operator.

Examples

Use the $in Operator to Match Values

Consider the following example:

db.inventory.find( { qty: { $in: [ 5, 15 ] } } )

This query selects all documents in the inventory collection where the qty field value is either 5 or 15. Although you can express this query using the $or operator, choose the $in operator rather than the $or operator when performing equality checks on the same field.

Use the $in Operator to Match Values in an Array

The collection inventory contains documents that include the field tags, as in the following:

{ _id: 1, item: "abc", qty: 10, tags: [ "school", "clothing" ], sale: false }

Then, the following update() operation will set the sale field value to true where the tags field holds an array with at least one element matching either "appliances" or "school".

db.inventory.update(
                     { tags: { $in: ["appliances", "school"] } },
                     { $set: { sale:true } }
                   )

Use the $in Operator with a Regular Expression

The $in operator can specify matching values using regular expressions of the form /pattern/. You cannot use $regex operator expressions inside an $in.

Consider the following example:

db.inventory.find( { tags: { $in: [ /^be/, /^st/ ] } } )

This query selects all documents in the inventory collection where the tags field holds an array that contains at least one element that starts with either be or st.

See also

find(), update(), $or, $set.

$nin

$nin

Syntax: { field: { $nin: [ <value1>, <value2> ... <valueN> ]} }

$nin selects the documents where:

the field value is not in the specified array or

the field does not exist.

For comparison of different BSON type values, see the specified BSON comparison order.

Consider the following query:

db.inventory.find( { qty: { $nin: [ 5, 15 ] } } )

This query will select all documents in the inventory collection where the qty field value does not equal 5 nor 15. The selected documents will include those documents that do not contain the qty field.

If the field holds an array, then the $nin operator selects the documents whose field holds an array with no element equal to a value in the specified array (e.g. <value1>, <value2>, etc.).

Consider the following query:

db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } )

This update() operation will set the sale field value in the inventory collection where the tags field holds an array with no elements matching an element in the array ["appliances", "school"] or where a document does not contain the tags field.

See also

find(), update(), $set.

Logical Query Operators

Name | Description
$or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
$and | Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.
$not | Inverts the effect of a query expression and returns documents that do not match the query expression.
$nor | Joins query clauses with a logical NOR returns all documents that fail to match both clauses.

$or

$and

$not

$nor

$or

$or

The $or operator performs a logical OR operation on an array of two or more <expressions> and selects the documents that satisfy at least one of the <expressions>. The $or has the following syntax:

{ $or: [ { <expression1> }, { <expression2> }, ... , { <expressionN> } ] }

Consider the following example:

db.inventory.find( { $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] } )

This query will select all documents in the inventory collection where either the quantity field value is less than 20 or the price field value equals 10.

Behaviors

$or Clauses and Indexes

When evaluating the clauses in the $or expression, MongoDB either performs a collection scan or, if all the clauses are supported by indexes, MongoDB performs index scans. That is, for MongoDB to use indexes to evaluate an $or expression, all the clauses in the $or expression must be supported by indexes. Otherwise, MongoDB will perform a collection scan.

When using indexes with $or queries, each clause of an $or can use its own index. Consider the following query:

db.inventory.find( { $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] } )

To support this query, rather than a compound index, you would create one index on quantity and another index on price:

db.inventory.ensureIndex( { quantity: 1 } )
db.inventory.ensureIndex( { price: 1 } )

MongoDB can use all but the geoHaystack index to support $or clauses.

$or and text Queries

Changed in version 2.6.

If $or includes a $text query, all clauses in the $or array must be supported by an index. This is because a $text query must use an index, and $or can only use indexes if all its clauses are supported by indexes. If the $text query cannot use an index, the query will return an error.

$or and GeoSpatial Queries

Changed in version 2.6.

$or supports geospatial clauses with the following exception for the near clause (near clause includes $nearSphere and $near). $or cannot contain a near clause with any other clause.

$or and Sort Operations

Changed in version 2.6.

When executing $or queries with a sort(), MongoDB can now use indexes that support the $or clauses. Previous versions did not use the indexes.

$or versus $in

When using $or with <expressions> that are equality checks for the value of the same field, use the $in operator instead of the $or operator.

For example, to select all documents in the inventory collection where the quantity field value equals either 20 or 50, use the $in operator:

db.inventory.find ( { quantity: { $in: [20, 50] } } )

Nested $or Clauses

You may nest $or operations.

See also

$and, find(), sort(), $in

$and

$and

New in version 2.0.

Syntax: { $and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }

$and performs a logical AND operation on an array of two or more expressions (e.g. <expression1>, <expression2>, etc.) and selects the documents that satisfy all the expressions in the array. The $and operator uses short-circuit evaluation. If the first expression (e.g. <expression1>) evaluates to false, MongoDB will not evaluate the remaining expressions.

Note

MongoDB provides an implicit AND operation when specifying a comma separated list of expressions. Using an explicit AND with the $and operator is necessary when the same field or operator has to be specified in multiple expressions.

Examples

AND Queries With Multiple Expressions Specifying the Same Field

Consider the following example:

db.inventory.find( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] } )

This query will select all documents in the inventory collection where:

the price field value is not equal to 1.99 and

the price field exists.

This query can be also be constructed with an implicit AND operation by combining the operator expressions for the price field. For example, this query can be written as:

db.inventory.find( { price: { $ne: 1.99, $exists: true } } )

AND Queries With Multiple Expressions Specifying the Same Operator

Consider the following example:

db.inventory.find( {
    $and : [
        { $or : [ { price : 0.99 }, { price : 1.99 } ] },
        { $or : [ { sale : true }, { qty : { $lt : 20 } } ] }
    ]
} )

This query will return all select all documents where:

the price field value equals 0.99 or 1.99, and

the sale field value is equal to true or the qty field value is less than 20.

This query cannot be constructed using an implicit AND operation, because it uses the $or operator more than once.

See also

find(), update(), $ne, $exists, $set.

$not

$not

Syntax: { field: { $not: { <operator-expression> } } }

$not performs a logical NOT operation on the specified <operator-expression> and selects the documents that do not match the <operator-expression>. This includes documents that do not contain the field.

Consider the following query:

db.inventory.find( { price: { $not: { $gt: 1.99 } } } )

This query will select all documents in the inventory collection where:

the price field value is less than or equal to 1.99 or

the price field does not exist

{ $not: { $gt: 1.99 } } is different from the $lte operator. { $lte: 1.99 } returns only the documents where price field exists and its value is less than or equal to 1.99.

Remember that the $not operator only affects other operators and cannot check fields and documents independently. So, use the $not operator for logical disjunctions and the $ne operator to test the contents of fields directly.

Consider the following behaviors when using the $not operator:

The operation of the $not operator is consistent with the behavior of other operators but may yield unexpected results with some data types like arrays.

The $not operator does not support operations with the $regex operator. Instead use // or in your driver interfaces, use your language’s regular expression capability to create regular expression objects.

Consider the following example which uses the pattern match expression //:

db.inventory.find( { item: { $not: /^p.*/ } } )

The query will select all documents in the inventory collection where the item field value does not start with the letter p.

If you are using Python, you can write the above query with the PyMongo driver and Python’s python:re.compile() method to compile a regular expression, as follows:

import re
for noMatch in db.inventory.find( { "item": { "$not": re.compile("^p.*") } } ):
    print noMatch

See also

find(), update(), $set, $gt, $regex, PyMongo [http://api.mongodb.org/pythoncurrent], driver.

$nor

$nor

$nor performs a logical NOR operation on an array of one or more query expression and selects the documents that fail all the query expressions in the array. The $nor has the following syntax:

{ $nor: [ { <expression1> }, { <expression2> }, ...  { <expressionN> } ] }

See also

find(), update(), $or, $set, and $exists.

Examples

$nor Query with Two Expressions

Consider the following query which uses only the $nor operator:

db.inventory.find( { $nor: [ { price: 1.99 }, { sale: true } ]  } )

This query will return all documents that:

contain the price field whose value is not equal to 1.99 and contain the sale field whose value is not equal to true or

contain the price field whose value is not equal to 1.99 but do not contain the sale field or

do not contain the price field but contain the sale field whose value is not equal to true or

do not contain the price field and do not contain the sale field

$nor and Additional Comparisons

Consider the following query:

db.inventory.find( { $nor: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } )

This query will select all documents in the inventory collection where:

the price field value does not equal 1.99 and

the qty field value is not less than 20 and

the sale field value is not equal to true

including those documents that do not contain these field(s).

The exception in returning documents that do not contain the field in the $nor expression is when the $nor operator is used with the $exists operator.

$nor and $exists

Compare that with the following query which uses the $nor operator with the $exists operator:

db.inventory.find( { $nor: [ { price: 1.99 }, { price: { $exists: false } },
                             { sale: true }, { sale: { $exists: false } } ] } )

This query will return all documents that:

contain the price field whose value is not equal to 1.99 and contain the sale field whose value is not equal to true

Element Query Operators

Name | Description
$exists | Matches documents that have the specified field.
$type | Selects documents if a field is of the specified type.

$exists

$type

$exists

Definition

$exists

Syntax: { field: { $exists: <boolean> } }

When <boolean> is true, $exists matches the documents that contain the field, including documents where the field value is null. If <boolean> is false, the query returns only the documents that do not contain the field.

MongoDB $exists does not correspond to SQL operator exists. For SQL exists, refer to the $in operator.

See also

$nin, $in, and How do I query for fields that have null values?.

Examples

Exists and Not Equal To

Consider the following example:

db.inventory.find( { qty: { $exists: true, $nin: [ 5, 15 ] } } )

This query will select all documents in the inventory collection where the qty field exists and its value does not equal 5 or 15.

Null Values

Given a collection named records with the following documents:

{ a: 5, b: 5, c: null }
{ a: 3, b: null, c: 8 }
{ a: null, b: 3, c: 9 }
{ a: 1, b: 2, c: 3 }
{ a: 2, c: 5 }
{ a: 3, b: 2 }
{ a: 4 }
{ b: 2, c: 4 }
{ b: 2 }
{ c: 6 }

Consider the output of the following queries:

Query:

db.records.find( { a: { $exists: true } } )

Result:

{ a: 5, b: 5, c: null }
{ a: 3, b: null, c: 8 }
{ a: null, b: 3, c: 9 }
{ a: 1, b: 2, c: 3 }
{ a: 2, c: 5 }
{ a: 3, b: 2 }
{ a: 4 }

Query:

db.records.find( { b: { $exists: false } } )

Result:

{ a: 2, c: 5 }
{ a: 4 }
{ c: 6 }

Query:

db.records.find( { c: { $exists: false } } )

Result:

{ a: 3, b: 2 }
{ a: 4 }
{ b: 2 }

$type

Definition

$type

Syntax: { field: { $type: <BSON type> } }

$type selects the documents where the value of the field is the specified numeric BSON type. This is useful when dealing with highly unstructured data where data types are not predictable.

Warning

Data models that associate a field name with different data types within a collection are strongly discouraged.

Without internal consistency complicates application code, and can lead to unnecessary complexity for application developers.

Behavior

Available Types

Refer to the following table for the available BSON types and their corresponding numbers.

Type | Number | Notes
Double | 1 |
String | 2 |
Object | 3 |
Array | 4 |
Binary data | 5 |
Undefined | 6 | Deprecated.
Object id | 7 |
Boolean | 8 |
Date | 9 |
Null | 10 |
Regular Expression | 11 |
JavaScript | 13 |
Symbol | 14 |
JavaScript (with scope) | 15 |
32-bit integer | 16 |
Timestamp | 17 |
64-bit integer | 18 |
Min key | 255 | Query with -1.
Max key | 127 |

Minimum and Maximum Values

MinKey and MaxKey compare less than and greater than all other possible BSON element values, respectively, and exist primarily for internal use.

To query if a field value is a MinKey, you must use $type with -1 as in the following example:

db.collection.find( { field: { $type: -1 } } );

Arrays

When applied to arrays, $type matches any inner element that is of the specified type. Without projection this means that the entire array will match if any element has the right type. With projection, the results will include just those elements of the requested type.

Examples

Querying by Data Type

Consider the following query:

db.inventory.find( { tags: { $type : 2 } } );

This will list all documents containing a tags field that is either a string or an array holding at least one string. If you only want to list documents where tags is an array, you could use $where:

db.inventory.find( { $where : "Array.isArray(this.tags)" } );

Queries that use $where requires a complete collection scan and uses Server-side JavaScript.

MinKey and MaxKey

The following operation sequence demonstrates both type comparison and the special MinKey and MaxKey values:

> db.test.insert( [ { x : 3 },
                  { x : 2.9 },
                  { x : new Date() },
                  { x : true },
                  { x : MaxKey },
                  { x : MinKey } ] );

> db.test.find().sort( { x : 1 } );
{ "_id" : ObjectId("4b04094b7c65b846e2090112"), "x" : { $minKey : 1 } }
{ "_id" : ObjectId("4b03155dce8de6586fb002c7"), "x" : 2.9 }
{ "_id" : ObjectId("4b03154cce8de6586fb002c6"), "x" : 3 }
{ "_id" : ObjectId("4b031566ce8de6586fb002c9"), "x" : true }
{ "_id" : ObjectId("4b031563ce8de6586fb002c8"), "x" : "Tue Jul 25 2012 18:42:03 GMT-0500 (EST)" }
{ "_id" : ObjectId("4b0409487c65b846e2090111"), "x" : { $maxKey : 1 } }

Minimum Shard Key

To query for the minimum value of a shard key of a sharded cluster, use the following operation when connected to the mongos:

use config
db.chunks.find( { "min.shardKey": { $type: -1 } } )

Additional Information

find(), insert(), $where, BSON, shard key, sharded cluster .

Evaluation Query Operators

Name | Description
$mod | Performs a modulo operation on the value of a field and selects documents with a specified result.
$regex | Selects documents where values match a specified regular expression.
$text | Performs text search.
$where | Matches documents that satisfy a JavaScript expression.

$mod

$regex

$text

$where

$mod

$mod

Select documents where the value of a field divided by a divisor has the specified remainder (i.e. perform a modulo operation to select documents). To specify a $mod expression, use the following syntax:

{ field: { $mod: [ divisor, remainder ] } }

Changed in version 2.6: The $mod operator errors when passed an array with fewer or more elements. In previous versions, if passed an array with one element, the $mod operator uses 0 as the remainder value, and if passed an array with more than two elements, the $mod ignores all but the first two elements. Previous versions do return an error when passed an empty array. See Not Enough Elements Error and Too Many Elements Error for details.

Examples

Use $mod to Select Documents

Consider a collection inventory with the following documents:

{ "_id" : 1, "item" : "abc123", "qty" : 0 }
{ "_id" : 2, "item" : "xyz123", "qty" : 5 }
{ "_id" : 3, "item" : "ijk123", "qty" : 12 }

Then, the following query selects those documents in the inventory collection where value of the qty field modulo 4 equals 0:

db.inventory.find( { qty: { $mod: [ 4, 0 ] } } )

The query returns the following documents:

{ "_id" : 1, "item" : "abc123", "qty" : 0 }
{ "_id" : 3, "item" : "ijk123", "qty" : 12 }

Not Enough Elements Error

The $mod operator errors when passed an array with fewer than two elements.

Array with Single Element

The following operation incorrectly passes the $mod operator an array that contains a single element:

db.inventory.find( { qty: { $mod: [ 4 ] } } )

The statement results in the following error:

error: {
     "$err" : "bad query: BadValue malformed mod, not enough elements",
     "code" : 16810
}

Changed in version 2.6: In previous versions, if passed an array with one element, the $mod operator uses the specified element as the divisor and 0 as the remainder value.

Empty Array

The following operation incorrectly passes the $mod operator an empty array:

db.inventory.find( { qty: { $mod: [ ] } } )

The statement results in the following error:

error: {
     "$err" : "bad query: BadValue malformed mod, not enough elements",
     "code" : 16810
}

Changed in version 2.6: Previous versions returned the following error:

error: { "$err" : "mod can't be 0", "code" : 10073 }

Too Many Elements Error

The $mod operator errors when passed an array with more than two elements.

For example, the following operation attempts to use the $mod operator with an array that contains four elements:

error: {
     "$err" : "bad query: BadValue malformed mod, too many elements",
     "code" : 16810
}

Changed in version 2.6: In previous versions, if passed an array with more than two elements, the $mod ignores all but the first two elements.

$regex

Definition

$regex

Provides regular expression capabilities for pattern matching strings in queries. MongoDB uses Perl compatible regular expressions (i.e. “PCRE” ) version 8.30 with UTF-8 support.

To use $regex, use one of the following syntax:

{ <field>: { $regex: /pattern/, $options: '<options>' } }
{ <field>: { $regex: 'pattern', $options: '<options>' } }
{ <field>: { $regex: /pattern/<options> } }

In MongoDB, you can also use regular expression objects (i.e. /pattern/) to specify regular expressions:

{ <field>: /pattern/<options> }

For restrictions on particular syntax use, see $regex vs. /pattern/ Syntax.

$options

The following <options> are available for use with regular expression.

Option
Description
Syntax Restrictions

i
Case insensitivity to match upper and lower cases. For an example, see Perform Case-Insensitive Regular Expression Match.

m

For patterns that include anchors (i.e. ^ for the start, $ for the end), match at the beginning or end of each line for strings with multiline values. Without this option, these anchors match at beginning or end of the string. For an example, see Multiline Match for Lines Starting with Specified Pattern.

If the pattern contains no anchors or if the string value has no newline characters (e.g. \n), the m option has no effect.

x

“Extended” capability to ignore all white space characters in the $regex pattern unless escaped or included in a character class.

Additionally, it ignores characters in-between and including an un-escaped hash/pound (#) character and the next new line, so that you may include comments in complicated patterns. This only applies to data characters; white space characters may never appear within special character sequences in a pattern.

The x option does not affect the handling of the VT character (i.e. code 11).

Requires $regex with $options syntax

s
Allows the dot character (i.e. .) to match all characters including newline characters. For an example, see Use the . Dot Character to Match New Line.
Requires $regex with $options syntax

Behavior

$regex vs. /pattern/ Syntax

$in Expressions

To include a regular expression in an $in query expression, you can only use JavaScript regular expression objects (i.e. /pattern/ ). For example:

{ name: { $in: [ /^acme/i, /^ack/ ] } }

You cannot use $regex operator expressions inside an $in.

Implicit AND Conditions for the Field

To include a regular expression in a comma-separated list of query conditions for the field, use the $regex operator. For example:

{ name: { $regex: /acme.*corp/i, $nin: [ 'acmeblahcorp' ] } }
{ name: { $regex: /acme.*corp/, $options: 'i', $nin: [ 'acmeblahcorp' ] } }
{ name: { $regex: 'acme.*corp', $options: 'i', $nin: [ 'acmeblahcorp' ] } }

x and s Options

To use either the x option or s options, you must use the $regex operator expression with the $options operator. For example, to specify the i and the s options, you must use $options for both:

{ name: { $regex: /acme.*corp/, $options: "si" } }
{ name: { $regex: 'acme.*corp', $options: "si" } }

PCRE vs JavaScript

To use PCRE supported features in the regex pattern that are unsupported in JavaScript, you must use the $regex operator expression with the pattern as a string. For example, to use (?i) in the pattern to turn case-insensitivity on for the remaining pattern and (?-i) to turn case-sensitivity on for the remaining pattern, you must use the $regex operator with the pattern as a string:

{ name: { $regex: '(?i)a(?-i)cme' } }

Index Use

If an index exists for the field, then MongoDB matches the regular expression against the values in the index, which can be faster than a collection scan. Further optimization can occur if the regular expression is a “prefix expression”, which means that all potential matches start with the same string. This allows MongoDB to construct a “range” from that prefix and only match against those values from the index that fall within that range.

A regular expression is a “prefix expression” if it starts with a caret (^) or a left anchor (\A), followed by a string of simple symbols. For example, the regex /^abc.*/ will be optimized by matching only against the values from the index that start with abc.

Additionally, while /^a/, /^a.*/, and /^a.*$/ match equivalent strings, they have different performance characteristics. All of these expressions use an index if an appropriate index exists; however, /^a.*/, and /^a.*$/ are slower. /^a/ can stop scanning after matching the prefix.

Examples

The following examples use a collection products with the following documents:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }
{ "_id" : 102, "sku" : "xyz456", "description" : "Many spaces before     line" }
{ "_id" : 103, "sku" : "xyz789", "description" : "Multiple\nline description" }

Perform Case-Insensitive Regular Expression Match

The following example uses the i option perform a case-insensitive match for documents with sku value that starts with ABC.

db.products.find( { sku: { $regex: /^ABC/i } } )

The query matches the following documents:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Multiline Match for Lines Starting with Specified Pattern

The following example uses the m option to match lines starting with the letter S for multiline strings:

db.products.find( { description: { $regex: /^S/, $options: 'm' } } )

The query matches the following documents:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Without the m option, the query would match just the following document:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }

If the $regex pattern does not contain an anchor, the pattern matches against the string as a whole, as in the following example:

db.products.find( { description: { $regex: /S/ } } )

Then, the $regex would match both documents:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }
{ "_id" : 101, "sku" : "abc789", "description" : "First line\nSecond line" }

Use the . Dot Character to Match New Line

The following example uses the s option to allow the dot character (i.e. .) to match all characters including new line as well as the i option to perform a case-insensitive match:

db.products.find( { description: { $regex: /m.*line/, $options: 'si' } } )

The query matches the following documents:

{ "_id" : 102, "sku" : "xyz456", "description" : "Many spaces before     line" }
{ "_id" : 103, "sku" : "xyz789", "description" : "Multiple\nline description" }

Without the s option, the query would have matched only the following document:

{ "_id" : 102, "sku" : "xyz456", "description" : "Many spaces before     line" }

Ignore White Spaces in Pattern

The following example uses the x option ignore white spaces and the comments, denoted by the # and ending with the \n in the matching pattern:

var pattern = "abc #category code\n123 #item number"
db.products.find( { sku: { $regex: pattern, $options: "x" } } )

The query matches the following document:

{ "_id" : 100, "sku" : "abc123", "description" : "Single line description." }

$text

$text

New in version 2.6.

$text performs a text search on the content of the fields indexed with a text index. A $text expression has the following syntax:

{ $text: { $search: <string>, $language: <string> } }

The $text operator accepts a text query document with the following fields:

Field
Description

$search
A string of terms that MongoDB parses and uses to query the text index. MongoDB performs a logical OR search of the terms unless specified as a phrase. See Behavior for more information on the field.

$language

Optional. The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index. For supported languages, see Text Search Languages.

If you specify a language value of "none", then the text search uses simple tokenization with no list of stop words and no stemming.

field string $search:

A string of terms that MongoDB parses and uses to query the text index. MongoDB performs a logical OR search of the terms unless specified as a phrase. See Behavior for more information on the field.

field string $language:

Optional. The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index. For supported languages, see Text Search Languages.

If you specify a language value of "none", then the text search uses simple tokenization with no list of stop words and no stemming.

The $text operator, by default, does not return results sorted in terms of the results’ score. For more information, see the Text Score documentation.

Behavior

Restrictions

A query can specify, at most, one $text expression.

The $text query can not appear in $nor expressions.

To use a $text query in an $or expression, all clauses in the $or array must be indexed.

You cannot use hint() if the query includes a $text query expression.

You cannot specify $natural sort order if the query includes a $text expression.

You cannot combine the $text expression, which requires a special text index, with a query operator that requires a different type of special index. For example you cannot combine $text expression with the $near operator.

$search Field

In the $search field, specify a string of words that the text operator parses and uses to query the text index. The text operator treats most punctuation in the string as delimiters, except a hyphen - that negates term or an escaped double quotes \" that specifies a phrase.

Phrases

To match on a phrase, as opposed to individual terms, enclose the phrase in escaped double quotes (\"), as in:

"\"ssl certificate\""

If the $search string includes a phrase and individual terms, text search will only match the documents that include the phrase. More specifically, the search performs a logical AND of the phrase with the individual terms in the search string.

For example, passed a $search string:

"\"ssl certificate\" authority key"

The $text operator searches for the phrase "ssl certificate" and ("authority" or "key" or "ssl" or "certificate" ).

Negations

Prefixing a word with a hyphen sign (-) negates a word:

The negated word excludes documents that contain the negated word from the result set.

When passed a search string that only contains negated words, text search will not match any documents.

A hyphenated word, such as pre-market, is not a negation. The $text operator treats the hyphen as a delimiter.

The $text operator adds all negations to the query with the logical AND operator.

Match Operation

The $text operator ignores language-specific stop words, such as the and and in English.

The $text operator matches on the complete stemmed word. So if a document field contains the word blueberry, a search on the term blue will not match. However, blueberry or blueberries will match.

For non-diacritics, text search is case insensitive; i.e. case insensitive for [A-z].

Text Score

The $text operator assigns a score to each document that contains the search term in the indexed fields. The score represents the relevance of a document to a given text search query. The score can be part of a sort() method specification as well as part of the projection expression. The { $meta: "textScore" } expression provides information on the processing of the $text operation. See $meta projection operator for details on accessing the score for projection or sort.

Examples

The following examples assume a collection articles that has a text index on the field subject:

db.articles.ensureIndex( { subject: "text" } )

Search for a Single Word

The following query searches for the term coffee:

db.articles.find( { $text: { $search: "coffee" } } )

This query returns documents that contain the term coffee in the indexed subject field.

Match Any of the Search Terms

If the search string is a space-delimited string, $text operator performs a logical OR search on each term and returns documents that contains any of the terms.

The following query searches specifies a $search string of three terms delimited by space, "bake coffee cake":

db.articles.find( { $text: { $search: "bake coffee cake" } } )

This query returns documents that contain either bake or coffee or cake in the indexed subject field.

Search for a Phrase

To match the exact phrase as a single term, escape the quotes.

The following query searches for the phrase coffee cake:

db.articles.find( { $text: { $search: "\"coffee cake\"" } } )

This query returns documents that contain the phrase coffee cake.

See also

Phrases

Exclude Documents That Contain a Term

A negated term is a term that is prefixed by a minus sign -. If you negate a term, the $text operator will exclude the documents that contain those terms from the results.

The following example searches for documents that contain the words bake or coffee but do not contain the term cake:

db.articles.find( { $text: { $search: "bake coffee -cake" } } )

See also

Negations

Return the Text Search Score

The following query searches for the term cake and returns the score assigned to each matching document:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
)

In the result set, the returned documents includes an additional field score that contains the document’s score associated with the text search. [1]

See also

Text Score

Sort by Text Search Score

To sort by the text score, include the same $meta expression in both the projection document and the sort expression. [1] The following query searches for the term cake and sorts the results by the descending score:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
).sort( { score: { $meta: "textScore" } } )

In the result set, the returned documents includes an additional field score that contains the document’s score associated with the text search.

See also

Text Score

Return Top 3 Matching Documents

Use the limit() method in conjunction with a sort() to return the top three matching documents. The following query searches for the term cake and sorts the results by the descending score:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
).sort( { score: { $meta: "textScore" } } ).limit(3)

See also

Text Score

Text Search with Additional Query and Sort Expressions

The following query searches for documents with status equal to "A" that contain the terms coffee or cake in the indexed field subject and specifies a sort order of ascending date, descending text score:

db.articles.find(
   { status: "A", $text: { $search: "coffee cake" } },
   { score: { $meta: "textScore" } }
).sort( { date: 1, score: { $meta: "textScore" } } )

Search a Different Language

Use the optional $language field in the $text expression to specify a language that determines the list of stop words and the rules for the stemmer and tokenizer for the search string.

If you specify a language value of "none", then the text search uses simple tokenization with no list of stop words and no stemming.

The following query specifies es for Spanish as the language that determines the tokenization, stemming, and stop words:

db.articles.find(
   { $text: { $search: "leche", $language: "es" } }
)

The $text expression can also accept the language by name, spanish. See Text Search Languages for the supported languages.

See also

Text Search in the Aggregation Pipeline

[1]
(1, 2) The behavior and requirements of the $meta operator differs from that of the $meta aggregation operator. See the $meta aggregation operator for details.

$where

$where

Use the $where operator to pass either a string containing a JavaScript expression or a full JavaScript function to the query system. The $where provides greater flexibility, but requires that the database processes the JavaScript expression or function for each document in the collection. Reference the document in the JavaScript expression or function using either this or obj .

Behavior

Restrictions

Changed in version 2.4.

In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties
Available Functions

args

MaxKey

MinKey

assert()

BinData()

DBPointer()

DBRef()

doassert()

emit()

gc()

HexData()

hex_md5()

isNumber()

isObject()

ISODate()

isString()

Map()

MD5()

NumberInt()

NumberLong()

ObjectId()

print()

printjson()

printjsononeline()

sleep()

Timestamp()

tojson()

tojsononeline()

tojsonObject()

UUID()

version()

elemMatch

Changed in version 2.6.

Only apply the $where query operator to top-level documents. The $where query operator will not work inside a nested document, for instance, in an $elemMatch query.

Considerations

Do not write to the database within the $where JavaScript function.

$where evaluates JavaScript and cannot take advantage of indexes. Therefore, query performance improves when you express your query using the standard MongoDB operators (e.g., $gt, $in).

In general, you should use $where only when you can’t express your query using another operator. If you must use $where, try to include at least one other standard query operator to filter the result set. Using $where alone requires a table scan.

Using normal non-$where query statements provides the following performance advantages:

MongoDB will evaluate non-$where components of query before $where statements. If the non-$where statements match no documents, MongoDB will not perform any query evaluation using $where.

The non-$where query statements may use an index.

Examples

Consider the following examples:

db.myCollection.find( { $where: "this.credits == this.debits" } );
db.myCollection.find( { $where: "obj.credits == obj.debits" } );

db.myCollection.find( { $where: function() { return (this.credits == this.debits) } } );
db.myCollection.find( { $where: function() { return obj.credits == obj.debits; } } );

Additionally, if the query consists only of the $where operator, you can pass in just the JavaScript expression or JavaScript functions, as in the following examples:

db.myCollection.find( "this.credits == this.debits || this.credits > this.debits" );

db.myCollection.find( function() { return (this.credits == this.debits || this.credits > this.debits ) } );

You can include both the standard MongoDB operators and the $where operator in your query, as in the following examples:

db.myCollection.find( { active: true, $where: "this.credits - this.debits < 0" } );
db.myCollection.find( { active: true, $where: function() { return obj.credits - obj.debits < 0; } } );

Geospatial Query Operators

Operators

Query Selectors

Name | Description
$geoWithin | Selects geometries within a bounding GeoJSON geometry. The 2dsphere and 2d indexes support $geoWithin.
$geoIntersects | Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects.
$near | Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near.
$nearSphere | Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d indexes support $nearSphere.

$geoWithin

$geoIntersects

$near

$nearSphere

Geometry Specifiers

Name | Description
$geometry | Specifies a geometry in GeoJSON format to geospatial query operators.
$minDistance | Specifies a minimum distance to limit the results of $near and $nearSphere queries. For use with 2dsphere index only.
$maxDistance | Specifies a maximum distance to limit the results of $near and $nearSphere queries. The 2dsphere and 2d indexes support $centerSphere.
$center | Specifies a circle using legacy coordinate pairs to $geoWithin queries when using planar geometry. The 2d index supports $center.
$centerSphere | Specifies a circle using either legacy coordinate pairs or GeoJSON format for $geoWithin queries when using spherical geometry. The 2dsphere and 2d indexes support $centerSphere.
$box | Specifies a rectangular box using legacy coordinate pairs for $geoWithin queries. The 2d index supports $box.
$polygon | Specifies a polygon to using legacy coordinate pairs for $geoWithin queries. The 2d index supports $center.
$uniqueDocs | Deprecated. Modifies a $geoWithin and $near queries to ensure that even if a document matches the query multiple times, the query returns the document once.

$geometry

$minDistance

$maxDistance

$center

$centerSphere

$box

$polygon

$uniqueDocs

Geospatial Query Compatibility

While numerous combinations of query operators are possible, the following table shows the recommended operators for different types of queries. The table uses the $geoWithin, $geoIntersects and $near operators.

Query Document
Geometry of the Query Condition
Surface Type for Query Calculation
Units for Query Calculation
Supported by this Index

Returns points, lines and polygons

{ $geoWithin : {
  $geometry : <GeoJSON Polygon>
} }

polygon
sphere
meters
2dsphere

{ $geoIntersects : {
  $geometry : <GeoJSON>
} }

point, line or polygon
sphere
meters
2dsphere

{ $near : {
  $geometry : <GeoJSON Point>,
  $maxDistance : d
} }

point
sphere
meters

2dsphere

The index is required.

Returns points only

{ $geoWithin : {
  $box : [[x1, y1], [x2, y2]]
} }

rectangle
flat
flat units
2d

{ $geoWithin : {
  $polygon : [[x1, y1],
              [x1, y2],
              [x2, y2],
              [x2, y1]]
} }

polygon
flat
flat units
2d

{ $geoWithin : {
  $center : [[x1, y1], r],
} }

circular region
flat
flat units
2d

{ $geoWithin : {
  $centerSphere :
    [[x, y], radius]
} }

circular region
sphere
radians

2d

2dsphere

{ $near : [x1, y1],
  $maxDistance : d
}

point
flat / flat units
flat units

2d

The index is required.

$geoWithin

Definition

$geoWithin

New in version 2.4: $geoWithin replaces $within which is deprecated.

Selects documents with geospatial data that exists entirely within a specified shape. When determining inclusion, MongoDB considers the border of a shape to be part of the shape, subject to the precision of floating point numbers.

$geoWithin does not require a geospatial index. However, a geospatial index will improve query performance. Both 2dsphere and 2d geospatial indexes support $geoWithin.

The specified shape can be either a GeoJSON Polygon (either single-ringed or multi-ringed), a GeoJSON MultiPolygon, or a shape defined by legacy coordinate pairs.

To specify a GeoJSON Polygon (either single-ringed or multi-ringed) or MultiPolygon, $geoWithin uses the $geometry operator to specify the shape and has the following form:

{
   <location field>: {
      $geoWithin: {
         $geometry: {
            type: <"Polygon" or "MultiPolygon"> ,
            coordinates: [ <coordinates> ]
         }
      }
   }
}

Important

If you use longitude and latitude, specify coordinates in order of longitude, latitude.

If querying for inclusion in a shape defined by legacy coordinate pairs on a plane, use the following syntax:

{
   <location field>: {
      $geoWithin: { <shape operator>: <coordinates> }
   }
}

The available shape operators are:

$box,

$polygon,

$center (defines a circle), and

$centerSphere (defines a circle on a sphere).

Behavior

The $geoWithin operator does not return sorted results. As such, MongoDB can return $geoWithin queries more quickly than geospatial $near or $nearSphere queries, which sort results.

For $geoWithin queries, GeoJSON geometries must have an area less than the area of a single hemisphere. For geometries larger than a single hemisphere, MongoDB queries for the smaller of the complementary geometries. For geometries equal to a single hemisphere, MongoDB makes no guarantees as to which geometry (the specified geometry or the complementary) it uses.

Example

The following example selects all loc data that exist entirely within a GeoJSON Polygon:

db.places.find(
   {
     loc: {
       $geoWithin: {
          $geometry: {
             type : "Polygon" ,
             coordinates: [ [ [ 0, 0 ], [ 3, 6 ], [ 6, 1 ], [ 0, 0 ] ] ]
          }
       }
     }
   }
)

$within

Deprecated since version 2.4: $geoWithin replaces $within in MongoDB 2.4.

$geoIntersects

Definition

$geoIntersects

New in version 2.4.

Selects documents whose geospatial data intersects with a specified GeoJSON object; i.e. where the intersection of the data and the specified object is non-empty. This includes cases where the data and the specified object share an edge. $geoIntersects uses spherical geometry.

$geoIntersects does not require a geospatial index. However, a geospatial index will improve query performance. Only the 2dsphere geospatial index supports $geoIntersects.

The $geoIntersects operator uses the $geometry operator to specify the GeoJSON object and has the following form:

{
   <location field>: {
     $geoIntersects: {
        $geometry: {
          type: "<GeoJSON object type>" ,
          coordinates: [ <coordinates> ]
        }
     }
   }
}

Important

If you use longitude and latitude, specify coordinates in order of: longitude, latitude.

Behavior

For $geoIntersects queries, GeoJSON geometries must have an area less than the area of a single hemisphere. For geometries larger than a single hemisphere, MongoDB queries for the smaller of the complementary geometries. For geometries equal to a single hemisphere, MongoDB makes no guarantees as to which geometry (the specified geometry or the complementary) it uses.

Example

The following example uses $geoIntersects to select all loc data that intersect with the Polygon defined by the coordinates array.

db.places.find(
   {
     loc: {
       $geoIntersects: {
          $geometry: {
             type: "Polygon" ,
             coordinates: [
               [ [ 0, 0 ], [ 3, 6 ], [ 6, 1 ], [ 0, 0 ] ]
             ]
          }
       }
     }
   }
)

$near

Definition

$near

Specifies a point for which a geospatial query returns the documents from nearest to farthest. The $near operator can specify either a GeoJSON point or legacy coordinate point.

$near requires a geospatial index:

2dsphere index if specifying a GeoJSON point,

2d index if specifying a point using legacy coordinates.

To specify a GeoJSON point, $near operator requires a 2dsphere index and has the following syntax:

{
  $near: {
     $geometry: {
        type: "Point" ,
        coordinates: [ <longitude> , <latitude> ]
     },
     $maxDistance: <distance in meters>,
     $minDistance: <distance in meters>
  }
}

When specifying a GeoJSON point, you can use the optional $minDistance and $maxDistance specifications to limit the $near results by distance in meters:

$minDistance limits the results to those documents that are at least the specified distance from the center point. $minDistance is only available for use with 2dsphere index.

New in version 2.6.

$maxDistance limits the results to those documents that are at most the specified distance from the center point.

To specify a point using legacy coordinates, $near requires a 2d index and has the following syntax:

{
  $near: [ <x>, <y> ],
  $maxDistance: <distance in radians>
}

If you use longitude and latitude for legacy coordinates, specify the longitude first, then latitude.

When specifying a legacy coordinate, you can use the optional $maxDistance specification to limit the $near results by distance in radians. $maxDistance limits the results to those documents that are at most the specified distance from the center point.

Behavior

$near queries that use a 2d index return a limit of 100 documents.

You cannot combine the $near operator, which requires a special geospatial index, with a query operator or command that uses a different type of special index. For example you cannot combine $near with the $text query.

If using a 2d index for $near, specifying a batch size (i.e. batchSize()) in conjunction with $near queries that use a 2d index is undefined. See SERVER-5236 [https://jira.mongodb.org/browse/SERVER-5236] for more information.

For sharded collections, queries using $near are not supported. You can instead use either the geoNear command or the $geoNear aggregation stage.

$near always returns the documents sorted by distance. Any other sort order requires to sort the documents in memory, which can be inefficient. To return results in a different sort order, use the $geoWithin operator and the sort() method.

Examples

Query on GeoJSON Data

Important

Specify coordinates in this order: “longitude, latitude.”

Consider a collection places that has a 2dsphere index.

The following example returns documents that are at least 1000 meters from and at most 5000 meters from the specified GeoJSON point, sorted from nearest to farthest:

db.places.find(
   {
     location:
       { $near :
          {
            $geometry: { type: "Point",  coordinates: [ -73.9667, 40.78 ] },
            $minDistance: 1000,
            $maxDistance: 5000
          }
       }
   }
)

Query on Legacy Coordinates

Important

Specify coordinates in this order: “longitude, latitude.”

Consider a collection legacy2d that has a 2d index.

The following example returns documents that are at most 0.10 radians from the specified legacy coordinate pair, sorted from nearest to farthest:

db.legacy2d.find(
   { location : { $near : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)

The result set contains at most 100 documents.

$nearSphere

Definition

$nearSphere

Specifies a point for which a geospatial query returns the documents from nearest to farthest. MongoDB calculates distances for $nearSphere using spherical geometry.

$nearSphere requires a geospatial index:

2dsphere index for location data defined as GeoJSON points

2d index for location data defined as legacy coordinate pairs. To use a 2d index on GeoJSON points, create the index on the coordinates field of the GeoJSON object.

The $nearSphere operator can specify either a GeoJSON point or legacy coordinate point.

To specify a GeoJSON point, use the following syntax:

{
  $nearSphere: {
     $geometry: {
        type : "Point",
        coordinates : [ <longitude>, <latitude> ]
     },
     $minDistance: <distance in meters>,
     $maxDistance: <distance in meters>
  }
}

The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

New in version 2.6.

The optional $maxDistance is available for either index.

To specify a point using legacy coordinates, use the following syntax:

{
  $nearSphere: [ <x>, <y> ],
  $minDistance: <distance in radians>,
  $maxDistance: <distance in radians>
}

The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

New in version 2.6.

The optional $maxDistance is available for either index.

If you use longitude and latitude for legacy coordinates, specify the longitude first, then latitude.

Behavior

Queries that use a 2d index return at most 100 documents.

Examples

Specify Center Point Using GeoJSON

Consider a collection places that contains documents with a location field and has a 2dsphere index.

Then, the following example returns whose location is at least 1000 meters from and at most 5000 meters from the specified point, ordered from nearest to farthest:

db.places.find(
   {
     location: {
        $nearSphere: {
           $geometry: {
              type : "Point",
              coordinates : [ -73.9667, 40.78 ]
           },
           $minDistance: 1000,
           $maxDistance: 5000
        }
     }
   }
)

Specify Center Point Using Legacy Coordinates

2d Index

Consider a collection legacyPlaces that contains documents with legacy coordinates pairs in the location field and has a 2d index.

Then, the following example returns up to 100 documents whose location is at most 0.10 radians from the specified point, ordered from nearest to farthest:

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)

2dsphere Index

If the collection has a 2dsphere index instead, you can also specify the optional $minDistance specification. For example, the following example returns the documents whose location is at least 0.0004 radians from the specified point, ordered from nearest to farthest:

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $minDistance: 0.0004 } }
)

$geometry

$geometry

New in version 2.4.

The $geometry operator specifies a GeoJSON for a geospatial query operators. For details on using $geometry with an operator, see the following operators:

$geoWithin

$geoIntersects

$near

$minDistance

Definition

$minDistance

New in version 2.6.

Filters the results of a geospatial $near or $nearSphere query to those documents that are at least the specified distance from the center point.

$minDistance is available for use with 2dsphere index only.

If $near or $nearSphere query specifies the center point as a GeoJSON point, specify the distance as a non-negative number in meters.

If $nearSphere query specifies the center point as legacy coordinate pair, specify the distance as a non-negative number in radians. $near can only use the 2dsphere index if the query specifies the center point as a GeoJSON point.

Examples

Use with $near

Important

Specify coordinates in this order: “longitude, latitude.”

Consider a collection places that has a 2dsphere index.

The following example returns documents that are at least 1000 meters from and at most 5000 meters from the specified GeoJSON point, sorted from nearest to farthest:

db.places.find(
   {
     location:
       { $near :
          {
            $geometry: { type: "Point",  coordinates: [ -73.9667, 40.78 ] },
            $minDistance: 1000,
            $maxDistance: 5000
          }
       }
   }
)

Use with $nearSphere

Consider a collection places that contains documents with a location field and has a 2dsphere index.

Then, the following example returns whose location is at least 1000 meters from and at most 5000 meters from the specified point, ordered from nearest to farthest:

db.places.find(
   {
     location: {
        $nearSphere: {
           $geometry: {
              type : "Point",
              coordinates : [ -73.9667, 40.78 ]
           },
           $minDistance: 1000,
           $maxDistance: 5000
        }
     }
   }
)

For an example that specifies the center point as legacy coordinate pair, see $nearSphere

$maxDistance

Definition

$maxDistance

The $maxDistance operator constrains the results of a geospatial $near or $nearSphere query to the specified distance. The measuring units for the maximum distance are determined by the coordinate system in use. For GeoJSON point object, specify the distance in meters, not radians.

Changed in version 2.6: Specify a non-negative number for $maxDistance.

The 2dsphere and 2d geospatial indexes both support $maxDistance: .

Example

The following example query returns documents with location values that are 10 or fewer units from the point [ 100 , 100 ].

db.places.find( {
   loc: { $near: [ 100 , 100 ],  $maxDistance: 10 }
} )

MongoDB orders the results by their distance from [ 100 , 100 ]. The operation returns the first 100 results, unless you modify the query with the cursor.limit() method.

$center

Definition

$center

New in version 1.4.

The $center operator specifies a circle for a $geoWithin query. The query returns legacy coordinate pairs that are within the bounds of the circle. The operator does not return GeoJSON objects.

To use the $center operator, specify an array that contains:

The grid coordinates of the circle’s center point, and

The circle’s radius, as measured in the units used by the coordinate system.

{
   <location field>: {
      $geoWithin: { $center: [ [ <x>, <y> ] , <radius> ] }
   }
}

Important

If you use longitude and latitude, specify longitude first.

Behavior

The query calculates distances using flat (planar) geometry.

Changed in version 2.2.3: Applications can use $center without having a geospatial index. However, geospatial indexes support much faster queries than the unindexed equivalents. Before 2.2.3, a geospatial index must exist on a field holding coordinates before using any of the geospatial query operators.

Only the 2d geospatial index supports $center.

Example

The following example query returns all documents that have coordinates that exist within the circle centered on [ -74, 40.74 ] and with a radius of 10:

db.places.find(
   { loc: { $geoWithin: { $center: [ [-74, 40.74], 10 ] } } }
)

$centerSphere

Definition

$centerSphere

New in version 1.8.

Defines a circle for a geospatial query that uses spherical geometry. The query returns documents that are within the bounds of the circle. You can use the $centerSphere operator on both GeoJSON objects and legacy coordinate pairs.

To use $centerSphere, specify an array that contains:

The grid coordinates of the circle’s center point, and

The circle’s radius measured in radians. To calculate radians, see Calculate Distance Using Spherical Geometry.

{
   <location field>: {
      $geoWithin: { $centerSphere: [ [ <x>, <y> ], <radius> ] }
   }
}

Important

If you use longitude and latitude, specify longitude first.

Behavior

Changed in version 2.2.3: Applications can use $centerSphere without having a geospatial index. However, geospatial indexes support much faster queries than the unindexed equivalents. Before 2.2.3, a geospatial index must exist on a field holding coordinates before using any of the geospatial query operators.

Both 2dsphere and 2d geospatial indexes support $centerSphere.

Example

The following example queries grid coordinates and returns all documents within a 10 mile radius of longitude 88 W and latitude 30 N. The query converts the distance to radians by dividing by the approximate radius of the earth, 3959 miles:

db.places.find( {
  loc: { $geoWithin: { $centerSphere: [ [ -88, 30 ], 10/3959 ] } }
} )

$box

Definition

$box

Specifies a rectangle for a geospatial $geoWithin query to return documents that are within the bounds of the rectangle, according to their point-based location data. When used with the $box operator, $geoWithin returns documents based on grid coordinates and does not query for GeoJSON shapes.

To use the $box operator, you must specify the bottom left and top right corners of the rectangle in an array object:

{
  <location field>: {
     $geoWithin: {
        $box: [
          [ <bottom left coordinates> ],
          [ <upper right coordinates> ]
        ]
     }
  }
}

Important

If you use longitude and latitude, specify longitude first.

Behavior

The query calculates distances using flat (planar) geometry.

Changed in version 2.2.3: Applications can use $box without having a geospatial index. However, geospatial indexes support much faster queries than the unindexed equivalents. Before 2.2.3, a geospatial index must exist on a field holding coordinates before using any of the geospatial query operators.

Only the 2d geospatial index supports $box.

Example

The following example query returns all documents that are within the box having points at: [ 0 , 0 ], [ 0 , 100 ], [ 100 , 0 ], and [ 100 , 100 ].

db.places.find( {
   loc: { $geoWithin: { $box:  [ [ 0, 0 ], [ 100, 100 ] ] } }
} )

$polygon

Definition

$polygon

New in version 1.9.

Specifies a polygon for a geospatial $geoWithin query on legacy coordinate pairs. The query returns pairs that are within the bounds of the polygon. The operator does not query for GeoJSON objects.

To define the polygon, specify an array of coordinate points:

{
   <location field>: {
      $geoWithin: {
         $polygon: [ [ <x1> , <y1> ], [ <x2> , <y2> ], [ <x3> , <y3> ], ... ]
      }
   }
}

The last point is always implicitly connected to the first. You can specify as many points, i.e. sides, as you like.

Important

If you use longitude and latitude, specify longitude first.

Behavior

The $polygon operator calculates distances using flat (planar) geometry.

Changed in version 2.2.3: Applications can use $polygon without having a geospatial index. However, geospatial indexes support much faster queries than the unindexed equivalents. Before 2.2.3, a geospatial index must exist on a field holding coordinates before using any of the geospatial query operators.

Only the 2d geospatial index supports the $polygon operator.

Example

The following query returns all documents that have coordinates that exist within the polygon defined by [ 0 , 0 ], [ 3 , 6 ], and [ 6 , 0 ]:

db.places.find(
  {
     loc: {
       $geoWithin: { $polygon: [ [ 0 , 0 ], [ 3 , 6 ], [ 6 , 0 ] ] }
     }
  }
)

$uniqueDocs

Definition

$uniqueDocs

Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.

Returns a document only once for a geospatial query even if the document matches the query multiple times.

Query Operator Array

Name | Description
$all | Matches arrays that contain all elements specified in the query.
$elemMatch | Selects documents if element in the array field matches all the specified $elemMatch conditions.
$size | Selects documents if the array field is a specified size.

$all

$elemMatch (query)

$size

$all

$all

The $all operator selects the documents where the value of a field is an array that contains all the specified elements. To specify an $all expression, use the following prototype:

{ <field>: { $all: [ <value1> , <value2> ... ] } }

Behavior

Equivalent to $and Operation

Changed in version 2.6.

The $all is equivalent to an $and operation of the specified values; i.e. the following statement:

{ tags: { $all: [ "ssl" , "security" ] } }

is equivalent to:

{ $and: [ { tags: "ssl" }, { tags: "security" } ] }

Nested Array

Changed in version 2.6.

When passed an array of a nested array (e.g. [ [ "A" ] ] ), $all can now match documents where the field contains the nested array as an element (e.g. field: [ [ "A" ], ... ]), or the field equals the nested array (e.g. field: [ "A" ]).

For example, consider the following query [1]:

db.articles.find( { tags: { $all: [ [ "ssl", "security" ] ] } } )

The query is equivalent to:

db.articles.find( { $and: [ { tags: [ "ssl", "security" ] } ] } )

which is equivalent to:

db.articles.find( { tags: [ "ssl", "security" ] } )

As such, the $all expression can match documents where the tags field is an array that contains the nested array [ "ssl", "security" ] or is an array that equals the nested array:

tags: [ [ "ssl", "security" ], ... ]
tags: [ "ssl", "security" ]

This behavior for $all allows for more matches than previous versions of MongoDB. Earlier versions could only match documents where the field contains the nested array.

[1]
The $all expression with a single element is for illustrative purposes since the $all expression is unnecessary if matching only a single element. Instead, when matching a single element, a “contains” expression (i.e. arrayField: element ) is more suitable.

Performance

Queries that use the $all operator must scan all the documents that match the first element in the $all expression. As a result, even with an index to support the query, the operation may be long running, particularly when the first element in the $all expression is not very selective.

Examples

The following examples use the inventory collection that contains the documents:

{
   _id: ObjectId("5234cc89687ea597eabee675"),
   code: "xyz",
   tags: [ "school", "book", "bag", "headphone", "appliance" ],
   qty: [
          { size: "S", num: 10, color: "blue" },
          { size: "M", num: 45, color: "blue" },
          { size: "L", num: 100, color: "green" }
        ]
}

{
   _id: ObjectId("5234cc8a687ea597eabee676"),
   code: "abc",
   tags: [ "appliance", "school", "book" ],
   qty: [
          { size: "6", num: 100, color: "green" },
          { size: "6", num: 50, color: "blue" },
          { size: "8", num: 100, color: "brown" }
        ]
}

{
   _id: ObjectId("5234ccb7687ea597eabee677"),
   code: "efg",
   tags: [ "school", "book" ],
   qty: [
          { size: "S", num: 10, color: "blue" },
          { size: "M", num: 100, color: "blue" },
          { size: "L", num: 100, color: "green" }
        ]
}

{
   _id: ObjectId("52350353b2eff1353b349de9"),
   code: "ijk",
   tags: [ "electronics", "school" ],
   qty: [
          { size: "M", num: 100, color: "green" }
        ]
}

Use $all to Match Values

The following operation uses the $all operator to query the inventory collection for documents where the value of the tags field is an array whose elements include appliance, school, and book:

db.inventory.find( { tags: { $all: [ "appliance", "school", "book" ] } } )

The above query returns the following documents:

{
   _id: ObjectId("5234cc89687ea597eabee675"),
   code: "xyz",
   tags: [ "school", "book", "bag", "headphone", "appliance" ],
   qty: [
          { size: "S", num: 10, color: "blue" },
          { size: "M", num: 45, color: "blue" },
          { size: "L", num: 100, color: "green" }
        ]
}

{
   _id: ObjectId("5234cc8a687ea597eabee676"),
   code: "abc",
   tags: [ "appliance", "school", "book" ],
   qty: [
          { size: "6", num: 100, color: "green" },
          { size: "6", num: 50, color: "blue" },
          { size: "8", num: 100, color: "brown" }
        ]
}

Use $all with $elemMatch

If the field contains an array of documents, you can use the $all with the $elemMatch operator.

The following operation queries the inventory collection for documents where the value of the qty field is an array whose elements match the $elemMatch criteria:

db.inventory.find( {
                     qty: { $all: [
                                    { "$elemMatch" : { size: "M", num: { $gt: 50} } },
                                    { "$elemMatch" : { num : 100, color: "green" } }
                                  ] }
                   } )

The query returns the following documents:

{
   "_id" : ObjectId("5234ccb7687ea597eabee677"),
   "code" : "efg",
   "tags" : [ "school", "book"],
   "qty" : [
             { "size" : "S", "num" : 10, "color" : "blue" },
             { "size" : "M", "num" : 100, "color" : "blue" },
             { "size" : "L", "num" : 100, "color" : "green" }
           ]
}

{
   "_id" : ObjectId("52350353b2eff1353b349de9"),
   "code" : "ijk",
   "tags" : [ "electronics", "school" ],
   "qty" : [
             { "size" : "M", "num" : 100, "color" : "green" }
           ]
}

The $all operator exists to support queries on arrays. But you may use the $all operator to select against a non-array field, as in the following example:

db.inventory.find( { "qty.num": { $all: [ 50 ] } } )

However, use the following form to express the same query:

db.inventory.find( { "qty.num" : 50 } )

Both queries will select all documents in the inventory collection where the value of the num field equals 50.

Note

In most cases, MongoDB does not treat arrays as sets. This operator provides a notable exception to this approach.

See also

find(), update(), and $set.

$elemMatch (query)

See also

$elemMatch (projection)

Definition

$elemMatch

The $elemMatch operator matches documents that contain an array field with at least one element that matches all the specified query criteria.

{ <field>: { $elemMatch: { <query1>, <query2>, ... } } }

If you specify only a single <query> condition in the $elemMatch expression, you do not need to use $elemMatch.

Behavior

You cannot specify a $where expression as a query criterion for $elemMatch.

Examples

Element Match

Given the following documents in the scores collection:

{ _id: 1, results: [ 82, 85, 88 ] }
{ _id: 2, results: [ 75, 88, 89 ] }

The following query matches only those documents where the results array contains at least one element that is both greater than or equal to 80 and is less than 85.

db.scores.find(
   { results: { $elemMatch: { $gte: 80, $lt: 85 } } }
)

The query returns the following document since the element 82 is both greater than or equal to 80 and is less than 85

{ "_id" : 1, "results" : [ 82, 85, 88 ] }

For more information on specifying multiple criteria on array elements, see Specify Multiple Criteria for Array Elements.

Array of Embedded Documents

Given the following documents in the survey collection:

{ _id: 1, results: [ { product: "abc", score: 10 }, { product: "xyz", score: 5 } ] }
{ _id: 2, results: [ { product: "abc", score: 8 }, { product: "xyz", score: 7 } ] }
{ _id: 3, results: [ { product: "abc", score: 7 }, { product: "xyz", score: 8 } ] }

The following query matches only those documents where the results array contains at least one element with both product equal to "xyz" and score greater than or equal to 8.

db.survey.find(
   { results: { $elemMatch: { product: "xyz", score: { $gte: 8 } } } }
)

Specifically, the query matches the following document:

{ "_id" : 3, "results" : [ { "product" : "abc", "score" : 7 }, { "product" : "xyz", "score" : 8 } ] }

Single Query Condition

If you specify a single query predicate in the $elemMatch expression, $elemMatch is not necessary.

For example, consider the following example where $elemMatch specifies only a single query predicate { product: "xyz" }:

db.survey.find(
   { results: { $elemMatch: { product: "xyz" } } }
)

Since the $elemMatch only specifies a single condition, the $elemMatch expression is not necessary, and instead you can use the following query:

db.survey.find(
   { "results.product": "xyz" }
)

For more information on querying arrays, see Arrays, including Specify Multiple Criteria for Array Elements and Array of Embedded Documents sections.

$size

$size

The $size operator matches any array with the number of elements specified by the argument. For example:

db.collection.find( { field: { $size: 2 } } );

returns all documents in collection where field is an array with 2 elements. For instance, the above expression will return { field: [ red, green ] } and { field: [ apple, lime ] } but not { field: fruit } or { field: [ orange, lemon, grapefruit ] }. To match fields with only one element within an array use $size with a value of 1, as follows:

db.collection.find( { field: { $size: 1 } } );

$size does not accept ranges of values. To select documents based on fields with different numbers of elements, create a counter field that you increment when you add elements to a field.

Queries cannot use indexes for the $size portion of a query, although the other portions of a query can use indexes if applicable.

$comment

Definition

$comment

The $comment query operator associates a comment to any expression taking a query predicate.

Because comments propagate to the profile log, adding a comment can make your profile data easier to interpret and trace.

The $comment operator has the form:

db.collection.find( { <query>, $comment: <comment> } )

Behavior

You can use the $comment with any expression taking a query predicate, such as the query predicate in db.collection.update() or in the $match stage of the aggregation pipeline. For an example, see Attach a Comment to an Aggregation Expression.

Examples

Attach a Comment to find

The following example adds a $comment to a find() operation :

db.records.find(
   {
     x: { $mod: [ 2, 0 ] },
     $comment: "Find even values."
   }
)

Attach a Comment to an Aggregation Expression

You can use the $comment with any expression taking a query predicate.

The following examples uses the $comment operator in the $match stage to clarify the operation:

db.records.aggregate( [
   { $match: { x: { $gt: 0 }, $comment: "Don't allow negative inputs." } },
   { $group : { _id: { $mod: [ "$x", 2 ] }, total: { $sum: "$x" } } }
] )

See also

$comment

Projection Operators

Name | Description
$ | Projects the first element in an array that matches the query condition.
$elemMatch | Projects the first element in an array that matches the specified $elemMatch condition.
$meta | Projects the document’s score assigned during $text operation.
$slice | Limits the number of elements projected from an array. Supports skip and limit slices.

$ (projection)

$elemMatch (projection)

$meta

$slice (projection)

$ (projection)

Definition

$

The positional $ operator limits the contents of an <array> from the query results to contain only the first element matching the query document. To specify an array element to update, see the positional $ operator for updates.

Use $ in the projection document of the find() method or the findOne() method when you only need one particular array element in selected documents.

Usage Considerations

Both the $ operator and the $elemMatch operator project a subset of elements from an array based on a condition.

The $ operator projects the array elements based on some condition from the query statement.

The $elemMatch projection operator takes an explicit condition argument. This allows you to project based on a condition not in the query, or if you need to project based on multiple fields in the array’s embedded documents. See Array Field Limitations for an example.

Behavior

Usage Requirements

Given the form:

db.collection.find( { <array>: <value> ... },
                    { "<array>.$": 1 } )
db.collection.find( { <array.field>: <value> ...},
                    { "<array>.$": 1 } )

The <array> field being limited must appear in the query document, and the <value> can be documents that contain query operator expressions.

Array Field Limitations

MongoDB requires the following when dealing with projection over arrays:

Only one positional $ operator may appear in the projection document.

Only one array field may appear in the query document.

The query document should only contain a single condition on the array field being projected. Multiple conditions may override each other internally and lead to undefined behavior.

Under these requirements, the following query is incorrect:

db.collection.find( { <array>: <value>, <someOtherArray>: <value2> },
                    { "<array>.$": 1 } )

To specify criteria on multiple fields of documents inside that array, use the $elemMatch query operator. The following query will return any embedded documents inside a grades array that have a mean of greater than 70 and a grade of greater than 90.

db.students.find( { grades: { $elemMatch: {
                                            mean: { $gt: 70 },
                                            grade: { $gt:90 }
                                          } } },
                  { "grades.$": 1 } )

You must use the $elemMatch operator if you need separate conditions for selecting documents and for choosing fields within those documents.

Sorts and the Positional Operator

When the find() method includes a sort(), the find() method applies the sort() to order the matching documents before it applies the positional $ projection operator.

If an array field contains multiple documents with the same field name and the find() method includes a sort() on that repeating field, the returned documents may not reflect the sort order because the sort was applied to the elements of the array before the $ projection operator.

Examples

Project Array Values

A collection students contains the following documents:

{ "_id" : 1, "semester" : 1, "grades" : [ 70, 87, 90 ] }
{ "_id" : 2, "semester" : 1, "grades" : [ 90, 88, 92 ] }
{ "_id" : 3, "semester" : 1, "grades" : [ 85, 100, 90 ] }
{ "_id" : 4, "semester" : 2, "grades" : [ 79, 85, 80 ] }
{ "_id" : 5, "semester" : 2, "grades" : [ 88, 88, 92 ] }
{ "_id" : 6, "semester" : 2, "grades" : [ 95, 90, 96 ] }

In the following query, the projection { "grades.$": 1 } returns only the first element greater than or equal to 85 for the grades field.

db.students.find( { semester: 1, grades: { $gte: 85 } },
                  { "grades.$": 1 } )

The operation returns the following documents:

{ "_id" : 1, "grades" : [ 87 ] }
{ "_id" : 2, "grades" : [ 90 ] }
{ "_id" : 3, "grades" : [ 85 ] }

Although the array field grades may contain multiple elements that are greater than or equal to 85, the $ projection operator returns only the first matching element from the array.

Project Array Documents

A students collection contains the following documents where the grades field is an array of documents; each document contain the three field names grade, mean, and std:

{ "_id" : 7, semester: 3, "grades" : [ { grade: 80, mean: 75, std: 8 },
                                       { grade: 85, mean: 90, std: 5 },
                                       { grade: 90, mean: 85, std: 3 } ] }

{ "_id" : 8, semester: 3, "grades" : [ { grade: 92, mean: 88, std: 8 },
                                       { grade: 78, mean: 90, std: 5 },
                                       { grade: 88, mean: 85, std: 3 } ] }

In the following query, the projection { "grades.$": 1 } returns only the first element with the mean greater than 70 for the grades field:

db.students.find(
   { "grades.mean": { $gt: 70 } },
   { "grades.$": 1 }
)

The operation returns the following documents:

{ "_id" : 7, "grades" : [  {  "grade" : 80,  "mean" : 75,  "std" : 8 } ] }
{ "_id" : 8, "grades" : [  {  "grade" : 92,  "mean" : 88,  "std" : 8 } ] }

Further Reading

$elemMatch (projection)

$elemMatch (projection)

See also

$elemMatch (query)

Definition

$elemMatch

New in version 2.2.

The $elemMatch operator limits the contents of an <array> field from the query results to contain only the first element matching the $elemMatch condition.

Usage Considerations

Both the $ operator and the $elemMatch operator project a subset of elements from an array based on a condition.

The $ operator projects the array elements based on some condition from the query statement.

The $elemMatch projection operator takes an explicit condition argument. This allows you to project based on a condition not in the query, or if you need to project based on multiple fields in the array’s embedded documents. See Array Field Limitations for an example.

Examples

The examples on the $elemMatch projection operator assumes a collection school with the following documents:

{
 _id: 1,
 zipcode: "63109",
 students: [
              { name: "john", school: 102, age: 10 },
              { name: "jess", school: 102, age: 11 },
              { name: "jeff", school: 108, age: 15 }
           ]
}
{
 _id: 2,
 zipcode: "63110",
 students: [
              { name: "ajax", school: 100, age: 7 },
              { name: "achilles", school: 100, age: 8 },
           ]
}
{
 _id: 3,
 zipcode: "63109",
 students: [
              { name: "ajax", school: 100, age: 7 },
              { name: "achilles", school: 100, age: 8 },
           ]
}
{
 _id: 4,
 zipcode: "63109",
 students: [
              { name: "barney", school: 102, age: 7 },
              { name: "ruth", school: 102, age: 16 },
           ]
}

Zipcode Search

The following find() operation queries for all documents where the value of the zipcode field is 63109. The $elemMatch projection returns only the first matching element of the students array where the school field has a value of 102:

db.schools.find( { zipcode: "63109" },
                 { students: { $elemMatch: { school: 102 } } } )

The operation returns the following documents:

{ "_id" : 1, "students" : [ { "name" : "john", "school" : 102, "age" : 10 } ] }
{ "_id" : 3 }
{ "_id" : 4, "students" : [ { "name" : "barney", "school" : 102, "age" : 7 } ] }

For the document with _id equal to 1, the students array contains multiple elements with the school field equal to 102. However, the $elemMatch projection returns only the first matching element from the array.

The document with _id equal to 3 does not contain the students field in the result since no element in its students array matched the $elemMatch condition.

$elemMatch with Multiple Fields

The $elemMatch projection can specify criteria on multiple fields:

The following find() operation queries for all documents where the value of the zipcode field is 63109. The projection includes the first matching element of the students array where the school field has a value of 102 and the age field is greater than 10:

db.schools.find( { zipcode: "63109" },
                 { students: { $elemMatch: { school: 102, age: { $gt: 10} } } } )

The operation returns the three documents that have zipcode equal to 63109:

{ "_id" : 1, "students" : [ { "name" : "jess", "school" : 102, "age" : 11 } ] }
{ "_id" : 3 }
{ "_id" : 4, "students" : [ { "name" : "ruth", "school" : 102, "age" : 16 } ] }

The document with _id equal to 3 does not contain the students field since no array element matched the $elemMatch criteria.

$elemMatch with sort()

When the find() method includes a sort(), the find() method applies the sort() to order the matching documents before it applies the projection. This is a general rule when sorting and projecting, and is discussed in Interaction with Projection.

If an array field contains multiple documents with the same field name and the find() method includes a sort() on that repeating field, the returned documents may not reflect the sort order because the sort() was applied to the elements of the array before the $elemMatch projection.

An array’s sorting value is taken from either its “minimum” or “maximum” value, depending on which way the sorting goes. The way that sort() sorts documents containing arrays is described in Ascending/Descending Sort.

The following query includes a sort() to order by descending students.age field:

db.schools.find(
                 { zipcode: "63109" },
                 { students: { $elemMatch: { school: 102 } } }
               ).sort( { "students.age": -1 } )

The operation applies the sort() to order the documents that have the field zipcode equal to 63109 and then applies the projection. The operation returns the three documents in the following order:

{ "_id" : 4, "students" : [ { "name" : "barney", "school" : 102, "age" : 7 } ] }
{ "_id" : 1, "students" : [ { "name" : "john", "school" : 102, "age" : 10 } ] }
{ "_id" : 3 }

Even though the sort is descending, the younger student is listed first. This is because the sort occurred before the older students in Barney’s document were projected out.

See also

$ (projection) operator

$meta

$meta

New in version 2.6.

The $meta projection operator returns for each matching document the metadata (e.g. "textScore") associated with the query.

A $meta expression has the following syntax:

{ $meta: <metaDataKeyword> }

The $meta expression can specify the following keyword as the <metaDataKeyword>:

Keyword | Description | Sort Order
"textScore" | Returns the score associated with the corresponding $text query for each matching document. The text score signifies how well the document matched the stemmed term or terms. If not used in conjunction with a $text query, returns a score of 0. | Descending

Behaviors

The $meta expression can be a part of the projection document as well as a sort() expression as:

{ <projectedFieldName>: { $meta: "textScore" } }

Projected Field Name

The <projectedFieldName> cannot include a dot (.) in the name.

If the specified <projectedFieldName> already exists in the matching documents, in the result set, the existing fields will return with the $meta values instead of with the stored values.

Projection

The $meta expression can be used in the projection document, as in:

db.collection.find(
   <query>,
   { score: { $meta: "textScore" } }
)

The $meta expression specifies the inclusion of the field to the result set and does not specify the exclusion of the other fields.

The $meta expression can be a part of a projection document that specifies exclusions of other fields or that specifies inclusions of other fields.

The metadata returns information on the processing of the <query> operation. As such, the returned metadata, assigned to the <projectedFieldName>, has no meaning inside a <query> expression; i.e. specifying a condition on the <projectedFieldName> as part of the <query> is similar to specifying a condition on a non-existing field if no field exists in the documents with the <projectedFieldName>.

Sort

The $meta expression can be part of a sort() expression, as in:

db.collection.find(
   <query>,
   { score: { $meta: "textScore" } }
).sort( { score: { $meta: "textScore" } } )

To include a $meta expression in a sort() expression, the same $meta expression, including the <projectedFieldName>, must appear in the projection document. The specified metadata determines the sort order. For example, the "textScore" metadata sorts in descending order.

For additional examples, see Text Search with Additional Query and Sort Expressions.

Examples

For examples of "textScore" projections and sorts, see $text.

$slice (projection)

$slice

The $slice operator controls the number of items of an array that a query returns. For information on limiting the size of an array during an update with $push, see the $slice modifier instead.

Consider the following prototype query:

db.collection.find( { field: value }, { array: {$slice: count } } );

This operation selects the document collection identified by a field named field that holds value and returns the number of elements specified by the value of count from the array stored in the array field. If count has a value greater than the number of elements in array the query returns all elements of the array.

$slice accepts arguments in a number of formats, including negative values and arrays. Consider the following examples:

db.posts.find( {}, { comments: { $slice: 5 } } )

Here, $slice selects the first five items in an array in the comments field.

db.posts.find( {}, { comments: { $slice: -5 } } )

This operation returns the last five items in array.

The following examples specify an array as an argument to $slice. Arrays take the form of [ skip , limit ], where the first value indicates the number of items in the array to skip and the second value indicates the number of items to return.

db.posts.find( {}, { comments: { $slice: [ 20, 10 ] } } )

Here, the query will only return 10 items, after skipping the first 20 items of that array.

db.posts.find( {}, { comments: { $slice: [ -20, 10 ] } } )

This operation returns 10 items as well, beginning with the item that is 20th from the last item of the array.

Update Operators

The following modifiers are available for use in update operations; e.g. in db.collection.update() and db.collection.findAndModify().

Update Operators

Fields

Field Update Operators

$inc

$mul

$rename

$setOnInsert

$set

$unset

$min

$max

$currentDate

Array

Array Update Operators

$ (update)

$addToSet

$pop

$pullAll

$pull

$pushAll

$push

$each

$slice

$sort

$position

Bitwise

Bitwise Update Operator

$bit

Isolation

Isolation Update Operator

$isolated

Field Update Operators

Name | Description
$inc | Increments the value of the field by the specified amount.
$mul | Multiplies the value of the field by the specified amount.
$rename | Renames a field.
$setOnInsert | Sets the value of a field if an update results in an insert of a document. Has no effect on update operations that modify existing documents.
$set | Sets the value of a field in a document.
$unset | Removes the specified field from a document.
$min | Only updates the field if the specified value is less than the existing field value.
$max | Only updates the field if the specified value is greater than the existing field value.
$currentDate | Sets the value of a field to current date, either as a Date or a Timestamp.

$inc

$mul

$rename

$setOnInsert

$set

$unset

$min

$max

$currentDate

$inc

Definition

$inc

The $inc operator increments a field by a specified value and has the following form:

{ $inc: { <field1>: <amount1>, <field2>: <amount2>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

The $inc operator accepts positive and negative values.

If the field does not exist, $inc creates the field and sets the field to the specified value.

Use of the $inc operator on a field with a null value will generate an error.

$inc is an atomic operation within a single document.

Example

Consider a collection products with the following document:

{
  _id: 1,
  sku: "abc123",
  quantity: 10,
  metrics: {
    orders: 2,
    ratings: 3.5
  }
}

The following update() operation uses the $inc operator to decrease the quantity field by 2 (i.e. increase by -2) and increase the "metrics.orders" field by 1:

db.products.update(
   { sku: "abc123" },
   { $inc: { quantity: -2, "metrics.orders": 1 } }
)

The updated document would resemble:

{
   "_id" : 1,
   "sku" : "abc123",
   "quantity" : 8,
   "metrics" : {
      "orders" : 3,
      "ratings" : 3.5
   }
}

See also

db.collection.update(), db.collection.findAndModify()

$mul

Definition

$mul

New in version 2.6.

Multiply the value of a field by a number. To specify a $mul expression, use the following prototype:

{ $mul: { field: <number> } }

The field to update must contain a numeric value.

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exist in a document, $mul creates the field and sets the value to zero of the same numeric type as the multiplier.

Multiplication with values of mixed numeric types (32-bit integer, 64-bit integer, float) may result in conversion of numeric type. See Multiplication Type Conversion Rules for details.

$mul is an atomic operation within a single document.

Examples

Multiply the Value of a Field

Consider a collection products with the following document:

{ _id: 1, item: "ABC", price: 10.99 }

The following db.collection.update() operation updates the document, using the $mul operator to multiply the value in the price field by 1.25:

db.products.update(
   { _id: 1 },
   { $mul: { price: 1.25 } }
)

The operation results in the following document, where the new value of the price field 13.7375 reflects the original value 10.99 multiplied by 1.25:

{ _id: 1, item: "ABC", price: 13.7375 }

Apply $mul Operator to a Non-existing Field

Consider a collection products with the following document:

{ _id: 2,  item: "Unknown" }

The following db.collection.update() operation updates the document, applying the $mul operator to the field price that does not exist in the document:

db.products.update(
   { _id: 2 },
   { $mul: { price: NumberLong(100) } }
)

The operation results in the following document with a price field set to value 0 of numeric type NumberLong, the same type as the multiplier:

{ "_id" : 2, "item" : "Unknown", "price" : NumberLong(0) }

Multiply Mixed Numeric Types

Consider a collection products with the following document:

{ _id: 3,  item: "XYZ", price: NumberLong(10) }

The following db.collection.update() operation uses the $mul operator to multiply the value in the price field NumberLong(10) by NumberInt(5):

db.products.update(
   { _id: 3 },
   { $mul: { price: NumberInt(5) } }
)

The operation results in the following document:

{ "_id" : 3, "item" : "XYZ", "price" : NumberLong(50) }

The value in the price field is of type NumberLong. See Multiplication Type Conversion Rules for details.

See also

db.collection.update(), db.collection.findAndModify()

$rename

Definition

$rename

The $rename operator updates the name of a field and has the following form:

{$rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }

The new field name must differ from the existing field name. To specify a <field> in an embedded document, use dot notation.

Consider the following example:

db.students.update( { _id: 1 }, { $rename: { 'nickname': 'alias', 'cell': 'mobile' } } )

This operation renames the field nickname to alias, and the field cell to mobile.

Behavior

The $rename operator logically performs an $unset of both the old name and the new name, and then performs a $set operation with the new name. As such, the operation may not preserve the order of the fields in the document; i.e. the renamed field may move within the document.

If the document already has a field with the <newName>, the $rename operator removes that field and renames the specified <field> to <newName>.

If the field to rename does not exist in a document, $rename does nothing (i.e. no operation).

For fields in embedded documents, the $rename operator can rename these fields as well as move the fields in and out of embedded documents. $rename does not work if these fields are in array elements.

Examples

A collection students the following document where a field nmae appears misspelled, i.e. should be name:

{ "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "nmae": { "first" : "george", "last" : "washington" }
}

The examples in this section successively updates this document.

Rename a Field

To rename a field, call the $rename operator with the current name of the field and the new name:

db.students.update( { _id: 1 }, { $rename: { "nmae": "name" } } )

This operation renames the field nmae to name:

{
  "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "name": { "first" : "george", "last" : "washington" }
}

Rename a Field in an Embedded Document

To rename a field in an embedded document, call the $rename operator using the dot notation to refer to the field. If the field is to remain in the same embedded document, also use the dot notation in the new name, as in the following:

db.students.update( { _id: 1 }, { $rename: { "name.first": "name.fname" } } )

This operation renames the embedded field first to fname:

{
  "_id" : 1,
  "alias" : [ "The American Cincinnatus", "The American Fabius" ],
  "mobile" : "555-555-5555",
  "name" : { "fname" : "george", "last" : "washington" }
}

Rename a Field That Does Not Exist

When renaming a field and the existing field name refers to a field that does not exist, the $rename operator does nothing, as in the following:

db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse' } } )

This operation does nothing because there is no field named wife.

See also

db.collection.update(), db.collection.findAndModify()

$setOnInsert

Definition

$setOnInsert

New in version 2.4.

If an update operation with upsert: true results in an insert of a document, then $setOnInsert assigns the specified values to the fields in the document. If the update operation does not result in an insert, $setOnInsert does nothing.

You can specify the upsert option for either the db.collection.update() or db.collection.findAndModify() methods.

db.collection.update(
   <query>,
   { $setOnInsert: { <field1>: <value1>, ... } },
   { upsert: true }
)

To specify a <field> in an embedded document or in an array, use dot notation.

Example

A collection named products contains no documents.

Then, the following db.collection.update() with upsert: true inserts a new document.

db.products.update(
  { _id: 1 },
  {
     $set: { item: "apple" },
     $setOnInsert: { defaultQty: 100 }
  },
  { upsert: true }
)

MongoDB creates a new document with _id equal to 1 from the <query> condition, and then applies the $set and $setOnInsert operations to this document.

The products collection contains the newly-inserted document:

{ "_id" : 1, "item" : "apple", "defaultQty" : 100 }

If the db.collection.update() with upsert: true had found a matching document, then MongoDB performs an update, applying the $set operation but ignoring the $setOnInsert operation.

See also

db.collection.update(), db.collection.findAndModify()

$set

Definition

$set

The $set operator replaces the value of a field with the specified value.

The $set operator expression has the following form:

{ $set: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exist, $set will add a new field with the specified value, provided that the new field does not violate a type constraint. If you specify a dotted path for a non-existent field, $set will create the embedded documents as needed to fulfill the dotted path to the field.

If you specify multiple field-value pairs, $set will update or create each field.

Examples

Consider a collection products with the following document:

{
  _id: 100,
  sku: "abc123",
  quantity: 250,
  instock: true,
  reorder: false,
  details: { model: "14Q2", make: "xyz" },
  tags: [ "apparel", "clothing" ],
  ratings: [ { by: "ijk", rating: 4 } ]
}

Set Top-Level Fields

For the document matching the criteria _id equal to 100, the following operation uses the $set operator to update the value of the quantity field, details field, and the tags field.

db.products.update(
   { _id: 100 },
   { $set:
      {
        quantity: 500,
        details: { model: "14Q3", make: "xyz" },
        tags: [ "coats", "outerwear", "clothing" ]
      }
   }
)

The operation replaces the value of: quantity to 500; the details field to a new embedded document, and the tags field to a new array.

Set Fields in Embedded Documents

To specify a <field> in an embedded document or in an array, use dot notation.

For the document matching the criteria _id equal to 100, the following operation updates the make field in the details document:

db.products.update(
   { _id: 100 },
   { $set: { "details.make": "zzz" } }
)

Set Elements in Arrays

To specify a <field> in an embedded document or in an array, use dot notation.

For the document matching the criteria _id equal to 100, the following operation update the value second element (array index of 1) in the tags field and the rating field in the first element (array index of 0) of the ratings array.

db.products.update(
   { _id: 100 },
   { $set:
      {
        "tags.1": "rain gear",
        "ratings.0.rating": 2
      }
   }
)

For additional update operators for arrays, see Array Update Operators.

See also

db.collection.update(), db.collection.findAndModify()

$unset

$unset

The $unset operator deletes a particular field. Consider the following syntax:

{ $unset: { <field1>: "", ... } }

The specified value in the $unset expression (i.e. "") does not impact the operation.

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exist, then $unset does nothing (i.e. no operation).

When used with $ to match an array element, $unset replaces the matching element with null rather than removing the matching element from the array. This behavior keeps consistent the array size and element positions.

Example

The following update() operation uses the $unset operator to remove the fields quantity and instock from the first document in the products collection where the field sku has a value of unknown.

db.products.update(
   { sku: "unknown" },
   { $unset: { quantity: "", instock: "" } }
)

See also

db.collection.update(), db.collection.findAndModify()

$min

Definition

$min

The $min updates the value of the field to a specified value if the specified value is less than the current value of the field. The $min operator can compare values of different types, using the BSON comparison order.

{ $min: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exists, the $min operator sets the field to the specified value.

Examples

Use $min to Compare Numbers

Consider the following document in the collection scores:

{ _id: 1, highScore: 800, lowScore: 200 }

The lowScore for the document currently has the value 200. The following operation uses $min to compare 200 to the specified value 150 and updates the value of lowScore to 150 since 150 is less than 200:

db.scores.update( { _id: 1 }, { $min: { lowScore: 150 } } )

The scores collection now contains the following modified document:

{ _id: 1, highScore: 800, lowScore: 150 }

The next operation has no effect since the current value of the field lowScore, i.e 150, is less than 200:

db.scores.update( { _id: 1 }, { $min: { lowScore: 250 } } )

The document remains unchanged in the scores collection:

{ _id: 1, highScore: 800, lowScore: 150 }

Use $min to Compare Dates

Consider the following document in the collection tags:

{
  _id: 1,
  desc: "crafts",
  dateEntered: ISODate("2013-10-01T05:00:00Z"),
  dateExpired: ISODate("2013-10-01T16:38:16Z")
}

The following operation compares the current value of the dateEntered field, i.e. ISODate("2013-10-01T05:00:00Z"), with the specified date new Date("2013-09-25") to determine whether to update the field:

db.tags.update(
   { _id: 1 },
   { $min: { dateEntered: new Date("2013-09-25") } }
)

The operation updates the dateEntered field:

{
  _id: 1,
  desc: "crafts",
  dateEntered: ISODate("2013-09-25T00:00:00Z"),
  dateExpired: ISODate("2013-10-01T16:38:16Z")
}

See also

db.collection.update(), db.collection.findAndModify()

$max

Definition

$max

The $max operator updates the value of the field to a specified value if the specified value is greater than the current value of the field. The $max operator can compare values of different types, using the BSON comparison order.

The $max operator expression has the form:

{ $max: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exists, the $max operator sets the field to the specified value.

Examples

Use $max to Compare Numbers

Consider the following document in the collection scores:

{ _id: 1, highScore: 800, lowScore: 200 }

The highScore for the document currently has the value 800. The following operation uses $max to compare the 800 and the specified value 950 and updates the value of highScore to 950 since 950 is greater than 800:

db.scores.update( { _id: 1 }, { $max: { highScore: 950 } } )

The scores collection now contains the following modified document:

{ _id: 1, highScore: 950, lowScore: 200 }

The next operation has no effect since the current value of the field highScore, i.e. 950, is greater than 870:

db.scores.update( { _id: 1 }, { $max: { highScore: 870 } } )

The document remains unchanged in the scores collection:

{ _id: 1, highScore: 950, lowScore: 200 }

Use $max to Compare Dates

Consider the following document in the collection tags:

{
  _id: 1,
  desc: "crafts",
  dateEntered: ISODate("2013-10-01T05:00:00Z"),
  dateExpired: ISODate("2013-10-01T16:38:16.163Z")
}

The following operation compares the current value of the dateExpired field, i.e. ISODate("2013-10-01T16:38:16.163Z"), with the specified date new Date("2013-09-30") to determine whether to update the field:

db.tags.update(
   { _id: 1 },
   { $max: { dateExpired: new Date("2013-09-30") } }
)

The operation does not update the dateExpired field:

{
   _id: 1,
   desc: "decorative arts",
   dateEntered: ISODate("2013-10-01T05:00:00Z"),
   dateExpired: ISODate("2013-10-01T16:38:16.163Z")
}

See also

db.collection.update(), db.collection.findAndModify()

$currentDate

Definition

$currentDate

The $currentDate operator sets the value of a field to the current date, either as a Date or a timestamp. The default type is Date.

The $currentDate operator has the form:

{ $currentDate: { <field1>: <typeSpecification1>, ... } }

<typeSpecification> can be either:

a boolean true to set the field value to the current date as a Date, or

a document { $type: "timestamp" } or { $type: "date" } which explicitly specifies the type. The operator is case-sensitive and accepts only the lowercase "timestamp" or the lowercase "date".

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field does not exist, $currentDate adds the field to a document.

Example

Consider the following document in the users collection:

{ _id: 1, status: "a", lastModified: ISODate("2013-10-02T01:11:18.965Z") }

The following operation updates the lastModified field to the current date, the "cancellation.date" field to the current timestamp as well as updating the status field to "D" and the "cancellation.reason" to "user request".

db.users.update(
   { _id: 1 },
   {
     $currentDate: {
        lastModified: true,
        "cancellation.date": { $type: "timestamp" }
     },
     $set: {
        status: "D",
        "cancellation.reason": "user request"
     }
   }
)

The updated document would resemble:

{
   "_id" : 1,
   "status" : "D",
   "lastModified" : ISODate("2014-09-17T23:25:56.314Z"),
   "cancellation" : {
      "date" : Timestamp(1410996356, 1),
      "reason" : "user request"
   }
}

See also

db.collection.update(), db.collection.findAndModify()

Array Update Operators

Update Operators

Name | Description
$ | Acts as a placeholder to update the first element that matches the query condition in an update.
$addToSet | Adds elements to an array only if they do not already exist in the set.
$pop | Removes the first or last item of an array.
$pullAll | Removes all matching values from an array.
$pull | Removes all array elements that match a specified query.
$pushAll | Deprecated. Adds several items to an array.
$push | Adds an item to an array.

$ (update)

$addToSet

$pop

$pullAll

$pull

$pushAll

$push

Update Operator Modifiers

Name | Description
$each | Modifies the $push and $addToSet operators to append multiple items for array updates.
$slice | Modifies the $push operator to limit the size of updated arrays.
$sort | Modifies the $push operator to reorder documents stored in an array.
$position | Modifies the $push operator to specify the position in the array to add elements.

$each

$slice

$sort

$position

$ (update)

Definition

$

The positional $ operator identifies an element in an array to update without explicitly specifying the position of the element in the array. To project, or return, an array element from a read operation, see the $ projection operator.

The positional $ operator has the form:

{ "<array>.$" : value }

When used with update operations, e.g. db.collection.update() and db.collection.findAndModify(),

the positional $ operator acts as a placeholder for the first element that matches the query document, and

the array field must appear as part of the query document.

For example:

db.collection.update(
   { <array>: value ... },
   { <update operator>: { "<array>.$" : value } }
)

Behavior

upsert

Do not use the positional operator $ with upsert operations because inserts will use the $ as a field name in the inserted document.

Nested Arrays

The positional $ operator cannot be used for queries which traverse more than one array, such as queries that traverse arrays nested within other arrays, because the replacement for the $ placeholder is a single value

Unsets

When used with the $unset operator, the positional $ operator does not remove the matching element from the array but rather sets it to null.

Negations

If the query matches the array using a negation operator, such as $ne, $not, or $nin, then you cannot use the positional operator to update values from this array.

However, if the negated portion of the query is inside of an $elemMatch expression, then you can use the positional operator to update this field.

Examples

Update Values in an Array

Consider a collection students with the following documents:

{ "_id" : 1, "grades" : [ 80, 85, 90 ] }
{ "_id" : 2, "grades" : [ 88, 90, 92 ] }
{ "_id" : 3, "grades" : [ 85, 100, 90 ] }

To update 80 to 82 in the grades array in the first document, use the positional $ operator if you do not know the position of the element in the array:

db.students.update(
   { _id: 1, grades: 80 },
   { $set: { "grades.$" : 82 } }
)

Remember that the positional $ operator acts as a placeholder for the first match of the update query document.

Update Documents in an Array

The positional $ operator facilitates updates to arrays that contain embedded documents. Use the positional $ operator to access the fields in the embedded documents with the dot notation on the $ operator.

db.collection.update(
   { <query selector> },
   { <update operator>: { "array.$.field" : value } }
)

Consider the following document in the students collection whose grades element value is an array of embedded documents:

{
  _id: 4,
  grades: [
     { grade: 80, mean: 75, std: 8 },
     { grade: 85, mean: 90, std: 5 },
     { grade: 90, mean: 85, std: 3 }
  ]
}

Use the positional $ operator to update the value of the std field in the embedded document with the grade of 85:

db.students.update(
   { _id: 4, "grades.grade": 85 },
   { $set: { "grades.$.std" : 6 } }
)

Update Embedded Documents Using Multiple Field Matches

The $ operator can update the first array element that matches multiple query criteria specified with the $elemMatch() operator.

Consider the following document in the students collection whose grades field value is an array of embedded documents:

{
  _id: 4,
  grades: [
     { grade: 80, mean: 75, std: 8 },
     { grade: 85, mean: 90, std: 5 },
     { grade: 90, mean: 85, std: 3 }
  ]
}

In the example below, the $ operator updates the value of the std field in the first embedded document that has grade field with a value less than or equal to 90 and a mean field with a value greater than 80:

db.students.update(
   {
     _id: 4,
     grades: { $elemMatch: { grade: { $lte: 90 }, mean: { $gt: 80 } } }
   },
   { $set: { "grades.$.std" : 6 } }
)

This operation updates the first embedded document that matches the criteria, namely the second embedded document in the array:

{
  _id: 4,
  grades: [
    { grade: 80, mean: 75, std: 8 },
    { grade: 85, mean: 90, std: 6 },
    { grade: 90, mean: 85, std: 3 }
  ]
}

See also

db.collection.update(), db.collection.findAndModify(), $elemMatch()

$addToSet

Definition

$addToSet

The $addToSet operator adds a value to an array only if the value is not already in the array. If the value is in the array, $addToSet does not modify the array.

The $addToSet operator has the form:

{ $addToSet: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

$addToSet only ensures that there are no duplicate items added to the set and does not affect existing duplicate elements. $addToSet does not guarantee a particular ordering of elements in the modified set.

If the field is absent in the document to update, $addToSet creates the array field with the specified value as its element.

If the field is not an array, the operation will fail.

If the value is an array, $addToSet appends the whole array as a single element. To add each element of the value separately, use the $each modifier with $addToSet. See $each Modifier for details.

If the value is a document, MongoDB determines that the document is a duplicate if an existing document in the array matches the to-be-added document exactly; i.e. the existing document has the exact same fields and values and the fields are in the same order. As such, field order matters and you cannot specify that MongoDB compare only a subset of the fields in the document to determine whether the document is a duplicate of an existing array element.

Examples

Consider a collection inventory with the following document:

{ _id: 1, item: "filter", tags: [ "electronics", "camera" ] }

Add to Array

The following operation adds the element "accessories" to the tags array since "accessories" does not exist in the array:

db.inventory.update(
   { _id: 1 },
   { $addToSet: { tags: "accessories" } }
)

Value Already Exists

The following $addToSet operation has no effect as "camera" is already an element of the tags array:

db.inventory.update(
   { _id: 1 },
   { $addToSet: { tags: "camera"  } }
)

$each Modifier

You can use the $addToSet operator with the $each modifier. The $each modifier allows the $addToSet operator to add multiple values to the array field.

A collection inventory has the following document:

{ _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }

Then the following operation uses the $addToSet operator with the $each modifier to add multiple elements to the tags array:

db.inventory.update(
   { _id: 2 },
   { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
 )

The operation adds only "camera" and "accessories" to the tags array since "electronics" already exists in the array:

{
  _id: 2,
  item: "cable",
  tags: [ "electronics", "supplies", "camera", "accessories" ]
}

See also

db.collection.update(), db.collection.findAndModify(), $push

$pop

Definition

$pop

The $pop operator removes the first or last element of an array. Pass $pop a value of -1 to remove the first element of an array and 1 to remove the last element in an array.

The $pop operator has the form:

{ $pop: { <field>: <-1 | 1>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

The $pop operation fails if the <field> is not an array.

If the $pop operator removes the last item in the <field>, the <field> will then hold an empty array.

Examples

Remove the First Item of an Array

Given the following document in a collection students:

{ _id: 1, scores: [ 8, 9, 10 ] }

The following example removes the first element (8) in the scores array:

db.students.update( { _id: 1 }, { $pop: { scores: -1 } } )

After the operation, the updated document has the first item 8 removed from its scores array:

{ _id: 1, scores: [ 9, 10 ] }

Remove the Last Item of an Array

Given the following document in a collection students:

{ _id: 1, scores: [ 9, 10 ] }

The following example removes the last element (10) in the scores array by specifying 1 in the $pop expression:

db.students.update( { _id: 1 }, { $pop: { scores: 1 } } )

After the operation, the updated document has the last item 10 removed from its scores array:

{ _id: 1, scores: [ 9 ] }

See also

db.collection.update(), db.collection.findAndModify()

$pullAll

Definition

$pullAll

The $pullAll operator removes all instances of the specified values from an existing array. Unlike the $pull operator that removes elements by specifying a query, $pullAll removes elements that match the listed values.

The $pullAll operator has the form:

{ $pullAll: { <field1>: [ <value1>, <value2> ... ], ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If a <value> to remove is a document or an array, $pullAll removes only the elements in the array that match the specified <value> exactly, including order.

Examples

Given the following document in the survey collection:

{ _id: 1, scores: [ 0, 2, 5, 5, 1, 0 ] }

The following operation removes all instances of the value 0 and 5 from the scores array:

db.survey.update( { _id: 1 }, { $pullAll: { scores: [ 0, 5 ] } } )

After the operation, the updated document has all instances of 0 and 5 removed from the scores field:

{ "_id" : 1, "scores" : [ 2, 1 ] }

See also

db.collection.update(), db.collection.findAndModify()

$pull

$pull

The $pull operator removes from an existing array all instances of a value or values that match a specified query.

The $pull operator has the form:

{ $pull: { <field1>: <value|query>, ... } }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If you specify a <query> and the array elements are embedded documents, $pull operator applies the <query> as if each array element were a document in a collection. See Remove Items from an Array of Documents for an example.

If the specified <value> to remove is an array, $pull removes only the elements in the array that match the specified <value> exactly, including order.

If the specified <value> to remove is a document, $pull removes only the elements in the array that have the exact same fields and values. The ordering of the fields can differ.

Examples

Remove All Items That Equals a Specified Value

Given the following documents in the cpuinfo collection:

{ _id: 1, flags: [ "vme", "de", "msr", "tsc", "pse", "msr" ] }
{ _id: 2, flags: [ "msr", "pse", "tsc" ] }

The following operation removes the value "msr" from the flags array:

db.cpuinfo.update(
                   { flags: "msr" },
                   { $pull: { flags: "msr" } },
                   { multi: true }
                 )

After the operation, the documents no longer contain any "msr" values in the flags array:

{ _id: 1, flags: [  "vme",  "de",  "tsc",  "pse" ] }
{ _id: 2, flags: [  "pse",  "tsc" ] }

Remove All Items That Match a Specified $pull Condition

Given the following document in the profiles collection:

{ _id: 1, votes: [ 3, 5, 6, 7, 7, 8 ] }

The following operation will remove all items from the votes array that are greater than or equal to ($gte) 6:

db.profiles.update( { _id: 1 }, { $pull: { votes: { $gte: 6 } } } )

After the update operation, the document only has values less than 6:

{ _id: 1, votes: [  3,  5 ] }

Remove Items from an Array of Documents

A survey collection contains the following documents:

{
   _id: 1,
   results: [
      { item: "A", score: 5 },
      { item: "B", score: 8, comment: "Strongly agree" }
   ]
}
{
   _id: 2,
   results: [
      { item: "C", score: 8, comment: "Strongly agree" },
      { item: "B", score: 4 }
   ]
}

The following operation will remove from the results array all elements that contain a score field equal to 8 and item field equal to "B":

db.survey.update(
  { },
  { $pull: { results: { score: 8 , item: "B" } } },
  { multi: true }
)

The $pull expression applies the condition to each element of the results array as though it were a top-level document.

After the operation, the results array contains no documents that contains score field equal to 8 and item field equal to "B".

{
   "_id" : 1,
   "results" : [ { "item" : "A", "score" : 5 } ]
}
{
  "_id" : 2,
  "results" : [
      { "item" : "C", "score" : 8, "comment" : "Strongly agree" },
      { "item" : "B", "score" : 4 }
   ]
}

Because $pull operator applies its query to each element as though it were a top-level object, the expression did not require the use of $elemMatch to specify the condition of a score field equal to 8 and item field equal to "B". In fact, the following operation will not pull any element from the original collection.

db.survey.update(
  { },
  { $pull: { results: { $elemMatch: { score: 8 , item: "B" } } } },
  { multi: true }
)

However, if the survey collection contained the following documents, where the results array contains embedded documents that also contain arrays:

{
   _id: 1,
   results: [
      { item: "A", score: 5, answers: [ { q: 1, a: 4 }, { q: 2, a: 6 } ] },
      { item: "B", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 9 } ] }
   ]
}
{
   _id: 2,
   results: [
      { item: "C", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 7 } ] },
      { item: "B", score: 4, answers: [ { q: 1, a: 0 }, { q: 2, a: 8 } ] }
   ]
}

Then you can specify multiple conditions on the elements of the answers array with $elemMatch:

db.survey.update(
  { },
  { $pull: { results: { answers: { $elemMatch: { q: 2, a: { $gte: 8 } } } } } },
  { multi: true }
)

The operation removed from the results array those embedded documents with an answers field that contained at least one element with q equal to 2 and a greater than or equal to 8:

{
   "_id" : 1,
   "results" : [
      { "item" : "A", "score" : 5, "answers" : [ { "q" : 1, "a" : 4 }, { "q" : 2, "a" : 6 } ] }
   ]
}
{
   "_id" : 2,
   "results" : [
      { "item" : "C", "score" : 8, "answers" : [ { "q" : 1, "a" : 8 }, { "q" : 2, "a" : 7 } ] }
   ]
}

See also

db.collection.update(), db.collection.findAndModify()

$pushAll

$pushAll

Deprecated since version 2.4: Use the $push operator with $each instead.

The $pushAll operator appends the specified values to an array.

The $pushAll operator has the form:

{ $pushAll: { <field>: [ <value1>, <value2>, ... ] } }

If you specify a single value, $pushAll will behave as $push.

$push

Definition

$push

The $push operator appends a specified value to an array.

The $push operator has the form:

{ $push: { <field1>: <value1>, ... }

To specify a <field> in an embedded document or in an array, use dot notation.

Behavior

If the field is absent in the document to update, $push adds the array field with the value as its element.

If the field is not an array, the operation will fail.

If the value is an array, $push appends the whole array as a single element. To add each element of the value separately, use the $each modifier with $push. For an example, see Append Multiple Values to an Array. For a list of modifiers available for $push, see Modifiers.

Changed in version 2.4: MongoDB adds support for the $each modifier to the $push operator. Before 2.4, use $pushAll for similar functionality.

Modifiers

New in version 2.4.

You can use the $push operator with the following modifiers:

Modifier
Description

$each

Appends multiple values to the array field.

Changed in version 2.6: When used in conjunction with the other modifiers, the $each modifier no longer needs to be first.

$slice
Limits the number of array elements. Requires the use of the $each modifier.

$sort

Orders elements of the array. Requires the use of the $each modifier.

Changed in version 2.6: In previous versions, $sort is only available when used with both $each and $slice.

$position

Specifies the location in the array at which to insert the new elements. Requires the use of the $each modifier. Without the $position modifier, the $push appends the elements to the end of the array.

New in version 2.6.

When used with modifiers, the $push operator has the form:

{ $push: { <field1>: { <modifier1>: <value1>, ... }, ... } }

The processing of the push operation with modifiers occur in the following order, regardless of the order in which the modifiers appear:

Update array to add elements in the correct position.

Apply sort, if specified.

Slice the array, if specified.

Store the array.

Examples

Append a Value to an Array

The following example appends 89 to the scores array:

db.students.update(
   { _id: 1 },
   { $push: { scores: 89 } }
)

Append Multiple Values to an Array

Use $push with the $each modifier to append multiple values to the array field.

The following example appends each element of [ 90, 92, 85 ] to the scores array for the document where the name field equals joe:

db.students.update(
   { name: "joe" },
   { $push: { scores: { $each: [ 90, 92, 85 ] } } }
)

Use $push Operator with Multiple Modifiers

A collection students has the following document:

{
   "_id" : 5,
   "quizzes" : [
      { "wk": 1, "score" : 10 },
      { "wk": 2, "score" : 8 },
      { "wk": 3, "score" : 5 },
      { "wk": 4, "score" : 6 }
   ]
}

The following $push operation uses:

the $each modifier to add multiple documents to the quizzes array,

the $sort modifier to sort all the elements of the modified quizzes array by the score field in descending order, and

the $slice modifier to keep only the first three sorted elements of the quizzes array.

db.students.update(
   { _id: 5 },
   {
     $push: {
       quizzes: {
          $each: [ { wk: 5, score: 8 }, { wk: 6, score: 7 }, { wk: 7, score: 6 } ],
          $sort: { score: -1 },
          $slice: 3
       }
     }
   }
)

The result of the operation is keep only the three highest scoring quizzes:

{
  "_id" : 5,
  "quizzes" : [
     { "wk" : 1, "score" : 10 },
     { "wk" : 2, "score" : 8 },
     { "wk" : 5, "score" : 8 }
  ]
}

See also

db.collection.update(), db.collection.findAndModify()

$each

Definition

$each

The $each modifier is available for use with the $addToSet operator and the $push operator.

Use with the $addToSet operator to add multiple values to an array <field> if the values do not exist in the <field>.

{ $addToSet: { <field>: { $each: [ <value1>, <value2> ... ] } } }

Use with the $push operator to append multiple values to an array <field>.

{ $push: { <field>: { $each: [ <value1>, <value2> ... ] } } }

Changed in version 2.4: MongoDB adds support for the $each modifier to the $push operator. The $push operator can use $each modifier with other modifiers. For a list of modifiers available for $push, see Modifiers.

Examples

Use $each with $push Operator

The following example appends each element of [ 90, 92, 85 ] to the scores array for the document where the name field equals joe:

db.students.update(
   { name: "joe" },
   { $push: { scores: { $each: [ 90, 92, 85 ] } } }
)

Use $each with $addToSet Operator

A collection inventory has the following document:

{ _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }

Then the following operation uses the $addToSet operator with the $each modifier to add multiple elements to the tags array:

db.inventory.update(
   { _id: 2 },
   { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
 )

The operation adds only "camera" and "accessories" to the tags array since "electronics" already exists in the array:

{
  _id: 2,
  item: "cable",
  tags: [ "electronics", "supplies", "camera", "accessories" ]
}

$slice

$slice

New in version 2.4.

The $slice modifier limits the number of array elements during a $push operation. To project, or return, a specified number of array elements from a read operation, see the $slice projection operator instead.

To use the $slice modifier, it must appear with the $each modifier. You can pass an empty array [] to the $each modifier such that only the $slice modifier has an effect.

{
  $push: {
     <field>: {
       $each: [ <value1>, <value2>, ... ],
       $slice: <num>
     }
  }
}

The <num> can be:

Value
Description

Zero
To update the array <field> to an empty array.

Negative
To update the array <field> to contain only the last <num> elements.

Positive

To update the array <field> contain only the first <num> elements.

New in version 2.6.

Behavior

Changed in version 2.6.

The order in which the modifiers appear is immaterial. Previous versions required the $each modifier to appear as the first modifier if used in conjunction with $slice. For a list of modifiers available for $push, see Modifiers.

Trying to use the $slice modifier without the $each modifier results in an error.

Examples

Slice from the End of the Array

A collection students contains the following document:

{ "_id" : 1, "scores" : [ 40, 50, 60 ] }

The following operation adds new elements to the scores array, and then uses the $slice modifier to trim the array to the last five elements:

db.students.update(
   { _id: 1 },
   {
     $push: {
       scores: {
         $each: [ 80, 78, 86 ],
         $slice: -5
       }
     }
   }
)

The result of the operation is slice the elements of the updated scores array to the last five elements:

{ "_id" : 1, "scores" : [  50,  60,  80,  78,  86 ] }

Slice from the Front of the Array

A collection students contains the following document:

{ "_id" : 2, "scores" : [ 89, 90 ] }

The following operation adds new elements to the scores array, and then uses the $slice modifier to trim the array to the first three elements.

db.students.update(
   { _id: 2 },
   {
     $push: {
       scores: {
         $each: [ 100, 20 ],
         $slice: 3
       }
     }
   }
)

The result of the operation is to slice the elements of the updated scores array to the first three elements:

{ "_id" : 2, "scores" : [  89,  90,  100 ] }

Update Array Using Slice Only

A collection students contains the following document:

{ "_id" : 3, "scores" : [  89,  70,  100,  20 ] }

To update the scores field with just the effects of the $slice modifier, specify the number of elements to slice (e.g. -3) for the $slice modifier and an empty array [] for the $each modifier, as in the following:

db.students.update(
  { _id: 3 },
  {
    $push: {
      scores: {
         $each: [ ],
         $slice: -3
      }
    }
  }
)

The result of the operation is to slice the elements of the scores array to the last three elements:

{ "_id" : 3, "scores" : [  70,  100,  20 ] }

Use $slice with Other $push Modifiers

A collection students has the following document:

{
   "_id" : 5,
   "quizzes" : [
      { "wk": 1, "score" : 10 },
      { "wk": 2, "score" : 8 },
      { "wk": 3, "score" : 5 },
      { "wk": 4, "score" : 6 }
   ]
}

The following $push operation uses:

the $each modifier to add multiple documents to the quizzes array,

the $sort modifier to sort all the elements of the modified quizzes array by the score field in descending order, and

the $slice modifier to keep only the first three sorted elements of the quizzes array.

db.students.update(
   { _id: 5 },
   {
     $push: {
       quizzes: {
          $each: [ { wk: 5, score: 8 }, { wk: 6, score: 7 }, { wk: 7, score: 6 } ],
          $sort: { score: -1 },
          $slice: 3
       }
     }
   }
)

The result of the operation is keep only the three highest scoring quizzes:

{
  "_id" : 5,
  "quizzes" : [
     { "wk" : 1, "score" : 10 },
     { "wk" : 2, "score" : 8 },
     { "wk" : 5, "score" : 8 }
  ]
}

The order of the modifiers is immaterial to the order in which the modifiers are processed. See Modifiers for details.

$sort

$sort

New in version 2.4.

The $sort modifier orders the elements of an array during a $push operation.

To use the $sort modifier, it must appear with the $each modifier. You can pass an empty array [] to the $each modifier such that only the $sort modifier has an effect.

{
  $push: {
     <field>: {
       $each: [ <value1>, <value2>, ... ],
       $sort: <sort specification>
     }
  }
}

For <sort specification>:

To sort array elements that are not documents, or if the array elements are documents, to sort by the whole documents, specify 1 for ascending or -1 for descending.

If the array elements are documents, to sort by a field in the documents, specify a sort document with the field and the direction, i.e. { field: 1 } or { field: -1 }. Do not reference the containing array field in the sort specification (e.g. { "arrayField.field": 1 } is incorrect).

Behavior

Changed in version 2.6.

The $sort modifier can sort array elements that are not documents. In previous versions, the $sort modifier required the array elements be documents.

If the array elements are documents, the modifier can sort by either the whole document or by a specific field in the documents. In previous versions, the $sort modifier can only sort by a specific field in the documents.

Trying to use the $sort modifier without the $each modifier results in an error. The $sort no longer requires the $slice modifier. For a list of modifiers available for $push, see Modifiers.

Examples

Sort Array of Documents by a Field in the Documents

A collection students contains the following document:

{
  "_id": 1,
  "quizzes": [
    { "id" : 1, "score" : 6 },
    { "id" : 2, "score" : 9 }
  ]
}

The following update appends additional documents to the quizzes array and then sorts all the elements of the array by the ascending score field:

db.students.update(
   { _id: 1 },
   {
     $push: {
       quizzes: {
         $each: [ { id: 3, score: 8 }, { id: 4, score: 7 }, { id: 5, score: 6 } ],
         $sort: { score: 1 }
       }
     }
   }
)

Important

The sort document refers directly to the field in the documents and does not reference the containing array field quizzes; i.e. { score: 1 } and not { "quizzes.score": 1}

After the update, the array elements are in order of ascending score field.:

{
  "_id" : 1,
  "quizzes" : [
     { "id" : 1, "score" : 6 },
     { "id" : 5, "score" : 6 },
     { "id" : 4, "score" : 7 },
     { "id" : 3, "score" : 8 },
     { "id" : 2, "score" : 9 }
  ]
}

Sort Array Elements That Are Not Documents

A collection students contains the following document:

{ "_id" : 2, "tests" : [  89,  70,  89,  50 ] }

The following operation adds two more elements to the scores array and sorts the elements:

db.students.update(
   { _id: 2 },
   { $push: { tests: { $each: [ 40, 60 ], $sort: 1 } } }
)

The updated document has the elements of the scores array in ascending order:

{ "_id" : 2, "tests" : [  40,  50,  60,  70,  89,  89 ] }

Update Array Using Sort Only

A collection students contains the following document:

{ "_id" : 3, "tests" : [  89,  70,  100,  20 ] }

To update the tests field to sort its elements in descending order, specify the { $sort: -1 } and specify an empty array [] for the $each modifier, as in the following:

db.students.update(
   { _id: 3 },
   { $push: { tests: { $each: [ ], $sort: -1 } } }
)

The result of the operation is to update the scores field to sort its elements in descending order:

{ "_id" : 3, "tests" : [ 100,  89,  70,  20 ] }

Use $sort with Other $push Modifiers

A collection students has the following document:

{
   "_id" : 5,
   "quizzes" : [
      { "wk": 1, "score" : 10 },
      { "wk": 2, "score" : 8 },
      { "wk": 3, "score" : 5 },
      { "wk": 4, "score" : 6 }
   ]
}

The following $push operation uses:

the $each modifier to add multiple documents to the quizzes array,

the $sort modifier to sort all the elements of the modified quizzes array by the score field in descending order, and

the $slice modifier to keep only the first three sorted elements of the quizzes array.

db.students.update(
   { _id: 5 },
   {
     $push: {
       quizzes: {
          $each: [ { wk: 5, score: 8 }, { wk: 6, score: 7 }, { wk: 7, score: 6 } ],
          $sort: { score: -1 },
          $slice: 3
       }
     }
   }
)

The result of the operation is keep only the three highest scoring quizzes:

{
  "_id" : 5,
  "quizzes" : [
     { "wk" : 1, "score" : 10 },
     { "wk" : 2, "score" : 8 },
     { "wk" : 5, "score" : 8 }
  ]
}

The order of the modifiers is immaterial to the order in which the modifiers are processed. See Modifiers for details.

$position

Definition

$position

New in version 2.6.

The $position modifier specifies the location in the array at which the $push operator insert elements. Without the $position modifier, the $push operator inserts elements to the end of the array. See $push modifiers for more information.

To use the $position modifier, it must appear with the $each modifier.

{
  $push: {
    <field>: {
       $each: [ <value1>, <value2>, ... ],
       $position: <num>
    }
  }
}

The <num> is a non-negative number that corresponds to the position in the array, based on a zero-based index.

If the <num> is greater or equal to the length of the array, the $position modifier has no effect and $push adds elements to the end of the array.

Examples

Add Elements at the Start of the Array

Consider a collection students that contains the following document:

{ "_id" : 1, "scores" : [ 100 ] }

The following operation updates the scores field to add the elements 50, 60 and 70 to the beginning of the array:

db.students.update(
   { _id: 1 },
   {
     $push: {
        scores: {
           $each: [ 50, 60, 70 ],
           $position: 0
        }
     }
   }
)

The operation results in the following updated document:

{ "_id" : 1, "scores" : [  50,  60,  70,  100 ] }

Add Elements to the Middle of the Array

Consider a collection students that contains the following document:

{ "_id" : 1, "scores" : [  50,  60,  70,  100 ] }

The following operation updates the scores field to add the elements 20 and 30 at the array index of 2:

db.students.update(
   { _id: 1 },
   {
     $push: {
        scores: {
           $each: [ 20, 30 ],
           $position: 2
        }
     }
   }
)

The operation results in the following updated document:

{ "_id" : 1, "scores" : [  50,  60,  20,  30,  70,  100 ] }

Bitwise Update Operator

Name | Description
$bit | Performs bitwise AND, OR, and XOR updates of integer values.

$bit

$bit

Definition

$bit

Changed in version 2.6: Added support for bitwise xor operation.

The $bit operator performs a bitwise update of a field. The operator supports bitwise and, bitwise or, and bitwise xor (i.e. exclusive or) operations. To specify a $bit operator expression, use the following prototype:

{ $bit: { <field>: { <and|or|xor>: <int> } } }

Only use this operator with integer fields (either 32-bit integer or 64-bit integer).

To specify a <field> in an embedded document or in an array, use dot notation.

Note

All numbers in the mongo shell are doubles, not integers. Use the NumberInt() or the NumberLong() constructor to specify integers. See NumberInt or NumberLong for more information.

Examples

Bitwise AND

Consider the following document inserted into the collection switches:

{ _id: 1, expdata: NumberInt(13) }

The following update() operation updates the expdata field to the result of a bitwise and operation between the current value NumberInt(13) (i.e. 1101) and NumberInt(10) (i.e. 1010):

db.switches.update(
   { _id: 1 },
   { $bit: { expdata: { and: NumberInt(10) } } }
)

The bitwise and operation results in the integer 8 (i.e. 1000):

1101
1010
----
1000

And the updated document has the following value for expdata:

{ "_id" : 1, "expdata" : 8 }

The mongo shell displays NumberInt(8) as 8.

Bitwise OR

Consider the following document inserted into the collection switches:

{ _id: 2, expdata: NumberLong(3) }

The following update() operation updates the expdata field to the result of a bitwise or operation between the current value NumberLong(3) (i.e. 0011) and NumberInt(5) (i.e. 0101):

db.switches.update(
   { _id: 2 },
   { $bit: { expdata: { or: NumberInt(5) } } }
)

The bitwise or operation results in the integer 7 (i.e. 0111):

0011
0101
----
0111

And the updated document has the following value for expdata:

{ "_id" : 2, "expdata" : NumberLong(7) }

Bitwise XOR

Consider the following document in the collection switches:

{ _id: 3, expdata: NumberLong(1) }

The following update() operation updates the expdata field to the result of a bitwise xor operation between the current value NumberLong(1) (i.e. 0001) and NumberInt(5) (i.e. 0101):

db.switches.update(
   { _id: 3 },
   { $bit: { expdata: { xor: NumberInt(5) } } }
)

The bitwise xor operation results in the integer 4:

0001
0101
----
0100

And the updated document has the following value for expdata:

{ "_id" : 3, "expdata" : NumberLong(4) }

See also

db.collection.update(), db.collection.findAndModify()

Isolation Update Operator

Name | Description
$isolated | Modifies the behavior of a write operation to increase the isolation of the operation.

$isolated

$isolated

Definition

$isolated

Prevents a write operation that affects multiple documents from yielding to other reads or writes once the first document is written. By using the $isolated option, you can ensure that no client sees the changes until the operation completes or errors out.

This behavior can significantly affect the concurrency of the system as the operation holds the write lock much longer than normal.

Behavior

The $isolated isolation operator does not provide “all-or-nothing” atomicity for write operations.

$isolated does not work with sharded clusters.

Example

Consider the following example:

db.foo.update(
    { status : "A" , $isolated : 1 },
    { $inc : { count : 1 } },
    { multi: true }
)

Without the $isolated operator, the multi-update operation will allow other operations to interleave with its update of the matched documents.

See also

db.collection.update() and db.collection.remove()

$atomic

Deprecated since version 2.2: The $isolated operator replaces $atomic.

Aggregation Pipeline Operators

Stage Operators

Pipeline stages appear in an array. Documents pass through the stages in sequence.

db.collection.aggregate( [ { <stage> }, ... ] )

Name
Description

$project
Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document.

$match
Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).

$redact
Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero document.

$limit
Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).

$skip
Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).

$unwind
Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array.

$group
Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields.

$sort
Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.

$geoNear
Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field.

$out
Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline.

Pipeline Aggregation Stages

$project (aggregation)

$match (aggregation)

$redact (aggregation)

$limit (aggregation)

$skip (aggregation)

$unwind (aggregation)

$group (aggregation)

$sort (aggregation)

$geoNear (aggregation)

$out (aggregation)

Expression Operators

These expression operators are available to construct expressions for use in the aggregation pipeline.

Operator expressions are similar to functions that take arguments. In general, these expressions take an array of arguments and have the following form:

{ <operator>: [ <argument1>, <argument2> ... ] }

If operator accepts a single argument, you can omit the outer array designating the argument list:

{ <operator>: <argument> }

To avoid parsing ambiguity if the argument is a literal array, you must wrap the literal array in a $literal expression or keep the outer array that designates the argument list.

Boolean Operators

Boolean expressions evaluate their argument expressions as booleans and return a boolean as the result.

In addition to the false boolean value, Boolean expression evaluates as false the following: null, 0, and undefined values. The Boolean expression evaluates all other values as true, including non-zero numeric values and arrays.

Boolean Aggregation Operators

$and (aggregation)

$or (aggregation)

$not (aggregation)

Set Operators

Set expressions performs set operation on arrays, treating arrays as sets. Set expressions ignores the duplicate entries in each input array and the order of the elements.

If the set operation returns a set, the operation filters out duplicates in the result to output an array that contains only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, the set expression does not descend into the nested array but evaluates the array at top-level.

Set Operators (Aggregation)

$setEquals (aggregation)

$setIntersection (aggregation)

$setUnion (aggregation)

$setDifference (aggregation)

$setIsSubset (aggregation)

$anyElementTrue (aggregation)

$allElementsTrue (aggregation)

Comparison Operators

Comparison expressions return a boolean except for $cmp which returns a number.

The comparison expressions take two argument expressions and compare both value and type, using the specified BSON comparison order for values of different types.

Comparison Aggregation Operators

$cmp (aggregation)

$eq (aggregation)

$gt (aggregation)

$gte (aggregation)

$lt (aggregation)

$lte (aggregation)

$ne (aggregation)

Arithmetic Operators

Arithmetic expressions perform mathematic operations on numbers. Some arithmetic expressions can also support date arithmetic.

Arithmetic Aggregation Operators

$add (aggregation)

$subtract (aggregation)

$multiply (aggregation)

$divide (aggregation)

$mod (aggregation)

String Operators

String expressions, with the exception of $concat, only have a well-defined behavior for strings of ASCII characters.

$concat behavior is well-defined regardless of the characters used.

String Aggregation Operators

$concat (aggregation)

$substr (aggregation)

$toLower (aggregation)

$toUpper (aggregation)

$strcasecmp (aggregation)

Text Search Operators

Text Search Aggregation Operators

$meta (aggregation)

Array Operators

Array Aggregation Operators

$size (aggregation)

Variable Operators

Aggregation Variable Operators

$map (aggregation)

$let (aggregation)

Literal Operators

Aggregation Literal Operators

$literal (aggregation)

Date Operators

Date Aggregation Operators

$dayOfYear (aggregation)

$dayOfMonth (aggregation)

$dayOfWeek (aggregation)

$year (aggregation)

$month (aggregation)

$week (aggregation)

$hour (aggregation)

$minute (aggregation)

$second (aggregation)

$millisecond (aggregation)

Conditional Expressions

Conditional Aggregation Operators

$cond (aggregation)

$ifNull (aggregation)

Accumulators

Accumulators, available only for the $group stage, compute values by combining documents that share the same group key. Accumulators take as input a single expression, evaluating the expression once for each input document, and maintain their state for the group of documents.

Group Accumulator Operators

$sum (aggregation)

$avg (aggregation)

$first (aggregation)

$last (aggregation)

$max (aggregation)

$min (aggregation)

$push (aggregation)

$addToSet (aggregation)

Pipeline Aggregation Stages

Name
Description

$project
Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document.

$match
Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).

$redact
Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero document.

$limit
Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).

$skip
Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).

$unwind
Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array.

$group
Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields.

$sort
Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.

$geoNear
Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field.

$out
Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline.

$project (aggregation)

$match (aggregation)

$redact (aggregation)

$limit (aggregation)

$skip (aggregation)

$unwind (aggregation)

$group (aggregation)

$sort (aggregation)

$geoNear (aggregation)

$out (aggregation)

$project (aggregation)

Definition

$project

Passes along the documents with only the specified fields to the next stage in the pipeline. The specified fields can be existing fields from the input documents or newly computed fields.

The $project stage has the following prototype form:

{ $project: { <specifications> } }

The $project takes a document that can specify the inclusion of fields, the suppression of the _id field, the addition of new fields, and the resetting the values of existing fields. The specifications have the following forms:

Syntax | Description
<field>: <1 or true> | Specify the inclusion of a field.
_id: <0 or false> | Specify the suppression of the _id field.
<field>: <expression> | Add a new field or reset the value of an existing field.

Considerations

Include Existing Fields

The _id field is, by default, included in the output documents. To include the other fields from the input documents in the output documents, you must explicitly specify the inclusion in $project.

If you specify an inclusion of a field that does not exist in the document, $project ignores that field inclusion; i.e. $project does not add the field to the document.

Suppress the _id Field

The _id field is always included in the output documents by default. To exclude the _id field from the output documents, you must explicitly specify the suppression of the _id field in $project.

Add New Fields or Reset Existing Fields

To add a new field or to reset the value of an existing field, specify the field name and set its value to some expression. For more information on expressions, see Expressions.

To set a field value directly to a numeric or boolean literal, as opposed to setting the field to an expression that resolves to a literal, use the $literal operator. Otherwise, $project treats the numeric or boolean literal as a flag for including or excluding the field.

By specifying a new field and setting its value to the field path of an existing field, you can effectively rename a field.

Embedded Document Fields

When projecting or adding/resetting a field within an embedded document, you can either use dot notation, as in

"contact.address.country": <1 or 0 or expression>

Or you can nest the fields:

contact: { address: { country: <1 or 0 or expression> } }

When nesting the fields, you cannot use dot notation inside the embedded document to specify the field, e.g. contact: { "address.country": <1 or 0 or expression> } is invalid.

Examples

Include Specific Fields in Output Documents

Consider a books collection with the following document:

{
  "_id" : 1,
  title: "abc123",
  isbn: "0001122223334",
  author: { last: "zzz", first: "aaa" },
  copies: 5
}

The following $project stage includes only the _id, title, and the author fields in its output documents:

db.books.aggregate( [ { $project : { title : 1 , author : 1 } } ] )

The operation results in the following document:

{ "_id" : 1, "title" : "abc123", "author" : { "last" : "zzz", "first" : "aaa" } }

Suppress _id Field in the Output Documents

The _id field is always included by default. To exclude the _id field from the output documents of the $project stage, specify the exclusion of the _id field by setting it to 0 in the projection document.

Consider a books collection with the following document:

{
  "_id" : 1,
  title: "abc123",
  isbn: "0001122223334",
  author: { last: "zzz", first: "aaa" },
  copies: 5
}

The following $project stage excludes the _id field but includes the title, and the author fields in its output documents:

db.books.aggregate( [ { $project : { _id: 0, title : 1 , author : 1 } } ] )

The operation results in the following document:

{ "title" : "abc123", "author" : { "last" : "zzz", "first" : "aaa" } }

Include Specific Fields from Embedded Documents

Consider a bookmarks collection with the following documents:

{ _id: 1, user: "1234", stop: { title: "book1", author: "xyz", page: 32 } }
{ _id: 2, user: "7890", stop: [ { title: "book2", author: "abc", page: 5 }, { title: "b", author: "ijk", page: 100 } ] }

To include only the title field in the embedded document in the stop field, you can use the dot notation:

db.bookmarks.aggregate( [ { $project: { "stop.title": 1 } } ] )

Or, you can nest the inclusion specification in a document:

db.bookmarks.aggregate( [ { $project: { stop: { title: 1 } } } ] )

Both specifications result in the following documents:

{ "_id" : 1, "stop" : { "title" : "book1" } }
{ "_id" : 2, "stop" : [ { "title" : "book2" }, { "title" : "book3" } ] }

Include Computed Fields

Consider a books collection with the following document:

{
  "_id" : 1,
  title: "abc123",
  isbn: "0001122223334",
  author: { last: "zzz", first: "aaa" },
  copies: 5
}

The following $project stage adds the new fields isbn, lastName, and copiesSold:

db.books.aggregate(
   [
      {
         $project: {
            title: 1,
            isbn: {
               prefix: { $substr: [ "$isbn", 0, 3 ] },
               group: { $substr: [ "$isbn", 3, 2 ] },
               publisher: { $substr: [ "$isbn", 5, 4 ] },
               title: { $substr: [ "$isbn", 9, 3 ] },
               checkDigit: { $substr: [ "$isbn", 12, 1] }
            },
            lastName: "$author.last",
            copiesSold: "$copies"
         }
      }
   ]
)

The operation results in the following document:

{
   "_id" : 1,
   "title" : "abc123",
   "isbn" : {
      "prefix" : "000",
      "group" : "11",
      "publisher" : "2222",
      "title" : "333",
      "checkDigit" : "4"
   },
   "lastName" : "zzz",
   "copiesSold" : 5
}

$match (aggregation)

Definition

$match

Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline stage.

The $match stage has the following prototype form:

{ $match: { <query> } }

$match takes a document that specifies the query conditions. The query syntax is identical to the read operation query syntax.

Behavior

Pipeline Optimization

Place the $match as early in the aggregation pipeline as possible. Because $match limits the total number of documents in the aggregation pipeline, earlier $match operations minimize the amount of processing down the pipe.

If you place a $match at the very beginning of a pipeline, the query can take advantage of indexes like any other db.collection.find() or db.collection.findOne().

Restrictions

You cannot use $where in $match queries as part of the aggregation pipeline.

To use $text in the $match stage, the $match stage has to be the first stage of the pipeline.

Examples

Equality Match

The following operation uses $match to perform a simple equality match:

db.articles.aggregate(
    [ { $match : { author : "dave" } } ]
);

The $match selects the documents where the author field equals dave, and the aggregation returns the following:

{
  "result" : [
               {
                 "_id" : ObjectId("512bc95fe835e68f199c8686"),
                 "author": "dave",
                 "score" : 80
               },
               { "_id" : ObjectId("512bc962e835e68f199c8687"),
                 "author" : "dave",
                 "score" : 85
               }
             ],
  "ok" : 1
}

Perform a Count

The following example selects documents to process using the $match pipeline operator and then pipes the results to the $group pipeline operator to compute a count of the documents:

db.articles.aggregate( [
                        { $match : { score : { $gt : 70, $lte : 90 } } },
                        { $group: { _id: null, count: { $sum: 1 } } }
                       ] );

In the aggregation pipeline, $match selects the documents where the score is greater than 70 and less than or equal to 90. These documents are then piped to the $group to perform a count. The aggregation returns the following:

{
  "result" : [
               {
                 "_id" : null,
                 "count" : 3
               }
             ],
  "ok" : 1
}

$redact (aggregation)

Definition

$redact

New in version 2.6.

Restricts the contents of the documents based on information stored in the documents themselves.

The $redact stage has the following prototype form:

{ $redact: <expression> }

The argument can be any valid expression as long as it resolves to $$DESCEND, $$PRUNE, or $$KEEP system variables. For more information on expressions, see Expressions.

System Variable | Description
$$DESCEND | $redact returns the fields at the current document level, excluding embedded documents. To include embedded documents and embedded documents within arrays, apply the $cond expression to the embedded documents to determine access for these embedded documents.
$$PRUNE | $redact excludes all fields at this current document/embedded document level, without further inspection of any of the excluded fields. This applies even if the excluded field contains embedded documents that may have different access levels.
$$KEEP | $redact returns or keeps all fields at this current document/embedded document level, without further inspection of the fields at this level. This applies even if the included field contains embedded documents that may have different access levels.

Examples

The examples in this section use the db.collection.aggregate() helper provided in the 2.6 version of the mongo shell.

Evaluate Access at Every Document Level

A forecasts collection contains documents of the following form where the tags field lists the different access values for that document/embedded document level; i.e. a value of [ "G", "STLW" ] specifies either "G" or "STLW" can access the data:

{
   _id: 1,
   title: "123 Department Report",
   tags: [ "G", "STLW" ],
   year: 2014,
   subsections: [
       {
           subtitle: "Section 1: Overview",
           tags: [ "SI", "G" ],
           content:  "Section 1: This is the content of section 1."
       },
       {
           subtitle: "Section 2: Analysis",
           tags: [ "STLW" ],
           content: "Section 2: This is the content of section 2."
       },
       {
           subtitle: "Section 3: Budgeting",
           tags: [ "TK" ],
           content: {
               text: "Section 3: This is the content of section3.",
               tags: [ "HCS" ]
           }
       }
   ]
}

A user has access to view information with either the tag "STLW" or "G". To run a query on all documents with year 2014 for this user, include a $redact stage as in the following:

var userAccess = [ "STLW", "G" ];
db.forecasts.aggregate(
   [
     { $match: { year: 2014 } },
     { $redact:
         {
            $cond:
               {
                 if: { $gt: [ { $size: { $setIntersection: [ "$tags", userAccess ] } }, 0 ] },
                 then: "$$DESCEND",
                 else: "$$PRUNE"
               }
         }
     }
   ]
)

The aggregation operation returns the following “redacted” document:

{
   "_id" : 1,
   "title" : "123 Department Report",
   "tags" : [ "G", "STLW" ],
   "year" : 2014,
   "subsections" : [
      {
         "subtitle" : "Section 1: Overview",
         "tags" : [ "SI", "G" ],
         "content" : "Section 1: This is the content of section 1."
      },
      {
         "subtitle" : "Section 2: Analysis",
         "tags" : [ "STLW" ],
         "content" : "Section 2: This is the content of section 2."
      }
   ]
}

See also

$size, $setIntersection

Exclude All Fields at a Given Level

A collection accounts contains the following document:

{
  _id: 1,
  level: 1,
  acct_id: "xyz123",
  cc: {
        level: 5,
        type: "yy",
        num: 000000000000,
        exp_date: ISODate("2015-11-01T00:00:00.000Z"),
        billing_addr: {
                        level: 5,
                        addr1: "123 ABC Street",
                        city: "Some City"
                      },
        shipping_addr: [
                          {
                            level: 3,
                            addr1: "987 XYZ Ave",
                            city: "Some City"
                          },
                          {
                            level: 3,
                            addr1: "PO Box 0123",
                            city: "Some City"
                          }
                       ]
      },
  status: "A"
}

In this example document, the level field determines the access level required to view the data.

To run a query on all documents with status A and exclude all fields contained in a document/embedded document at level 5, include a $redact stage that specifies the system variable "$$PRUNE" in the then field:

db.accounts.aggregate(
   [
     { $match: { status: "A" } },
     { $redact:
        {
            $cond: {
                     if: { $eq: [ "$level", 5 ] },
                     then: "$$PRUNE",
                     else: "$$DESCEND"
                   }
        }
     }
   ]
)

The $redact stage evaluates the level field to determine access. If the level field equals 5, then exclude all fields at that level, even if the excluded field contains embedded documents that may have different level values, such as the shipping_addr field.

The aggregation operation returns the following “redacted” document:

{
  "_id" : 1,
  "level" : 1,
  "acct_id" : "xyz123",
  "status" : "A"
}

The result set shows that the $redact stage excluded the field cc as a whole, including the shipping_addr field which contained embedded documents that had level field values equal to 3 and not 5.

See also

Implement Field Level Redaction for steps to set up multiple combinations of access for the same data.

$limit (aggregation)

Definition

$limit

Limits the number of documents passed to the next stage in the pipeline.

The $limit stage has the following prototype form:

{ $limit: <positive integer> }

$limit takes a positive integer that specifies the maximum number of documents to pass along.

Example

Consider the following example:

db.article.aggregate(
    { $limit : 5 }
);

This operation returns only the first 5 documents passed to it from by the pipeline. $limit has no effect on the content of the documents it passes.

Note

When a $sort immediately precedes a $limit in the pipeline, the $sort operation only maintains the top n results as it progresses, where n is the specified limit, and MongoDB only needs to store n items in memory. This optimization still applies when allowDiskUse is true and the n items exceed the aggregation memory limit.

Changed in version 2.4: Before MongoDB 2.4, $sort would sort all the results in memory, and then limit the results to n results.

$skip (aggregation)

Definition

$skip

Skips over the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline.

The $skip stage has the following prototype form:

{ $skip: <positive integer> }

$skip takes a positive integer that specifies the maximum number of documents to skip.

Example

Consider the following example:

db.article.aggregate(
    { $skip : 5 }
);

This operation skips the first 5 documents passed to it by the pipeline. $skip has no effect on the content of the documents it passes along the pipeline.

$unwind (aggregation)

Definition

$unwind

Deconstructs an array field from the input documents to output a document for each element. Each output document is the input document with the value of the array field replaced by the element.

The $unwind stage has the following prototype form:

{ $unwind: <field path> }

To specify a field path, prefix the field name with a dollar sign $ and enclose in quotes.

Behaviors

$unwind has the following behaviors:

If a value in the field specified by the field path is not an array, db.collection.aggregate() generates an error.

If you specify a path for a field that does not exist in an input document, the pipeline ignores the input document and will not output documents for that input document.

If the array holds an empty array ([]) in an input document, the pipeline ignores the input document and will not output documents for that input document.

Examples

Consider an inventory with the following document:

{ "_id" : 1, "item" : "ABC1", sizes: [ "S", "M", "L"] }

The following aggregation uses the $unwind stage to output a document for each element in the sizes array:

db.inventory.aggregate( [ { $unwind : "$sizes" } ] )

The operation returns the following results:

{ "_id" : 1, "item" : "ABC1", "sizes" : "S" }
{ "_id" : 1, "item" : "ABC1", "sizes" : "M" }
{ "_id" : 1, "item" : "ABC1", "sizes" : "L" }

Each document is identical to the input document except for the value of the sizes field which now holds a value from the original sizes array.

$group (aggregation)

Definition

$group

Groups documents by some specified expression and outputs to the next stage a document for each distinct grouping. The output documents contain an _id field which contains the distinct group by key. The output documents can also contain computed fields that hold the values of some accumulator expression grouped by the $group‘s _id field. $group does not order its output documents.

The $group stage has the following prototype form:

{ $group: { _id: <expression>, <field1>: { <accumulator1> : <expression1> }, ... } }

The _id field is mandatory; however, you can specify an _id value of null to calculate accumulated values for all the input documents as a whole.

The remaining computed fields are optional and computed using the <accumulator> operators.

The _id and the <accumulator> expressions can accept any valid expression. For more information on expressions, see Expressions.

Considerations

Accumulator Operator

The <accumulator> operator must be one of the following accumulator operators:

Name | Description
$sum | Returns a sum for each group. Ignores non-numeric values.
$avg | Returns an average for each group. Ignores non-numeric values.
$first | Returns a value from the first document for each group. Order is only defined if the documents are in a defined order.
$last | Returns a value from the last document for each group. Order is only defined if the documents are in a defined order.
$max | Returns the highest expression value for each group.
$min | Returns the lowest expression value for each group.
$push | Returns an array of expression values for each group.
$addToSet | Returns an array of unique expression values for each group. Order of the array elements is undefined.

$group Operator and Memory

The $group stage has a limit of 100 megabytes of RAM. By default, if the stage exceeds this limit, $group will produce an error. However, to allow for the handling of large datasets, set the allowDiskUse option to true to enable $group operations to write to temporary files. See db.collection.aggregate() method and the aggregate command for details.

Changed in version 2.6: MongoDB introduces a limit of 100 megabytes of RAM for the $group stage as well as the allowDiskUse option to handle operations for large datasets.

Examples

Calculate Count, Sum, and Average

Given a collection sales with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-03-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-03-01T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-03-15T09:00:00Z") }
{ "_id" : 4, "item" : "xyz", "price" : 5, "quantity" : 20, "date" : ISODate("2014-04-04T11:21:39.736Z") }
{ "_id" : 5, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-04-04T21:23:13.331Z") }

Group by Month, Day, and Year

The following aggregation operation uses the $group stage to group the documents by the month, day, and year and calculates the total price and the average quantity as well as counts the documents per each group:

db.sales.aggregate(
   [
      {
        $group : {
           _id : { month: { $month: "$date" }, day: { $dayOfMonth: "$date" }, year: { $year: "$date" } },
           totalPrice: { $sum: { $multiply: [ "$price", "$quantity" ] } },
           averageQuantity: { $avg: "$quantity" },
           count: { $sum: 1 }
        }
      }
   ]
)

The operation returns the following results:

{ "_id" : { "month" : 3, "day" : 15, "year" : 2014 }, "totalPrice" : 50, "averageQuantity" : 10, "count" : 1 }
{ "_id" : { "month" : 4, "day" : 4, "year" : 2014 }, "totalPrice" : 200, "averageQuantity" : 15, "count" : 2 }
{ "_id" : { "month" : 3, "day" : 1, "year" : 2014 }, "totalPrice" : 40, "averageQuantity" : 1.5, "count" : 2 }

Group by null

The following aggregation operation specifies a group _id of null, calculating the total price and the average quantity as well as counts for all documents in the collection:

db.sales.aggregate(
   [
      {
        $group : {
           _id : null,
           totalPrice: { $sum: { $multiply: [ "$price", "$quantity" ] } },
           averageQuantity: { $avg: "$quantity" },
           count: { $sum: 1 }
        }
      }
   ]
)

The operation returns the following result:

{ "_id" : null, "totalPrice" : 290, "averageQuantity" : 8.6, "count" : 5 }

Retrieve Distinct Values

Given a collection sales with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-03-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-03-01T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-03-15T09:00:00Z") }
{ "_id" : 4, "item" : "xyz", "price" : 5, "quantity" : 20, "date" : ISODate("2014-04-04T11:21:39.736Z") }
{ "_id" : 5, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-04-04T21:23:13.331Z") }

The following aggregation operation uses the $group stage to group the documents by the item to retrieve the distinct item values:

db.sales.aggregate( [ { $group : { _id : "$item" } } ] )

The operation returns the following result:

{ "_id" : "xyz" }
{ "_id" : "jkl" }
{ "_id" : "abc" }

Pivot Data

A collection books contains the following documents:

{ "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 }
{ "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 }
{ "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
{ "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 }
{ "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }

Group title by author

The following aggregation operation pivots the data in the books collection to have titles grouped by authors.

db.books.aggregate(
   [
     { $group : { _id : "$author", books: { $push: "$title" } } }
   ]
)

The operation returns the following documents:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

Group Documents by author

The following aggregation operation uses the $$ROOT system variable to group the documents by authors. The resulting documents must not exceed the BSON Document Size limit.

db.books.aggregate(
   [
     { $group : { _id : "$author", books: { $push: "$$ROOT" } } }
   ]
)

The operation returns the following documents:

{
  "_id" : "Homer",
  "books" :
     [
       { "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 },
       { "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }
     ]
}

{
  "_id" : "Dante",
  "books" :
     [
       { "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 },
       { "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 },
       { "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
     ]
}

See also

The Aggregation with the Zip Code Data Set tutorial provides an extensive example of the $group operator in a common use case.

$sort (aggregation)

Definition

$sort

Sorts all input documents and returns them to the pipeline in sorted order.

The $sort stage has the following prototype form:

{ $sort: { <field1>: <sort order>, <field2>: <sort order> ... } }

$sort takes a document that specifies the field(s) to sort by and the respective sort order. <sort order> can have one of the following values:

1 to specify ascending order.

-1 to specify descending order.

{ $meta: "textScore" } to sort by the computed textScore metadata in descending order. See Metadata Sort for an example.

Examples

Ascending/Descending Sort

To ascending order for a field or fields to sort by and a value of 1 or -1 to specify an ascending or descending sort respectively, as in the following example:

db.users.aggregate(
   [
     { $sort : { age : -1, posts: 1 } }
   ]
)

This operation sorts the documents in the users collection, in descending order according by the age field and then in ascending order according to the value in the posts field.

When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:

MinKey (internal type)

Null

Numbers (ints, longs, doubles)

Symbol, String

Object

Array

BinData

ObjectId

Boolean

Date, Timestamp

Regular Expression

MaxKey (internal type)

MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.

The comparison treats a non-existent field as it would an empty BSON Object. As such, a sort on the a field in documents { } and { a: null } would treat the documents as equivalent in sort order.

With arrays, a less-than comparison or an ascending sort compares the smallest element of arrays, and a greater-than comparison or a descending sort compares the largest element of the arrays. As such, when comparing a field whose value is a single-element array (e.g. [ 1 ]) with non-array fields (e.g. 2), the comparison is between 1 and 2. A comparison of an empty array (e.g. [ ]) treats the empty array as less than null or a missing field.

MongoDB sorts BinData in the following order:

First, the length or size of the data.

Then, by the BSON one-byte subtype.

Finally, by the data, performing a byte-by-byte comparison.

Metadata Sort

Specify in the { <sort-key> } document, a new field name for the computed metadata and specify the $meta expression as its value, as in the following example:

db.users.aggregate(
   [
     { $match: { $text: { $search: "operating" } } },
     { $sort: { score: { $meta: "textScore" }, posts: -1 } }
   ]
)

This operation uses the $text operator to match the documents, and then sorts first by the "textScore" metadata and then by descending order of the posts field. The specified metadata determines the sort order. For example, the "textScore" metadata sorts in descending order. See $meta for more information on metadata.

$sort Operator and Memory

$sort + $limit Memory Optimization

When a $sort immediately precedes a $limit in the pipeline, the $sort operation only maintains the top n results as it progresses, where n is the specified limit, and MongoDB only needs to store n items in memory. This optimization still applies when allowDiskUse is true and the n items exceed the aggregation memory limit.

Changed in version 2.4: Before MongoDB 2.4, $sort would sort all the results in memory, and then limit the results to n results.

Optimizations are subject to change between releases.

$sort and Memory Restrictions

The $sort stage has a limit of 100 megabytes of RAM. By default, if the stage exceeds this limit, $sort will produce an error. To allow for the handling of large datasets, set the allowDiskUse option to true to enable $sort operations to write to temporary files. See the allowDiskUse option in db.collection.aggregate() method and the aggregate command for details.

Changed in version 2.6: The memory limit for $sort changed from 10 percent of RAM to 100 megabytes of RAM.

$sort Operator and Performance

$sort operator can take advantage of an index when placed at the beginning of the pipeline or placed before the $project, $unwind, and $group aggregation operators. If $project, $unwind, or $group occur prior to the $sort operation, $sort cannot use any indexes.

$geoNear (aggregation)

Definition

$geoNear

New in version 2.4.

Outputs documents in order of nearest to farthest from a specified point.

The $geoNear stage has the following prototype form:

{ $geoNear: { <geoNear options> } }

The $geoNear operator accepts a document that contains the following $geoNear options. Specify all distances in the same units as those of the processed documents’ coordinate system:

Field
Description

spherical

Required if using a 2dsphere index. Determines how MongoDB calculates the distance. The default value is false.

If true, then MongoDB uses spherical geometry to calculate distances in meters if the specified (near) point is a GeoJSON point and in radians if the specified (near) point is a legacy coordinate pair.

If false, then MongoDB uses 2d planar geometry to calculate distance between points.

If using a 2dsphere index, spherical must be true.

limit
Optional. The maximum number of documents to return. The default value is 100. See also the num option.

num
Optional. The num option provides the same function as the limit option. Both define the maximum number of documents to return. If both options are included, the num value overrides the limit value.

maxDistance

Optional. The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

query

Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax.

You cannot specify a $near predicate in the query field of the $geoNear stage.

distanceMultiplier
Optional. The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.

uniqueDocs

Optional. If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query.

Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.

near

distanceField
The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation.

includeLocs
Optional. This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.

field Boolean spherical:

Required if using a 2dsphere index. Determines how MongoDB calculates the distance. The default value is false.

If true, then MongoDB uses spherical geometry to calculate distances in meters if the specified (near) point is a GeoJSON point and in radians if the specified (near) point is a legacy coordinate pair.

If false, then MongoDB uses 2d planar geometry to calculate distance between points.

If using a 2dsphere index, spherical must be true.

field number limit:

Optional. The maximum number of documents to return. The default value is 100. See also the num option.

field number num:

Optional. The num option provides the same function as the limit option. Both define the maximum number of documents to return. If both options are included, the num value overrides the limit value.

field number maxDistance:

Optional. The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

field document query:

Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax.

You cannot specify a $near predicate in the query field of the $geoNear stage.

field number distanceMultiplier:

Optional. The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.

field Boolean uniqueDocs:

Optional. If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query.

Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.

field near:

field string distanceField:

The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation.

field string includeLocs:

Optional. This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.

Behavior

When using $geoNear, consider that:

You can only use $geoNear as the first stage of a pipeline.

You must include the distanceField option. The distanceField option specifies the field that will contain the calculated distance.

The collection must have a geospatial index.

The $geoNear requires that a collection have at most only one 2d index and/or only one 2dsphere index.

You do not need to specify which field in the documents hold the coordinate pair or point. Because $geoNear requires that the collection have a single geospatial index, $geoNear implicitly uses the indexed field.

If using a 2dsphere index, you must specify spherical: true.

You cannot specify a $near predicate in the query field of the $geoNear stage.

Generally, the options for $geoNear are similar to the geoNear command with the following exceptions:

distanceField is a mandatory field for the $geoNear pipeline operator; the option does not exist in the geoNear command.

includeLocs accepts a string in the $geoNear pipeline operator and a boolean in the geoNear command.

Example

Consider a collection places that has a 2dsphere index. The following aggregation finds at most 5 unique documents with a location at most 2 units from the center [ -73.99279 , 40.719296 ] and have type equal to public:

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "dist.calculated",
        maxDistance: 2,
        query: { type: "public" },
        includeLocs: "dist.location",
        num: 5,
        spherical: true
     }
   }
])

The aggregation returns the following:

{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "type" : "public",
   "location" : {
      "type" : "Point",
      "coordinates" : [ -73.9928, 40.7193 ]
   },
   "dist" : {
      "calculated" : 0.9539931676365992,
      "location" : {
         "type" : "Point",
         "coordinates" : [ -73.9928, 40.7193 ]
      }
   }
}

The matching document contains two new fields:

dist.calculated field that contains the calculated distance, and

dist.location field that contains the location used in the calculation.

$out (aggregation)

New in version 2.6.

Definition

$out

Takes the documents returned by the aggregation pipeline and writes them to a specified collection. The $out operator must be the last stage in the pipeline. The $out operator lets the aggregation framework return result sets of any size.

The $out stage has the following prototype form:

{ $out: "<output-collection>" }

$out takes a string that specifies the output collection name.

Important

You cannot specify a sharded collection as the output collection. The input collection for a pipeline can be sharded.

The $out operator cannot write results to a capped collection.

Behaviors

Create New Collection

The $out operation creates a new collection in the current database if one does not already exist. The collection is not visible until the aggregation completes. If the aggregation fails, MongoDB does not create the collection.

Replace Existing Collection

If the collection specified by the $out operation already exists, then upon completion of the aggregation, the $out stage atomically replaces the existing collection with the new results collection. The $out operation does not change any indexes that existed on the previous collection. If the aggregation fails, the $out operation makes no changes to the pre-existing collection.

Index Constraints

The pipeline will fail to complete if the documents produced by the pipeline would violate any unique indexes, including the index on the _id field of the original output collection.

Example

A collection books contains the following documents:

{ "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 }
{ "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 }
{ "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
{ "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 }
{ "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }

The following aggregation operation pivots the data in the books collection to have titles grouped by authors and then writes the results to the authors collection.

db.books.aggregate( [
                      { $group : { _id : "$author", books: { $push: "$title" } } },
                      { $out : "authors" }
                  ] )

After the operation, the authors collection contains the following documents:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

Boolean Aggregation Operators

Boolean expressions evaluate their argument expressions as booleans and return a boolean as the result.

In addition to the false boolean value, Boolean expression evaluates as false the following: null, 0, and undefined values. The Boolean expression evaluates all other values as true, including non-zero numeric values and arrays.

Name | Description
$and | Returns true only when all its expressions evaluate to true. Accepts any number of argument expressions.
$or | Returns true when any of its expressions evaluates to true. Accepts any number of argument expressions.
$not | Returns the boolean value that is the opposite of its argument expression. Accepts a single argument expression.

$and (aggregation)

$or (aggregation)

$not (aggregation)

$and (aggregation)

Definition

$and

Evaluates one or more expressions and returns true if all of the expressions are true or if evoked with no argument expressions. Otherwise, $and returns false.

$and has the following syntax:

{ $and: [ <expression1>, <expression2>, ... ] }

For more information on expressions, see Expressions.

Behavior

$and uses short-circuit logic: the operation stops evaluation after encountering the first false expression.

In addition to the false boolean value, $and evaluates as false the following: null, 0, and undefined values. The $and evaluates all other values as true, including non-zero numeric values and arrays.

Example |  | Result
{ $and: [ 1, "green" ] } |  | true
{ $and: [ ] } |  | true
{ $and: [ [ null ], [ false ], [ 0 ] ] } |  | true
{ $and: [ null, true ] } |  | false
{ $and: [ 0, true ] } |  | false

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $and operator to determine if qty is greater than 100 and less than 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            result: { $and: [ { $gt: [ "$qty", 100 ] }, { $lt: [ "$qty", 250 ] } ] }
          }
     }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "result" : false }
{ "_id" : 2, "item" : "abc2", "result" : true }
{ "_id" : 3, "item" : "xyz1", "result" : false }
{ "_id" : 4, "item" : "VWZ1", "result" : false }
{ "_id" : 5, "item" : "VWZ2", "result" : true }

$or (aggregation)

Definition

$or

Evaluates one or more expressions and returns true if any of the expressions are true. Otherwise, $or returns false.

$or has the following syntax:

{ $or: [ <expression1>, <expression2>, ... ] }

For more information on expressions, see Expressions.

Behavior

$or uses short-circuit logic: the operation stops evaluation after encountering the first true expression.

In addition to the false boolean value, $or evaluates as false the following: null, 0, and undefined values. The $or evaluates all other values as true, including non-zero numeric values and arrays.

Example |  | Result
{ $or: [ true, false ] } |  | true
{ $or: [ [ false ], false ] } |  | true
{ $or: [ null, 0, undefined ] } |  | false
{ $or: [ ] } |  | false

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $or operator to determine if qty is greater than 250 or less than 200:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            result: { $or: [ { $gt: [ "$qty", 250 ] }, { $lt: [ "$qty", 200 ] } ] }
          }
     }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "result" : true }
{ "_id" : 2, "item" : "abc2", "result" : false }
{ "_id" : 3, "item" : "xyz1", "result" : false }
{ "_id" : 4, "item" : "VWZ1", "result" : true }
{ "_id" : 5, "item" : "VWZ2", "result" : true }

$not (aggregation)

Definition

$not

Evaluates a boolean and returns the opposite boolean value; i.e. when passed an expression that evaluates to true, $not returns false; when passed an expression that evaluates to false, $not returns true.

$not has the following syntax:

{ $not: [ <expression> ] }

For more information on expressions, see Expressions.

Behavior

In addition to the false boolean value, $not evaluates as false the following: null, 0, and undefined values. The $not evaluates all other values as true, including non-zero numeric values and arrays.

Example |  | Result
{ $not: [ true ] } |  | false
{ $not: [ [ false ] ] } |  | false
{ $not: [ false ] } |  | true
{ $not: [ null ] } |  | true
{ $not: [ 0 ] } |  | true

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $or operator to determine if qty is greater than 250 or less than 200:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            result: { $not: [ { $gt: [ "$qty", 250 ] } ] }
          }
     }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "result" : false }
{ "_id" : 2, "item" : "abc2", "result" : true }
{ "_id" : 3, "item" : "xyz1", "result" : true }
{ "_id" : 4, "item" : "VWZ1", "result" : false }
{ "_id" : 5, "item" : "VWZ2", "result" : true }

Set Operators (Aggregation)

Set expressions performs set operation on arrays, treating arrays as sets. Set expressions ignores the duplicate entries in each input array and the order of the elements.

If the set operation returns a set, the operation filters out duplicates in the result to output an array that contains only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, the set expression does not descend into the nested array but evaluates the array at top-level.

Name | Description
$setEquals | Returns true if the input sets have the same distinct elements. Accepts two or more argument expressions.
$setIntersection | Returns a set with elements that appear in all of the input sets. Accepts any number of argument expressions.
$setUnion | Returns a set with elements that appear in any of the input sets. Accepts any number of argument expressions.
$setDifference | Returns a set with elements that appear in the first set but not in the second set; i.e. performs a relative complement [http://en.wikipedia.org/wiki/Complement_(set_theory)] of the second set relative to the first. Accepts exactly two argument expressions.
$setIsSubset | Returns true if all elements of the first set appear in the second set, including when the first set equals the second set; i.e. not a strict subset [http://en.wikipedia.org/wiki/Subset]. Accepts exactly two argument expressions.
$anyElementTrue | Returns true if any elements of a set evaluate to true; otherwise, returns false. Accepts a single argument expression.
$allElementsTrue | Returns true if no element of a set evaluates to false, otherwise, returns false. Accepts a single argument expression.

$setEquals (aggregation)

$setIntersection (aggregation)

$setUnion (aggregation)

$setDifference (aggregation)

$setIsSubset (aggregation)

$anyElementTrue (aggregation)

$allElementsTrue (aggregation)

$setEquals (aggregation)

Definition

$setEquals

New in version 2.6.

Compares two or more arrays and returns true if they have the same distinct elements and false otherwise.

$setEquals has the following syntax:

{ $setEquals: [ <expression1>, <expression2>, ... ] }

The arguments can be any valid expression as long as they each resolve to an array. For more information on expressions, see Expressions.

Behavior

$setEquals performs set operation on arrays, treating arrays as sets. If an array contains duplicate entries, $setEquals ignores the duplicate entries. $setEquals ignores the order of the elements.

If a set contains a nested array element, $setEquals does not descend into the nested array but evaluates the array at top-level.

Example |  | Result
{ $setEquals: [ [ "a", "b", "a" ], [ "b", "a" ] ] } |  | true
{ $setEquals: [ [ "a", "b" ], [ [ "a", "b" ] ] ] } |  | false

Example

Consider an experiments collection with the following documents:

{ "_id" : 1, "A" : [ "red", "blue" ], "B" : [ "red", "blue" ] }
{ "_id" : 2, "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ] }
{ "_id" : 3, "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ] }
{ "_id" : 4, "A" : [ "red", "blue" ], "B" : [ "green", "red" ] }
{ "_id" : 5, "A" : [ "red", "blue" ], "B" : [ ] }
{ "_id" : 6, "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ] }
{ "_id" : 7, "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ] }
{ "_id" : 8, "A" : [ ], "B" : [ ] }
{ "_id" : 9, "A" : [ ], "B" : [ "red" ] }

The following operation uses the $setEquals operator to determine if the A array and the B array contain the same elements:

db.experiments.aggregate(
   [
     { $project: { A: 1, B: 1, sameElements: { $setEquals: [ "$A", "$B" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "A" : [ "red", "blue" ], "B" : [ "red", "blue" ], "sameElements" : true }
{ "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ], "sameElements" : true }
{ "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ], "sameElements" : false }
{ "A" : [ "red", "blue" ], "B" : [ "green", "red" ], "sameElements" : false }
{ "A" : [ "red", "blue" ], "B" : [ ], "sameElements" : false }
{ "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ], "sameElements" : false }
{ "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ], "sameElements" : false }
{ "A" : [ ], "B" : [ ], "sameElements" : true }
{ "A" : [ ], "B" : [ "red" ], "sameElements" : false }

$setIntersection (aggregation)

Definition

$setIntersection

New in version 2.6.

Takes two or more arrays and returns an array that contains the elements that appear in every input array.

$setIntersection has the following syntax:

{ $setIntersection: [ <array1>, <array2>, ... ] }

The arguments can be any valid expression as long as they each resolve to an array. For more information on expressions, see Expressions.

Behavior

$setIntersection performs set operation on arrays, treating arrays as sets. If an array contains duplicate entries, $setIntersection ignores the duplicate entries. $setIntersection ignores the order of the elements.

$setIntersection filters out duplicates in its result to output an array that contain only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, $setIntersection does not descend into the nested array but evaluates the array at top-level.

Example |  | Result
{ $setIntersection: [ [ "a", "b", "a" ], [ "b", "a" ] ] } |  | [ "b", "a" ]
{ $setIntersection: [ [ "a", "b" ], [ [ "a", "b" ] ] ] } |  | [ ]

Example

Consider an experiments collection with the following documents:

{ "_id" : 1, "A" : [ "red", "blue" ], "B" : [ "red", "blue" ] }
{ "_id" : 2, "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ] }
{ "_id" : 3, "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ] }
{ "_id" : 4, "A" : [ "red", "blue" ], "B" : [ "green", "red" ] }
{ "_id" : 5, "A" : [ "red", "blue" ], "B" : [ ] }
{ "_id" : 6, "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ] }
{ "_id" : 7, "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ] }
{ "_id" : 8, "A" : [ ], "B" : [ ] }
{ "_id" : 9, "A" : [ ], "B" : [ "red" ] }

The following operation uses the $setIntersection operator to return an array of elements common to both the A array and the B array:

db.experiments.aggregate(
   [
     { $project: { A: 1, B: 1, commonToBoth: { $setIntersection: [ "$A", "$B" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "A" : [ "red", "blue" ], "B" : [ "red", "blue" ], "commonToBoth" : [ "blue", "red" ] }
{ "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ], "commonToBoth" : [ "blue", "red" ] }
{ "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ], "commonToBoth" : [ "blue", "red" ] }
{ "A" : [ "red", "blue" ], "B" : [ "green", "red" ], "commonToBoth" : [ "red" ] }
{ "A" : [ "red", "blue" ], "B" : [ ], "commonToBoth" : [ ] }
{ "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ], "commonToBoth" : [ ] }
{ "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ], "commonToBoth" : [ ] }
{ "A" : [ ], "B" : [ ], "commonToBoth" : [ ] }
{ "A" : [ ], "B" : [ "red" ], "commonToBoth" : [ ] }

$setUnion (aggregation)

Definition

$setUnion

New in version 2.6.

Takes two or more arrays and returns an array containing the elements that appear in any input array.

$setUnion has the following syntax:

{ $setUnion: [ <expression1>, <expression2>, ... ] }

The arguments can be any valid expression as long as they each resolve to an array. For more information on expressions, see Expressions.

Behavior

$setUnion performs set operation on arrays, treating arrays as sets. If an array contains duplicate entries, $setUnion ignores the duplicate entries. $setUnion ignores the order of the elements.

$setUnion filters out duplicates in its result to output an array that contain only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, $setUnion does not descend into the nested array but evaluates the array at top-level.

Example |  | Result
{ $setUnion: [ [ "a", "b", "a" ], [ "b", "a" ] ] } |  | [ "b", "a" ]
{ $setUnion: [ [ "a", "b" ], [ [ "a", "b" ] ] ] } |  | [ [ "a", "b" ], "b", "a" ]

Example

Consider an experiments collection with the following documents:

{ "_id" : 1, "A" : [ "red", "blue" ], "B" : [ "red", "blue" ] }
{ "_id" : 2, "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ] }
{ "_id" : 3, "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ] }
{ "_id" : 4, "A" : [ "red", "blue" ], "B" : [ "green", "red" ] }
{ "_id" : 5, "A" : [ "red", "blue" ], "B" : [ ] }
{ "_id" : 6, "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ] }
{ "_id" : 7, "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ] }
{ "_id" : 8, "A" : [ ], "B" : [ ] }
{ "_id" : 9, "A" : [ ], "B" : [ "red" ] }

The following operation uses the $setUnion operator to return an array of elements found in the A array or the B array or both:

db.experiments.aggregate(
   [
     { $project: { A:1, B: 1, allValues: { $setUnion: [ "$A", "$B" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "A": [ "red", "blue" ], "B": [ "red", "blue" ], "allValues": [ "blue", "red" ] }
{ "A": [ "red", "blue" ], "B": [ "blue", "red", "blue" ], "allValues": [ "blue", "red" ] }
{ "A": [ "red", "blue" ], "B": [ "red", "blue", "green" ], "allValues": [ "blue", "red", "green" ] }
{ "A": [ "red", "blue" ], "B": [ "green", "red" ], "allValues": [ "blue", "red", "green" ] }
{ "A": [ "red", "blue" ], "B": [ ], "allValues": [ "blue", "red" ] }
{ "A": [ "red", "blue" ], "B": [ [ "red" ], [ "blue" ] ], "allValues": [ "blue", "red", [ "red" ], [ "blue" ] ] }
{ "A": [ "red", "blue" ], "B": [ [ "red", "blue" ] ], "allValues": [ "blue", "red", [ "red", "blue" ] ] }
{ "A": [ ], "B": [ ], "allValues": [ ] }
{ "A": [ ], "B": [ "red" ], "allValues": [ "red" ] }

$setDifference (aggregation)

Definition

$setDifference

New in version 2.6.

Takes two sets and returns an array containing the elements that only exist in the first set; i.e. performs a relative complement [http://en.wikipedia.org/wiki/Complement_(set_theory)] of the second set relative to the first.

$setDifference has the following syntax:

{ $setDifference: [ <expression1>, <expression2> ] }

The arguments can be any valid expression as long as they each resolve to an array. For more information on expressions, see Expressions.

Behavior

$setDifference performs set operation on arrays, treating arrays as sets. If an array contains duplicate entries, $setDifference ignores the duplicate entries. $setDifference ignores the order of the elements.

$setDifference filters out duplicates in its result to output an array that contain only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, $setDifference does not descend into the nested array but evaluates the array at top-level.

Example |  | Result
{ $setDifference: [ [ "a", "b", "a" ], [ "b", "a" ] ] } |  | [ ]
{ $setDifference: [ [ "a", "b" ], [ [ "a", "b" ] ] ] } |  | [ "a", "b" ]

Example

Consider an experiments collection with the following documents:

{ "_id" : 1, "A" : [ "red", "blue" ], "B" : [ "red", "blue" ] }
{ "_id" : 2, "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ] }
{ "_id" : 3, "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ] }
{ "_id" : 4, "A" : [ "red", "blue" ], "B" : [ "green", "red" ] }
{ "_id" : 5, "A" : [ "red", "blue" ], "B" : [ ] }
{ "_id" : 6, "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ] }
{ "_id" : 7, "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ] }
{ "_id" : 8, "A" : [ ], "B" : [ ] }
{ "_id" : 9, "A" : [ ], "B" : [ "red" ] }

The following operation uses the $setDifference operator to return an array of elements found in the B array but not in the A array:

db.experiments.aggregate(
   [
     { $project: { A: 1, B: 1, inBOnly: { $setDifference: [ "$B", "$A" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "A" : [ "red", "blue" ], "B" : [ "red", "blue" ], "inBOnly" : [ ] }
{ "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ], "inBOnly" : [ ] }
{ "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ], "inBOnly" : [ "green" ] }
{ "A" : [ "red", "blue" ], "B" : [ "green", "red" ], "inBOnly" : [ "green" ] }
{ "A" : [ "red", "blue" ], "B" : [ ], "inBOnly" : [ ] }
{ "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ], "inBOnly" : [ [ "red" ], [ "blue" ] ] }
{ "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ], "inBOnly" : [ [ "red", "blue" ] ] }
{ "A" : [ ], "B" : [ ], "inBOnly" : [ ] }
{ "A" : [ ], "B" : [ "red" ], "inBOnly" : [ "red" ] }

$setIsSubset (aggregation)

Definition

$setIsSubset

New in version 2.6.

Takes two arrays and returns true when the first array is a subset of the second, including when the first array equals the second array, and false otherwise.

$setIsSubset has the following syntax:

{ $setIsSubset: [ <expression1>, <expression2> ] }

The arguments can be any valid expression as long as they each resolve to an array. For more information on expressions, see Expressions.

Behavior

$setIsSubset performs set operation on arrays, treating arrays as sets. If an array contains duplicate entries, $setIsSubset ignores the duplicate entries. $setIsSubset ignores the order of the elements.

If a set contains a nested array element, $setIsSubset does not descend into the nested array but evaluates the array at top-level.

Example |  | Result
{ $setIsSubset: [ [ "a", "b", "a" ], [ "b", "a" ] ] } |  | true
{ $setIsSubset: [ [ "a", "b" ], [ [ "a", "b" ] ] ] } |  | false

Example

Consider an experiments collection with the following documents:

{ "_id" : 1, "A" : [ "red", "blue" ], "B" : [ "red", "blue" ] }
{ "_id" : 2, "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ] }
{ "_id" : 3, "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ] }
{ "_id" : 4, "A" : [ "red", "blue" ], "B" : [ "green", "red" ] }
{ "_id" : 5, "A" : [ "red", "blue" ], "B" : [ ] }
{ "_id" : 6, "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ] }
{ "_id" : 7, "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ] }
{ "_id" : 8, "A" : [ ], "B" : [ ] }
{ "_id" : 9, "A" : [ ], "B" : [ "red" ] }

The following operation uses the $setIsSubset operator to determine if the A array is a subset of the B array:

db.experiments.aggregate(
   [
     { $project: { A:1, B: 1, AisSubset: { $setIsSubset: [ "$A", "$B" ] }, _id:0 } }
   ]
)

The operation returns the following results:

{ "A" : [ "red", "blue" ], "B" : [ "red", "blue" ], "AisSubset" : true }
{ "A" : [ "red", "blue" ], "B" : [ "blue", "red", "blue" ], "AisSubset" : true }
{ "A" : [ "red", "blue" ], "B" : [ "red", "blue", "green" ], "AisSubset" : true }
{ "A" : [ "red", "blue" ], "B" : [ "green", "red" ], "AisSubset" : false }
{ "A" : [ "red", "blue" ], "B" : [ ], "AisSubset" : false }
{ "A" : [ "red", "blue" ], "B" : [ [ "red" ], [ "blue" ] ], "AisSubset" : false }
{ "A" : [ "red", "blue" ], "B" : [ [ "red", "blue" ] ], "AisSubset" : false }
{ "A" : [ ], "B" : [ ], "AisSubset" : true }
{ "A" : [ ], "B" : [ "red" ], "AisSubset" : true }

$anyElementTrue (aggregation)

Definition

$anyElementTrue

New in version 2.6.

Evaluates an array as a set and returns true if any of the elements are true and false otherwise. An empty array returns false.

$anyElementTrue has the following syntax:

{ $anyElementTrue: [ <expression> ] }

The <expression> itself must resolve to an array, separate from the outer array that denotes the argument list. For more information on expressions, see Expressions.

Behavior

If a set contains a nested array element, $anyElementTrue does not descend into the nested array but evaluates the array at top-level.

In addition to the false boolean value, $anyElementTrue evaluates as false the following: null, 0, and undefined values. The $anyElementTrue evaluates all other values as true, including non-zero numeric values and arrays.

Example |  | Result
{ $anyElementTrue: [ [ true, false ] ] } |  | true
{ $anyElementTrue: [ [ [ false ] ] ] } |  | true
{ $anyElementTrue: [ [ null, false, 0 ] ] } |  | false
{ $anyElementTrue: [ [ ] ] } |  | false

Example

Consider an survey collection with the following documents:

{ "_id" : 1, "responses" : [ true ] }
{ "_id" : 2, "responses" : [ true, false ] }
{ "_id" : 3, "responses" : [ ] }
{ "_id" : 4, "responses" : [ 1, true, "seven" ] }
{ "_id" : 5, "responses" : [ 0 ] }
{ "_id" : 6, "responses" : [ [ ] ] }
{ "_id" : 7, "responses" : [ [ 0 ] ] }
{ "_id" : 8, "responses" : [ [ false ] ] }
{ "_id" : 9, "responses" : [ null ] }
{ "_id" : 10, "responses" : [ undefined ] }

The following operation uses the $anyElementTrue operator to determine if the responses array contains any value that evaluates to true:

db.survey.aggregate(
   [
     { $project: { responses: 1, isAnyTrue: { $anyElementTrue: [ "$responses" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "responses" : [ true ], "isAnyTrue" : true }
{ "responses" : [ true, false ], "isAnyTrue" : true }
{ "responses" : [ ], "isAnyTrue" : false }
{ "responses" : [ 1, true, "seven" ], "isAnyTrue" : true }
{ "responses" : [ 0 ], "isAnyTrue" : false }
{ "responses" : [ [ ] ], "isAnyTrue" : true }
{ "responses" : [ [ 0 ] ], "isAnyTrue" : true }
{ "responses" : [ [ false ] ], "isAnyTrue" : true }
{ "responses" : [ null ], "isAnyTrue" : false }
{ "responses" : [ null ], "isAnyTrue" : false }

$allElementsTrue (aggregation)

Definition

$allElementsTrue

New in version 2.6.

Evaluates an array as a set and returns true if no element in the array is false. Otherwise, returns false. An empty array returns true.

$allElementsTrue has the following syntax:

{ $allElementsTrue: [ <expression> ] }

The <expression> itself must resolve to an array, separate from the outer array that denotes the argument list. For more information on expressions, see Expressions.

Behavior

If a set contains a nested array element, $allElementsTrue does not descend into the nested array but evaluates the array at top-level.

In addition to the false boolean value, $allElementsTrue evaluates as false the following: null, 0, and undefined values. The $allElementsTrue evaluates all other values as true, including non-zero numeric values and arrays.

Example |  | Result
{ $allElementsTrue: [ [ true, 1, "someString" ] ] } |  | true
{ $allElementsTrue: [ [ [ false ] ] ] } |  | true
{ $allElementsTrue: [ [ ] ] } |  | true
{ $allElementsTrue: [ [ null, false, 0 ] ] } |  | false

Example

Consider an survey collection with the following documents:

{ "_id" : 1, "responses" : [ true ] }
{ "_id" : 2, "responses" : [ true, false ] }
{ "_id" : 3, "responses" : [ ] }
{ "_id" : 4, "responses" : [ 1, true, "seven" ] }
{ "_id" : 5, "responses" : [ 0 ] }
{ "_id" : 6, "responses" : [ [ ] ] }
{ "_id" : 7, "responses" : [ [ 0 ] ] }
{ "_id" : 8, "responses" : [ [ false ] ] }
{ "_id" : 9, "responses" : [ null ] }
{ "_id" : 10, "responses" : [ undefined ] }

The following operation uses the $allElementsTrue operator to determine if the responses array only contains values that evaluate to true:

db.survey.aggregate(
   [
     { $project: { responses: 1, isAllTrue: { $allElementsTrue: [ "$responses" ] }, _id: 0 } }
   ]
)

The operation returns the following results:

{ "responses" : [ true ], "isAllTrue" : true }
{ "responses" : [ true, false ], "isAllTrue" : false }
{ "responses" : [ ], "isAllTrue" : true }
{ "responses" : [ 1, true, "seven" ], "isAllTrue" : true }
{ "responses" : [ 0 ], "isAllTrue" : false }
{ "responses" : [ [ ] ], "isAllTrue" : true }
{ "responses" : [ [ 0 ] ], "isAllTrue" : true }
{ "responses" : [ [ false ] ], "isAllTrue" : true }
{ "responses" : [ null ], "isAllTrue" : false }
{ "responses" : [ null ], "isAllTrue" : false }

Comparison Aggregation Operators

Comparison expressions return a boolean except for $cmp which returns a number.

The comparison expressions take two argument expressions and compare both value and type, using the specified BSON comparison order for values of different types.

Name | Description
$cmp | Returns: 0 if the two values are equivalent, 1 if the first value is greater than the second, and -1 if the first value is less than the second.
$eq | Returns true if the values are equivalent.
$gt | Returns true if the first value is greater than the second.
$gte | Returns true if the first value is greater than or equal to the second.
$lt | Returns true if the first value is less than the second.
$lte | Returns true if the first value is less than or equal to the second.
$ne | Returns true if the values are not equivalent.

$cmp (aggregation)

$eq (aggregation)

$gt (aggregation)

$gte (aggregation)

$lt (aggregation)

$lte (aggregation)

$ne (aggregation)

$cmp (aggregation)

Definition

$cmp

Compares two values and returns:

-1 if the first value is less than the second.

1 if the first value is greater than the second.

0 if the two values are equivalent.

The $cmp compares both value and type, using the specified BSON comparison order for values of different types.

$cmp has the following syntax:

{ $cmp: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $cmp operator to compare the qty value with 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            cmpTo250: { $cmp: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "cmpTo250" : 1 }
{ "item" : "abc2", "qty" : 200, "cmpTo250" : -1 }
{ "item" : "xyz1", "qty" : 250, "cmpTo250" : 0 }
{ "item" : "VWZ1", "qty" : 300, "cmpTo250" : 1 }
{ "item" : "VWZ2", "qty" : 180, "cmpTo250" : -1 }

$eq (aggregation)

Definition

$eq

Compares two values and returns:

true when the values are equivalent.

false when the values are not equivalent.

The $eq compares both value and type, using the specified BSON comparison order for values of different types.

$eq has the following syntax:

{ $eq: [ <expression1>, <expression2> ] }

The arguments can be any valid expression. For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $eq operator to determine if qty equals 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyEq250: { $eq: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyEq250" : false }
{ "item" : "abc2", "qty" : 200, "qtyEq250" : false }
{ "item" : "xyz1", "qty" : 250, "qtyEq250" : true }
{ "item" : "VWZ1", "qty" : 300, "qtyEq250" : false }
{ "item" : "VWZ2", "qty" : 180, "qtyEq250" : false }

$gt (aggregation)

Definition

$gt

Compares two values and returns:

true when the first value is greater than the second value.

false when the first value is less than or equivalent to the second value.

The $gt compares both value and type, using the specified BSON comparison order for values of different types.

$gt has the following syntax:

{ $gt: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $gt operator to determine if qty is greater than 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyGt250: { $gt: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyGt250" : true }
{ "item" : "abc2", "qty" : 200, "qtyGt250" : false }
{ "item" : "xyz1", "qty" : 250, "qtyGt250" : false }
{ "item" : "VWZ1", "qty" : 300, "qtyGt250" : true }
{ "item" : "VWZ2", "qty" : 180, "qtyGt250" : false }

$gte (aggregation)

Definition

$gte

Compares two values and returns:

true when the first value is greater than or equivalent to the second value.

false when the first value is less than the second value.

The $gte compares both value and type, using the specified BSON comparison order for values of different types.

$gte has the following syntax:

{ $gte: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $gte operator to determine if qty is greater than or equal to 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyGte250: { $gte: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyGte250" : true }
{ "item" : "abc2", "qty" : 200, "qtyGte250" : false }
{ "item" : "xyz1", "qty" : 250, "qtyGte250" : true }
{ "item" : "VWZ1", "qty" : 300, "qtyGte250" : true }
{ "item" : "VWZ2", "qty" : 180, "qtyGte250" : false }

$lt (aggregation)

Definition

$lt

Compares two values and returns:

true when the first value is less than the second value.

false when the first value is greater than or equivalent to the second value.

The $lt compares both value and type, using the specified BSON comparison order for values of different types.

$lt has the following syntax:

{ $lt: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $lt operator to determine if qty is less than 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyLt250: { $lt: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyLt250" : false }
{ "item" : "abc2", "qty" : 200, "qtyLt250" : true }
{ "item" : "xyz1", "qty" : 250, "qtyLt250" : false }
{ "item" : "VWZ1", "qty" : 300, "qtyLt250" : false }
{ "item" : "VWZ2", "qty" : 180, "qtyLt250" : true }

$lte (aggregation)

Definition

$lte

Compares two values and returns:

true when the first value is less than or equivalent to the second value.

false when the first value is greater than the second value.

The $lte compares both value and type, using the specified BSON comparison order for values of different types.

$lte has the following syntax:

{ $lte: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $lte operator to determine if qty is less than or equal to 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyLte250: { $lte: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyLte250" : false }
{ "item" : "abc2", "qty" : 200, "qtyLte250" : true }
{ "item" : "xyz1", "qty" : 250, "qtyLte250" : true }
{ "item" : "VWZ1", "qty" : 300, "qtyLte250" : false }
{ "item" : "VWZ2", "qty" : 180, "qtyLte250" : true }

$ne (aggregation)

Definition

$ne

Compares two values and returns:

true when the values are not equivalent.

false when the values are equivalent.

The $lte compares both value and type, using the specified BSON comparison order for values of different types.

$ne has the following syntax:

{ $ne: [ <expression1>, <expression2> ] }

For more information on expressions, see Expressions.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: "product 2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", description: "product 3", qty: 250 }
{ "_id" : 4, "item" : "VWZ1", description: "product 4", qty: 300 }
{ "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 }

The following operation uses the $ne operator to determine if qty does not equal 250:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            qty: 1,
            qtyNe250: { $ne: [ "$qty", 250 ] },
            _id: 0
          }
     }
   ]
)

The operation returns the following results:

{ "item" : "abc1", "qty" : 300, "qtyNe250" : true }
{ "item" : "abc2", "qty" : 200, "qtyNe250" : true }
{ "item" : "xyz1", "qty" : 250, "qtyNe250" : false }
{ "item" : "VWZ1", "qty" : 300, "qtyNe250" : true }
{ "item" : "VWZ2", "qty" : 180, "qtyNe250" : true }

Arithmetic Aggregation Operators

Arithmetic expressions perform mathematic operations on numbers. Some arithmetic expressions can also support date arithmetic.

Name
Description

$add
Adds numbers to return the sum, or adds numbers and a date to return a new date. If adding numbers and a date, treats the numbers as milliseconds. Accepts any number of argument expressions, but at most, one expression can resolve to a date.

$subtract
Returns the result of subtracting the second value from the first. If the two values are numbers, return the difference. If the two values are dates, return the difference in milliseconds. If the two values are a date and a number in milliseconds, return the resulting date. Accepts two argument expressions. If the two values are a date and a number, specify the date argument first as it is not meaningful to subtract a date from a number.

$multiply
Multiplies numbers to return the product. Accepts any number of argument expressions.

$divide
Returns the result of dividing the first number by the second. Accepts two argument expressions.

$mod
Returns the remainder of the first number divided by the second. Accepts two argument expressions.

$add (aggregation)

$subtract (aggregation)

$multiply (aggregation)

$divide (aggregation)

$mod (aggregation)

$add (aggregation)

Definition

$add

Adds numbers together or adds numbers and a date. If one of the arguments is a date, $add treats the other arguments as milliseconds to add to the date.

The $add expression has the following syntax:

{ $add: [ <expression1>, <expression2>, ... ] }

The arguments can be any valid expression as long as they resolve to either all numbers or to numbers and a date. For more information on expressions, see Expressions.

Examples

The following examples use a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "fee" : 2, date: ISODate("2014-03-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "fee" : 1, date: ISODate("2014-03-01T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5,  "fee" : 0, date: ISODate("2014-03-15T09:00:00Z") }

Add Numbers

The following aggregation uses the $add expression in the $project pipeline to calculate the total cost:

db.sales.aggregate(
   [
     { $project: { item: 1, total: { $add: [ "$price", "$fee" ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "total" : 12 }
{ "_id" : 2, "item" : "jkl", "total" : 21 }
{ "_id" : 3, "item" : "xyz", "total" : 5 }

Perform Addition on a Date

The following aggregation uses the $add expression to compute the billing_date by adding 3*24*60*60000 milliseconds (i.e. 3 days) to the date field :

db.sales.aggregate(
   [
     { $project: { item: 1, billing_date: { $add: [ "$date", 3*24*60*60000 ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "billing_date" : ISODate("2014-03-04T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "billing_date" : ISODate("2014-03-04T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "billing_date" : ISODate("2014-03-18T09:00:00Z") }

$subtract (aggregation)

Definition

$subtract

Subtracts two numbers to return the difference, or two dates to return the difference in milliseconds, or a date and a number in milliseconds to return the resulting date.

The $subtract expression has the following syntax:

{ $subtract: [ <expression1>, <expression2> ] }

The second argument is subtracted from the first argument.

The arguments can be any valid expression as long as they resolve to numbers and/or dates. To subtract a number from a date, the date must be the first argument. For more information on expressions, see Expressions.

Examples

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "fee" : 2, "discount" : 5, "date" : ISODate("2014-03-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "fee" : 1, "discount" : 2, "date" : ISODate("2014-03-01T09:00:00Z") }

Subtract Numbers

The following aggregation uses the $subtract expression to compute the total by subtracting the discount from the subtotal of price and fee.

db.sales.aggregate( [ { $project: { item: 1, total: { $subtract: [ { $add: [ "$price", "$fee" ] }, "$discount" ] } } } ] )

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "total" : 7 }
{ "_id" : 2, "item" : "jkl", "total" : 19 }

Subtract Two Dates

The following aggregation uses the $subtract expression to subtract $date from the current date:

db.sales.aggregate( [ { $project: { item: 1, dateDifference: { $subtract: [ new Date(), "$date" ] } } } ] )

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "dateDifference" : NumberLong("11713985194") }
{ "_id" : 2, "item" : "jkl", "dateDifference" : NumberLong("11710385194") }

Subtract Milliseconds from a Date

The following aggregation uses the $subtract expression to subtract 5 * 60 * 1000 milliseconds (5 minutes) from the “$date” field:

db.sales.aggregate( [ { $project: { item: 1, dateDifference: { $subtract: [ "$date", 5 * 60 * 1000 ] } } } ] )

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "dateDifference" : ISODate("2014-03-01T07:55:00Z") }
{ "_id" : 2, "item" : "jkl", "dateDifference" : ISODate("2014-03-01T08:55:00Z") }

$multiply (aggregation)

Definition

$multiply

Multiplies numbers together and returns the result. Pass the arguments to $multiply in an array.

The $multiply expression has the following syntax:

{ $multiply: [ <expression1>, <expression2>, ... ] }

The arguments can be any valid expression as long as they resolve to numbers. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity": 2, date: ISODate("2014-03-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity": 1, date: ISODate("2014-03-01T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity": 10, date: ISODate("2014-03-15T09:00:00Z") }

The following aggregation uses the $multiply expression in the $project pipeline to multiply the price and the quantity fields:

db.sales.aggregate(
   [
     { $project: { date: 1, item: 1, total: { $multiply: [ "$price", "$quantity" ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc", "date" : ISODate("2014-03-01T08:00:00Z"), "total" : 20 }
{ "_id" : 2, "item" : "jkl", "date" : ISODate("2014-03-01T09:00:00Z"), "total" : 20 }
{ "_id" : 3, "item" : "xyz", "date" : ISODate("2014-03-15T09:00:00Z"), "total" : 50 }

$divide (aggregation)

Definition

$divide

Divides one number by another and returns the result. Pass the arguments to $divide in an array.

The $divide expression has the following syntax:

{ $divide: [ <expression1>, <expression2> ] }

The first argument is the dividend, and the second argument is the divisor; i.e. the first argument is divided by the second argument.

The arguments can be any valid expression as long as the resolve to numbers. For more information on expressions, see Expressions.

Examples

Consider a planning collection with the following documents:

{ "_id" : 1, "name" : "A", "hours" : 80, "resources" : 7 },
{ "_id" : 2, "name" : "B", "hours" : 40, "resources" : 4 }

The following aggregation uses the $divide expression to divide the hours field by a literal 8 to compute the number of work days:

db.planning.aggregate(
   [
     { $project: { name: 1, workdays: { $divide: [ "$hours", 8 ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "name" : "A", "workdays" : 10 }
{ "_id" : 2, "name" : "B", "workdays" : 5 }

$mod (aggregation)

Definition

$mod

Divides one number by another and returns the remainder.

The $mod expression has the following syntax:

{ $mod: [ <expression1>, <expression2> ] }

The first argument is the dividend, and the second argument is the divisor; i.e. first argument is divided by the second argument.

The arguments can be any valid expression as long as they resolve to numbers. For more information on expressions, see Expressions.

Example

Consider a planning collection with the following documents:

{ "_id" : 1, "project" : "A", "hours" : 80, "tasks" : 7 }
{ "_id" : 2, "project" : "B", "hours" : 40, "tasks" : 4 }

The following aggregation uses the $mod expression to return the remainder of the hours field divided by the tasks field:

db.planning.aggregate(
   [
     { $project: { remainder: { $mod: [ "$hours", "$tasks" ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "remainder" : 3 }
{ "_id" : 2, "remainder" : 0 }

String Aggregation Operators

String expressions, with the exception of $concat, only have a well-defined behavior for strings of ASCII characters.

$concat behavior is well-defined regardless of the characters used.

Name | Description
$concat | Concatenates any number of strings.
$substr | Returns a substring of a string, starting at a specified index position up to a specified length. Accepts three expressions as arguments: the first argument must resolve to a string, and the second and third arguments must resolve to integers.
$toLower | Converts a string to lowercase. Accepts a single argument expression.
$toUpper | Converts a string to uppercase. Accepts a single argument expression.
$strcasecmp | Performs case-insensitive string comparison and returns: 0 if two strings are equivalent, 1 if the first string is greater than the second, and -1 if the first string is less than the second.

$concat (aggregation)

$substr (aggregation)

$toLower (aggregation)

$toUpper (aggregation)

$strcasecmp (aggregation)

$concat (aggregation)

Definition

$concat

New in version 2.4.

Concatenates strings and returns the concatenated string.

$concat has the following syntax:

{ $concat: [ <expression1>, <expression2>, ... ] }

The arguments can be any valid expression as long as they resolve to strings. For more information on expressions, see Expressions.

If the argument resolves to a value of null or refers to a field that is missing, $concat returns null.

Examples

Consider a inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "product 1" }
{ "_id" : 2, "item" : "ABC2", quarter: "13Q4", "description" : "product 2" }
{ "_id" : 3, "item" : "XYZ1", quarter: "14Q2", "description" : null }

The following operation uses the $concat operator to concatenate the item field and the description field with a `` - `` delimiter.

db.inventory.aggregate(
   [
      { $project: { itemDescription: { $concat: [ "$item", " - ", "$description" ] } } }
   ]
)

The operation returns the following results:

{ "_id" : 1, "itemDescription" : "ABC1 - product 1" }
{ "_id" : 2, "itemDescription" : "ABC2 - product 2" }
{ "_id" : 3, "itemDescription" : null }

$substr (aggregation)

Definition

$substr

Returns a substring of a string, starting at a specified index position and including the specified number of characters. The index is zero-based.

$substr has the following syntax:

{ $substr: [ <string>, <start>, <length> ] }

The arguments can be any valid expression as long as long as the first argument resolves to a string, and the second and third arguments resolve to integers. For more information on expressions, see Expressions.

Behavior

If <start> is a negative number, $substr returns an empty string "".

If <length> is a negative number, $substr returns a substring that starts at the specified index and includes the rest of the string.

$substr is not encoding aware and if used improperly may produce a result string containing an invalid UTF-8 character sequence.

$substr only has a well-defined behavior for strings of ASCII characters.

Example

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "product 1" }
{ "_id" : 2, "item" : "ABC2", quarter: "13Q4", "description" : "product 2" }
{ "_id" : 3, "item" : "XYZ1", quarter: "14Q2", "description" : null }

The following operation uses the $substr operator separate the quarter value into a yearSubstring and a quarterSubstring:

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            yearSubstring: { $substr: [ "$quarter", 0, 2 ] },
            quarterSubtring: { $substr: [ "$quarter", 2, -1 ] }
          }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "ABC1", "yearSubstring" : "13", "quarterSubtring" : "Q1" }
{ "_id" : 2, "item" : "ABC2", "yearSubstring" : "13", "quarterSubtring" : "Q4" }
{ "_id" : 3, "item" : "XYZ1", "yearSubstring" : "14", "quarterSubtring" : "Q2" }

$toLower (aggregation)

Definition

$toLower

Converts a string to lowercase, returning the result.

$toLower has the following syntax:

{ $toLower: <expression> }

The argument can be any expression as long as it resolves to a string. For more information on expressions, see Expressions.

If the argument resolves to null, $toLower returns an empty string "".

Behavior

$toLower only has a well-defined behavior for strings of ASCII characters.

Example

Consider a inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "PRODUCT 1" }
{ "_id" : 2, "item" : "abc2", quarter: "13Q4", "description" : "Product 2" }
{ "_id" : 3, "item" : "xyz1", quarter: "14Q2", "description" : null }

The following operation uses the $toLower operator return lowercase item and lowercase description value:

db.inventory.aggregate(
   [
     {
       $project:
         {
           item: { $toLower: "$item" },
           description: { $toLower: "$description" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "description" : "product 1" }
{ "_id" : 2, "item" : "abc2", "description" : "product 2" }
{ "_id" : 3, "item" : "xyz1", "description" : "" }

$toUpper (aggregation)

Definition

$toUpper

Converts a string to uppercase, returning the result.

$toUpper has the following syntax:

{ $toUpper: <expression> }

The argument can be any expression as long as it resolves to a string. For more information on expressions, see Expressions.

If the argument resolves to null, $toLower returns an empty string "".

Behavior

$toUpper only has a well-defined behavior for strings of ASCII characters.

Example

Consider a inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "PRODUCT 1" }
{ "_id" : 2, "item" : "abc2", quarter: "13Q4", "description" : "Product 2" }
{ "_id" : 3, "item" : "xyz1", quarter: "14Q2", "description" : null }

The following operation uses the $toUpper operator return uppercase item and uppercase description values:

db.inventory.aggregate(
   [
     {
       $project:
         {
           item: { $toUpper: "$item" },
           description: { $toUpper: "$description" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "ABC1", "description" : "PRODUCT 1" }
{ "_id" : 2, "item" : "ABC2", "description" : "PRODUCT 2" }
{ "_id" : 3, "item" : "XYZ1", "description" : "" }

$strcasecmp (aggregation)

Definition

$strcasecmp

Performs case-insensitive comparison of two strings. Returns

1 if first string is “greater than” the second string.

0 if the two strings are equal.

-1 if the first string is “less than” the second string.

$strcasecmp has the following syntax:

{ $strcasecmp: [ <expression1>, <expression2> ] }

The arguments can be any valid expression as long as they resolve to strings. For more information on expressions, see Expressions.

Behavior

$strcasecmp only has a well-defined behavior for strings of ASCII characters.

For a case sensitive comparison, see $cmp.

Example

Consider a inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "product 1" }
{ "_id" : 2, "item" : "ABC2", quarter: "13Q4", "description" : "product 2" }
{ "_id" : 3, "item" : "XYZ1", quarter: "14Q2", "description" : null }

The following operation uses the $strcasecmp operator to perform case-insensitive comparison of the quarter field value to the string "13q4":

db.inventory.aggregate(
   [
     {
       $project:
          {
            item: 1,
            comparisonResult: { $strcasecmp: [ "$quarter", "13q4" ] }
          }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "ABC1", "comparisonResult" : -1 }
{ "_id" : 2, "item" : "ABC2", "comparisonResult" : 0 }
{ "_id" : 3, "item" : "XYZ1", "comparisonResult" : 1 }

Text Search Aggregation Operators

Name | Description
$meta | Access text search metadata.

$meta (aggregation)

$meta (aggregation)

Definition

$meta

New in version 2.6.

Returns the metadata associated with a document in a pipeline operations, e.g. "textScore" when performing text search.

A $meta expression has the following syntax:

{ $meta: <metaDataKeyword> }

The $meta expression can specify the following keyword as the <metaDataKeyword>:

Keyword | Description | Sort Order
"textScore" | Returns the score associated with the corresponding $text query for each matching document. The text score signifies how well the document matched the stemmed term or terms. If not used in conjunction with a $text query, returns a score of null. | Descending

Behavior

The { $meta: "textScore" } expression is the only expression that the $sort stage accepts.

Although available for use everywhere expressions are accepted in the pipeline, the { $meta: "textScore" } expression is only meaningful in a pipeline that includes a $match stage with a $text query.

Examples

Consider an articles collection with the following documents:

{ "_id" : 1, "title" : "cakes and ale" }
{ "_id" : 2, "title" : "more cakes" }
{ "_id" : 3, "title" : "bread" }
{ "_id" : 4, "title" : "some cakes" }

The following aggregation operation performs a text search and use the $meta operator to group by the text search score:

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake" } } },
     { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } }
   ]
)

The operation returns the following results:

{ "_id" : 0.75, "count" : 1 }
{ "_id" : 1, "count" : 2 }

For more examples, see Text Search in the Aggregation Pipeline.

Array Aggregation Operators

Name | Description
$size | Returns the number of elements in the array. Accepts a single expression as argument.

$size (aggregation)

$size (aggregation)

New in version 2.6.

Definition

$size

Counts and returns the total the number of items in an array.

$size has the following syntax:

{ $size: <expression> }

The argument for $size can be any expression as long as it resolves to an array. For more information on expressions, see Expressions.

Example

Consider a inventory collection with the following documents:

{ "_id" : 1, "item" : "ABC1", "description" : "product 1", colors: [ "blue", "black", "red" ] }
{ "_id" : 2, "item" : "ABC2", "description" : "product 2", colors: [ "purple" ] }
{ "_id" : 3, "item" : "XYZ1", "description" : "product 3", colors: [ ] }

The following aggregation pipeline operation use the $size to return the number of elements in the colors array:

db.inventory.aggregate(
   [
      {
         $project: {
            item: 1,
            numberOfColors: { $size: "$colors" }
         }
      }
   ]
)

The operation returns the following:

{ "_id" : 1, "item" : "ABC1", "numberOfColors" : 3 }
{ "_id" : 2, "item" : "ABC2", "numberOfColors" : 1 }
{ "_id" : 3, "item" : "XYZ1", "numberOfColors" : 0 }

Aggregation Variable Operators

Name | Description
$map | Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters.
$let | Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters.

$map (aggregation)

$let (aggregation)

$map (aggregation)

Definition

$map

Applies an expression to each item in an array and returns an array with the applied results.

The $map expression has the following syntax:

{ $map: { input: <expression>, as: <string>, in: <expression> } }

Field | Specification
input | An expression that resolves to an array.
as | The variable name for the items in the input array. The in expression accesses each item in the input array by this variable.
in | The expression to apply to each item in the input array. The expression accesses the item by its variable name.

For more information on expressions, see Expressions.

Example

Consider a grades collection with the following documents:

{ _id: 1, quizzes: [ 5, 6, 7 ] }
{ _id: 2, quizzes: [ ] }
{ _id: 3, quizzes: [ 3, 8, 9 ] }

And the following $project statement:

db.grades.aggregate(
   [
      { $project:
         { adjustedGrades:
            {
              $map:
                 {
                   input: "$quizzes",
                   as: "grade",
                   in: { $add: [ "$$grade", 2 ] }
                 }
            }
         }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "adjustedGrades" : [ 7, 8, 9 ] }
{ "_id" : 2, "adjustedGrades" : [ ] }
{ "_id" : 3, "adjustedGrades" : [ 5, 10, 11 ] }

See also

$let

$let (aggregation)

Definition

$let

Binds variables for use in the specified expression, and returns the result of the expression.

The $let expression has the following syntax:

{
  $let:
     {
       vars: { <var1>: <expression>, ... },
       in: <expression>
     }
}

Field
Specification

vars

Assignment block for the variables accessible in the in expression. To assign a variable, specify a string for the variable name and assign a valid expression for the value.

The variable assignments have no meaning outside the in expression, not even within the vars block itself.

in
The expression to evaluate.

To access variables in aggregation expressions, prefix the variable name with double dollar signs ($$) and enclosed in quotes. For more information on expressions, see Expressions. For information on use of variables in the aggregation pipeline, see Variables in Aggregation Expressions.

Behavior

$let can access variables defined outside its expression block, including system variables.

If you modify the values of externally defined variables in the vars block, the new values take effect only in the in expression. Outside of the in expression, the variables retain their previous values.

In the vars assignment block, the order of the assignment does not matter, and the variable assignments only have meaning inside the in expression. As such, accessing a variable’s value in the vars assignment block refers to the value of the variable defined outside the vars block and not inside the same vars block.

For example, consider the following $let expression:

{
  $let:
    {
      vars: { low: 1, high: "$$low" },
      in: { $gt: [ "$$low", "$$high" ] }
    }
}

In the vars assignment block, "$$low" refers to the value of an externally defined variable low and not the variable defined in the same vars block. If low is not defined outside this $let expression block, the expression is invalid.

Example

A sales collection has the following documents:

{ _id: 1, price: 10, tax: 0.50, applyDiscount: true }
{ _id: 2, price: 10, tax: 0.25, applyDiscount: false }

The following aggregation uses $let in the $project pipeline stage to calculate and return the finalTotal for each document:

db.sales.aggregate( [
   {
      $project: {
         finalTotal: {
            $let: {
               vars: {
                  total: { $add: [ '$price', '$tax' ] },
                  discounted: { $cond: { if: '$applyDiscount', then: 0.9, else: 1 } }
               },
               in: { $multiply: [ "$$total", "$$discounted" ] }
            }
         }
      }
   }
] )

The aggregation returns the following results:

{ "_id" : 1, "finalTotal" : 9.450000000000001 }
{ "_id" : 2, "finalTotal" : 10.25 }

See also

$map

Aggregation Literal Operators

Name | Description
$literal | Return a value without parsing. Use for values that the aggregation pipeline may interpret as an expression. For example, use a $literal expression to a string that starts with a $ to avoid parsing as a field path.

$literal (aggregation)

$literal (aggregation)

Definition

$literal

Returns a value without parsing. Use for values that the aggregation pipeline may interpret as an expression.

The $literal expression has the following syntax:

{ $literal: <value> }

Behavior

If the <value> is an expression, $literal does not evaluate the expression but instead returns the unparsed expression.

Example |  | Result
{ $literal: { $add: [ 2, 3 ] } } |  | { "$add" : [ 2, 3 ] }
{ $literal:  { $literal: 1 } } |  | { "$literal" : 1 }

Examples

Treat $ as a Literal

In expression, the dollar sign $ evaluates to a field path; i.e. provides access to the field. For example, the $eq expression $eq: [ "$price", "$1" ] performs an equality check between the value in the field named price and the value in the field named 1 in the document.

The following example uses a $literal expression to treat a string that contains a dollar sign "$1" as a constant value.

A collection records has the following documents:

{ "_id" : 1, "item" : "abc123", price: "$2.50" }
{ "_id" : 2, "item" : "xyz123", price: "1" }
{ "_id" : 3, "item" : "ijk123", price: "$1" }

db.records.aggregate( [
   { $project: { costsOneDollar: { $eq: [ "$price", { $literal: "$1" } ] } } }
] )

This operation projects a field named costsOneDollar that holds a boolean value, indicating whether the value of the price field is equal to the string "$1":

{ "_id" : 1, "costsOneDollar" : false }
{ "_id" : 2, "costsOneDollar" : false }
{ "_id" : 3, "costsOneDollar" : true }

Project a New Field with Value 1

The $project stage uses the expression <field>: 1 to include the <field> in the output. The following example uses the $literal to return a new field set to the value of 1.

A collection bids has the following documents:

{ "_id" : 1, "item" : "abc123", condition: "new" }
{ "_id" : 2, "item" : "xyz123", condition: "new" }

The following aggregation evaluates the expression item: 1 to mean return the existing field item in the output, but uses the { $literal: 1 } expression to return a new field startAt set to the value 1:

db.bids.aggregate( [
   { $project: { item: 1, startAt: { $literal: 1 } } }
] )

The operation results in the following documents:

{ "_id" : 1, "item" : "abc123", "startAt" : 1 }
{ "_id" : 2, "item" : "xyz123", "startAt" : 1 }

Date Aggregation Operators

Name | Description
$dayOfYear | Returns the day of the year for a date as a number between 1 and 366 (leap year).
$dayOfMonth | Returns the day of the month for a date as a number between 1 and 31.
$dayOfWeek | Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday).
$year | Returns the year for a date as a number (e.g. 2014).
$month | Returns the month for a date as a number between 1 (January) and 12 (December).
$week | Returns the week number for a date as a number between 0 (the partial week that precedes the first Sunday of the year) and 53 (leap year).
$hour | Returns the hour for a date as a number between 0 and 23.
$minute | Returns the minute for a date as a number between 0 and 59.
$second | Returns the seconds for a date as a number between 0 and 60 (leap seconds).
$millisecond | Returns the milliseconds of a date as a number between 0 and 999.

$dayOfYear (aggregation)

$dayOfMonth (aggregation)

$dayOfWeek (aggregation)

$year (aggregation)

$month (aggregation)

$week (aggregation)

$hour (aggregation)

$minute (aggregation)

$second (aggregation)

$millisecond (aggregation)

$dayOfYear (aggregation)

Definition

$dayOfYear

Returns the day of the year for a date as a number between 1 and 366.

The $dayOfYear expression has the following syntax:

{ $dayOfYear: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $dayOfYear and other date expressions to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$dayOfMonth (aggregation)

Definition

$dayOfMonth

Returns the day of the month for a date as a number between 1 and 31.

The $dayOfMonth expression has the following syntax:

{ $dayOfMonth: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $dayOfMonth and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$dayOfWeek (aggregation)

Definition

$dayOfWeek

Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday).

The $dayOfWeek expression has the following syntax:

{ $dayOfWeek: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $dayOfWeek and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$year (aggregation)

Definition

$year

Returns the year portion of a date.

The $year expression has the following syntax:

{ $year: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $year and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$month (aggregation)

Definition

$month

Returns the month of a date as a number between 1 and 12.

The $month expression has the following syntax:

{ $month: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $month and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$week (aggregation)

Definition

$week

Returns the week of the year for a date as a number between 0 and 53.

Weeks begin on Sundays, and week 1 begins with the first Sunday of the year. Days preceding the first Sunday of the year are in week 0. This behavior is the same as the “%U” operator to the strftime standard library function.

The $week expression has the following syntax:

{ $week: <expression> }

The argument can be any valid expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $week and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$hour (aggregation)

Definition

$hour

Returns the hour portion of a date as a number between 0 and 23.

The $hour expression has the following syntax:

{ $hour: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $hour and other date expressions to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$minute (aggregation)

Definition

$minute

Returns the minute portion of a date as a number between 0 and 59.

The $minute expression has the following syntax:

{ $minute: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $minute and other date expressions to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$second (aggregation)

Definition

$second

Returns the second portion of a date as a number between 0 and 59, but can be 60 to account for leap seconds.

The $second expression has the following syntax:

{ $second: <expression> }

The argument can be any valid expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $second and other date expressions to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

$millisecond (aggregation)

Definition

$millisecond

Returns the millisecond portion of a date as an integer between 0 and 999.

The $millisecond expression has the following syntax:

{ $millisecond: <expression> }

The argument can be any expression as long as it resolves to a date. For more information on expressions, see Expressions.

Example

Consider a sales collection with the following document:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:15:39.736Z") }

The following aggregation uses the $millisecond and other date operators to break down the date field:

db.sales.aggregate(
   [
     {
       $project:
         {
           year: { $year: "$date" },
           month: { $month: "$date" },
           day: { $dayOfMonth: "$date" },
           hour: { $hour: "$date" },
           minutes: { $minute: "$date" },
           seconds: { $second: "$date" },
           milliseconds: { $millisecond: "$date" },
           dayOfYear: { $dayOfYear: "$date" },
           dayOfWeek: { $dayOfWeek: "$date" },
           week: { $week: "$date" }
         }
     }
   ]
)

The operation returns the following result:

{
  "_id" : 1,
  "year" : 2014,
  "month" : 1,
  "day" : 1,
  "hour" : 8,
  "minutes" : 15,
  "seconds" : 39,
  "milliseconds" : 736,
  "dayOfYear" : 1,
  "dayOfWeek" : 4,
  "week" : 0
}

Conditional Aggregation Operators

Name
Description

$cond
A ternary operator that evaluates one expression, and depending on the result, returns the value of one of the other two expressions. Accepts either three expressions in an ordered list or three named parameters.

$ifNull
Returns either the non-null result of the first expression or the result of the second expression if the first expression results in a null result. Null result encompasses instances of undefined values or missing fields. Accepts two expressions as arguments. The result of the second expression can be null.

$cond (aggregation)

$ifNull (aggregation)

$cond (aggregation)

Definition

$cond

Evaluates a boolean expression to return one of the two specified return expressions.

The $cond expression has one of two syntaxes:

New in version 2.6.

{ $cond: { if: <boolean-expression>, then: <true-case>, else: <false-case-> } }

Or:

{ $cond: [ <boolean-expression>, <true-case>, <false-case> ] }

If the <boolean-expression> evaluates to true, then $cond evaluates and returns the value of the <true-case> expression. Otherwise, $cond evaluates and returns the value of the <false-case> expression.

The arguments can be any valid expression. For more information on expressions, see Expressions.

Example

The following example use a inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", qty: 300 }
{ "_id" : 2, "item" : "abc2", qty: 200 }
{ "_id" : 3, "item" : "xyz1", qty: 250 }

The following aggregation operation uses the $cond expression to set the discount value to 30 if qty value is greater than or equal to 250 and to 20 if qty value is less than 250:

db.inventory.aggregate(
   [
      {
         $project:
           {
             item: 1,
             discount:
               {
                 $cond: { if: { $gte: [ "$qty", 250 ] }, then: 30, else: 20 }
               }
           }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "discount" : 30 }
{ "_id" : 2, "item" : "abc2", "discount" : 20 }
{ "_id" : 3, "item" : "xyz1", "discount" : 30 }

The following operation uses the array syntax of the $cond expression and returns the same results:

db.inventory.aggregate(
   [
      {
         $project:
           {
             item: 1,
             discount:
               {
                 $cond: [ { $gte: [ "$qty", 250 ] }, 30, 20 ]
               }
           }
      }
   ]
)

$ifNull (aggregation)

Definition

$ifNull

Evaluates an expression and returns the value of the expression if the expression evaluates to a non-null value. If the expression evaluates to a null value, including instances of undefined values or missing fields, returns the value of the replacement expression.

The $ifNull expression has the following syntax:

{ $ifNull: [ <expression>, <replacement-expression-if-null> ] }

The arguments can be any valid expression. For more information on expressions, see Expressions.

Example

The following example use a inventory collection with the following documents:

{ "_id" : 1, "item" : "abc1", description: "product 1", qty: 300 }
{ "_id" : 2, "item" : "abc2", description: null, qty: 200 }
{ "_id" : 3, "item" : "xyz1", qty: 250 }

The following operation uses the $ifNull expression to return either the non-null description field value or the string "Unspecified" if the description field is null or does not exist:

db.inventory.aggregate(
   [
      {
         $project: {
            item: 1,
            description: { $ifNull: [ "$description", "Unspecified" ] }
         }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "item" : "abc1", "description" : "product 1" }
{ "_id" : 2, "item" : "abc2", "description" : "Unspecified" }
{ "_id" : 3, "item" : "xyz1", "description" : "Unspecified" }

Group Accumulator Operators

Accumulators, available only for the $group stage, compute values by combining documents that share the same group key. Accumulators take as input a single expression, evaluating the expression once for each input document, and maintain their state for the group of documents.

Name | Description
$sum | Returns a sum for each group. Ignores non-numeric values.
$avg | Returns an average for each group. Ignores non-numeric values.
$first | Returns a value from the first document for each group. Order is only defined if the documents are in a defined order.
$last | Returns a value from the last document for each group. Order is only defined if the documents are in a defined order.
$max | Returns the highest expression value for each group.
$min | Returns the lowest expression value for each group.
$push | Returns an array of expression values for each group.
$addToSet | Returns an array of unique expression values for each group. Order of the array elements is undefined.

$sum (aggregation)

$avg (aggregation)

$first (aggregation)

$last (aggregation)

$max (aggregation)

$min (aggregation)

$push (aggregation)

$addToSet (aggregation)

$sum (aggregation)

Definition

$sum

Calculates and returns the sum of all the numeric values that result from applying a specified expression to each document in a group of documents that share the same group by key. $sum ignores non-numeric values.

$sum is an accumulator operator available only in the $group stage.

$sum has the following syntax:

{ $sum: <expression> }

For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }

Grouping the documents by the day and the year of the date field, the following operation uses the $sum accumulator to compute the total amount and the count for each group of documents.

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: { day: { $dayOfYear: "$date"}, year: { $year: "$date" } },
           totalAmount: { $sum: { $multiply: [ "$price", "$quantity" ] } },
           count: { $sum: 1 }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : { "day" : 46, "year" : 2014 }, "totalAmount" : 150, "count" : 2 }
{ "_id" : { "day" : 34, "year" : 2014 }, "totalAmount" : 45, "count" : 2 }
{ "_id" : { "day" : 1, "year" : 2014 }, "totalAmount" : 20, "count" : 1 }

$avg (aggregation)

Definition

$avg

Returns the average value of the numeric values that result from applying a specified expression to each document in a group of documents that share the same group by key. $avg ignores non-numeric values.

$avg is an accumulator operator available only in the $group stage.

$avg has the following syntax:

{ $avg: <expression> }

For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:12:00Z") }

Grouping the documents by the item field, the following operation uses the $avg accumulator to compute the average amount and average quantity for each grouping.

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: "$item",
           avgAmount: { $avg: { $multiply: [ "$price", "$quantity" ] } },
           avgQuantity: { $avg: "$quantity" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : "xyz", "avgAmount" : 37.5, "avgQuantity" : 7.5 }
{ "_id" : "jkl", "avgAmount" : 20, "avgQuantity" : 1 }
{ "_id" : "abc", "avgAmount" : 60, "avgQuantity" : 6 }

$first (aggregation)

Definition

$first

Returns the value that results from applying an expression to the first document in a group of documents that share the same group by key. Only meaningful when documents are in a defined order.

$first is an accumulator operator available only in the $group stage.

$first has the following syntax:

{ $first: <expression> }

For more information on expressions, see Expressions.

Behavior

When using $first in a $group stage, the $group stage should follow a $sort stage to have the input documents in a defined order.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }
{ "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") }
{ "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }

Grouping the documents by the item field, the following operation uses the $first accumulator to compute the first sales date for each item:

db.sales.aggregate(
   [
     { $sort: { item: 1, date: 1 } },
     {
       $group:
         {
           _id: "$item",
           firstSalesDate: { $first: "$date" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : "xyz", "firstSalesDate" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : "jkl", "firstSalesDate" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : "abc", "firstSalesDate" : ISODate("2014-01-01T08:00:00Z") }

$last (aggregation)

Definition

$last

Returns the value that results from applying an expression to the last document in a group of documents that share the same group by a field. Only meaningful when documents are in a defined order.

$last is an accumulator operator available only in the $group stage.

$last has the following syntax:

{ $last: <expression> }

For more information on expressions, see Expressions.

Behavior

When using $last in a $group stage, the $group stage should follow a $sort stage to have the input documents in a defined order.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }
{ "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") }
{ "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }

Grouping the documents by the item field, the following operation uses the $last accumulator to compute the last sales date for each item:

db.sales.aggregate(
   [
     { $sort: { item: 1, date: 1 } },
     {
       $group:
         {
           _id: "$item",
           lastSalesDate: { $last: "$date" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : "xyz", "lastSalesDate" : ISODate("2014-02-15T14:12:12Z") }
{ "_id" : "jkl", "lastSalesDate" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : "abc", "lastSalesDate" : ISODate("2014-02-15T08:00:00Z") }

$max (aggregation)

Definition

$max

Returns the highest value that results from applying an expression to each document in a group of documents that share the same group by key.

$max is an accumulator operator available only in the $group stage.

$max has the following syntax:

{ $max: <expression> }

For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }

Grouping the documents by the item field, the following operation uses the $max accumulator to compute the maximum total amount and maximum quantity for each group of documents.

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: "$item",
           maxTotalAmount: { $max: { $multiply: [ "$price", "$quantity" ] } },
           maxQuantity: { $max: "$quantity" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : "xyz", "maxTotalAmount" : 50, "maxQuantity" : 10 }
{ "_id" : "jkl", "maxTotalAmount" : 20, "maxQuantity" : 1 }
{ "_id" : "abc", "maxTotalAmount" : 100, "maxQuantity" : 10 }

$min (aggregation)

Definition

$min

Returns the lowest value that results from applying an expression to each document in a group of documents that share the same group by key.

$min is an accumulator operator available only in the $group stage.

$min has the following syntax:

{ $min: <expression> }

For more information on expressions, see Expressions.

Behavior

Changed in version 2.4.

If some, but not all, documents for the $min operation have either a null value for the field or are missing the field, the $min operator only considers the non-null and the non-missing values for the field.

If all documents for the $min operation have null value for the field or are missing the field, the $min operator returns null for the minimum value.

Before 2.4, if any of the documents for the $min operation were missing the field, the $min operator would not return any value. If any of the documents for the $min had the value null, the $min operator would return a null.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }

Grouping the documents by the item field, the following operation uses the $min accumulator to compute the minimum amount and minimum quantity for each grouping.

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: "$item",
           minQuantity: { $min: "$quantity" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : "xyz", "minQuantity" : 5 }
{ "_id" : "jkl", "minQuantity" : 1 }
{ "_id" : "abc", "minQuantity" : 2 }

$push (aggregation)

Definition

$push

Returns an array of all values that result from applying an expression to each document in a group of documents that share the same group by key.

$push is an accumulator operator available only in the $group stage.

$push has the following syntax:

{ $push: <expression> }

For more information on expressions, see Expressions.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }
{ "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") }
{ "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }

Grouping the documents by the day and the year of the date field, the following operation uses the $addToSet accumulator to compute the list of items and quantities sold for each group:

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: { day: { $dayOfYear: "$date"}, year: { $year: "$date" } },
           itemsSold: { $push:  { item: "$item", quantity: "$quantity" } }
         }
     }
   ]
)

The operation returns the following results:

{
   "_id" : { "day" : 46, "year" : 2014 },
   "itemsSold" : [
      { "item" : "abc", "quantity" : 10 },
      { "item" : "xyz", "quantity" : 10 },
      { "item" : "xyz", "quantity" : 5 },
      { "item" : "xyz", "quantity" : 10 }
   ]
}
{
   "_id" : { "day" : 34, "year" : 2014 },
   "itemsSold" : [
      { "item" : "jkl", "quantity" : 1 },
      { "item" : "xyz", "quantity" : 5 }
   ]
}
{
   "_id" : { "day" : 1, "year" : 2014 },
   "itemsSold" : [ { "item" : "abc", "quantity" : 2 } ]
}

$addToSet (aggregation)

Definition

$addToSet

Returns an array of all unique values that results from applying an expression to each document in a group of documents that share the same group by key. Order of the elements in the output array is unspecified.

$addToSet is an accumulator operator available only in the $group stage.

$addToSet has the following syntax:

{ $addToSet: <expression> }

For more information on expressions, see Expressions.

Behavior

If the value of the expression is an array, $addToSet appends the whole array as a single element.

If the value of the expression is a document, MongoDB determines that the document is a duplicate if another document in the array matches the to-be-added document exactly; i.e. the existing document has the exact same fields and values in the exact same order.

Example

Consider a sales collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
{ "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
{ "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
{ "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:12:00Z") }

Grouping the documents by the day and the year of the date field, the following operation uses the $addToSet accumulator to compute the list of unique items sold for each group:

db.sales.aggregate(
   [
     {
       $group:
         {
           _id: { day: { $dayOfYear: "$date"}, year: { $year: "$date" } },
           itemsSold: { $addToSet: "$item" }
         }
     }
   ]
)

The operation returns the following results:

{ "_id" : { "day" : 46, "year" : 2014 }, "itemsSold" : [ "xyz", "abc" ] }
{ "_id" : { "day" : 34, "year" : 2014 }, "itemsSold" : [ "xyz", "jkl" ] }
{ "_id" : { "day" : 1, "year" : 2014 }, "itemsSold" : [ "abc" ] }

Query Modifiers

Introduction

In addition to the MongoDB Query Operators, there are a number of “meta” operators that let you modify the output or behavior of a query. On the server, MongoDB treats the query and the options as a single object. The mongo shell and driver interfaces may provide cursor methods that wrap these options. When possible, use these methods; otherwise, you can add these options using either of the following syntax:

db.collection.find( { <query> } )._addSpecial( <option> )
db.collection.find( { $query: { <query> }, <option> } )

Operators

Modifiers

Many of these operators have corresponding methods in the shell. These methods provide a straightforward and user-friendly interface and are the preferred way to add these options.

Name | Description
$comment | Adds a comment to the query to identify queries in the database profiler output.
$explain | Forces MongoDB to report on query execution plans. See explain().
$hint | Forces MongoDB to use a specific index. See hint()
$maxScan | Limits the number of documents scanned.
$maxTimeMS | Specifies a cumulative time limit in milliseconds for processing operations on a cursor. See maxTimeMS().
$max | Specifies an exclusive upper limit for the index to use in a query. See max().
$min | Specifies an inclusive lower limit for the index to use in a query. See min().
$orderby | Returns a cursor with documents sorted according to a sort specification. See sort().
$returnKey | Forces the cursor to only return fields included in the index.
$showDiskLoc | Modifies the documents returned to include references to the on-disk location of each document.
$snapshot | Forces the query to use the index on the _id field. See snapshot().
$query | Wraps a query document.

$comment

$explain

$hint

$maxScan

$maxTimeMS

$max

$min

$orderby

$returnKey

$showDiskLoc

$snapshot

$query

Sort Order

Name | Description
$natural | A special sort order that orders documents using the order of documents on disk.

$natural

$comment

$comment

The $comment meta-operator makes it possible to attach a comment to a query in any context that $query may appear.

Because comments propagate to the profile log, adding a comment can make your profile data easier to interpret and trace.

Use $comment in one of the following ways:

db.collection.find( { <query> } )._addSpecial( "$comment", <comment> )
db.collection.find( { <query> } ).comment( <comment> )
db.collection.find( { $query: { <query> }, $comment: <comment> } )

To attach comments to query expressions in other contexts, such as db.collection.update(), use the $comment query operator instead of the meta-operator.

See also

$comment query operator

$explain

$explain

The $explain operator provides information on the query plan. It returns a document that describes the process and indexes used to return the query. This may provide useful insight when attempting to optimize a query. For details on the output, see cursor.explain().

You can specify the $explain operator in either of the following forms:

db.collection.find()._addSpecial( "$explain", 1 )
db.collection.find( { $query: {}, $explain: 1 } )

You also can specify $explain through the explain() method in the mongo shell:

db.collection.find().explain()

Behavior

$explain runs the actual query to determine the result. Although there are some differences between running the query with $explain and running without, generally, the performance will be similar between the two. So, if the query is slow, the $explain operation is also slow.

Additionally, the $explain operation reevaluates a set of candidate query plans, which may cause the $explain operation to perform differently than a normal query. As a result, these operations generally provide an accurate account of how MongoDB would perform the query, but do not reflect the length of these queries.

See also

explain()

Optimization Strategies for MongoDB page for information regarding optimization strategies.

Analyze Performance of Database Operations tutorial for information regarding the database profile.

Current Operation Reporting

$hint

$hint

The $hint operator forces the query optimizer to use a specific index to fulfill the query. Specify the index either by the index name or by document.

Use $hint for testing query performance and indexing strategies. The mongo shell provides a helper method hint() for the $hint operator.

Consider the following operation:

db.users.find().hint( { age: 1 } )

This operation returns all documents in the collection named users using the index on the age field.

You can also specify a hint using either of the following forms:

db.users.find()._addSpecial( "$hint", { age : 1 } )
db.users.find( { $query: {}, $hint: { age : 1 } } )

Note

When the query specifies the $hint in the following form:

db.users.find( { $query: {}, $hint: { age : 1 } } )

Then, in order to include the $explain option, you must add the $explain option to the document, as in the following:

db.users.find( { $query: {}, $hint: { age : 1 }, $explain: 1 } )

When an index filter exists for the query shape, MongoDB ignores the $hint. The explain.filterSet field of the explain() output indicates whether MongoDB applied an index filter for the query.

$maxScan

$maxScan

Constrains the query to only scan the specified number of documents when fulfilling the query. Use one of the following forms:

db.collection.find( { <query> } )._addSpecial( "$maxScan" , <number> )
db.collection.find( { $query: { <query> }, $maxScan: <number> } )

Use this modifier to prevent potentially long running queries from disrupting performance by scanning through too much data.

$maxTimeMS

$maxTimeMS

New in version 2.6: The $maxTimeMS operator specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.

The mongo shell provides the cursor.maxTimeMS() method

db.collection.find().maxTimeMS(100)

You can also specify the option in either of the following forms:

db.collection.find( { } , { $maxTimeMS: 100 } )
db.collection.find( { } )._addSpecial("$maxTimeMS", 100)

Interrupted operations return an error message similar to the following:

error: { "$err" : "operation exceeded time limit", "code" : 50 }

$max

Definition

$max

Specify a $max value to specify the exclusive upper bound for a specific index in order to constrain the results of find(). The $max specifies the upper bound for all keys of a specific index in order.

The mongo shell provides the max() wrapper method:

db.collection.find( { <query> } ).max( { field1: <max value>, ... fieldN: <max valueN> } )

You can also specify $max with either of the two forms:

db.collection.find( { <query> } )._addSpecial( "$max", { field1: <max value1>, ... fieldN: <max valueN> } )
db.collection.find( { $query: { <query> }, $max: { field1: <max value1>, ... fieldN: <max valueN> } } )

Behavior

Interaction with Index Selection

Because max() requires an index on a field, and forces the query to use this index, you may prefer the $lt operator for the query if possible. Consider the following example:

db.collection.find( { _id: 7 } ).max( { age: 25 } )

The query uses the index on the age field, even if the index on _id may be better.

Index Bounds

If you use $max with $min to specify a range, the index bounds specified in $min and $max must both refer to the keys of the same index.

$max without $min

The min and max operators indicate that the system should avoid normal query planning. Instead they construct an index scan where the index bounds are explicitly specified by the values given in min and max.

If one of the two boundaries is not specified, then the query plan will be an index scan that is unbounded on one side. This may degrade performance compared to a query containing neither operator, or one that uses both operators to more tightly constrain the index scan.

Examples

The following examples use the mongo shell wrappers.

Specify Exclusive Upper Bound

Consider the following operations on a collection named collection that has an index { age: 1 }:

db.collection.find( { <query> } ).max( { age: 100 } )

This operation limits the query to those documents where the field age is less than 100 and forces a query plan which scans the { age: 1 } index from MinKey to 100.

Index Selection

You can explicitly specify the corresponding index with hint(). Otherwise, MongoDB selects the index using the fields in the $max and $min bounds; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous.

Consider a collection named collection that has the following two indexes:

{ age: 1, type: -1 }
{ age: 1, type: 1 }

Without explicitly using hint(), MongoDB may select either index for the following operation:

db.collection.find().max( { age: 50, type: 'B' } )

Use with $min

Use $max alone or in conjunction with $min to limit results to a specific range for the same index, as in the following example:

db.collection.find().min( { age: 20 } ).max( { age: 25 } )

$min

Definition

$min

Specify a $min value to specify the inclusive lower bound for a specific index in order to constrain the results of find(). The $min specifies the lower bound for all keys of a specific index in order.

The mongo shell provides the min() wrapper method:

db.collection.find( { <query> } ).min( { field1: <min value>, ... fieldN: <min valueN>} )

You can also specify the option with either of the two forms:

db.collection.find( { <query> } )._addSpecial( "$min", { field1: <min value1>, ... fieldN: <min valueN> } )
db.collection.find( { $query: { <query> }, $min: { field1: <min value1>, ... fieldN: <min valueN> } } )

Behavior

Interaction with Index Selection

Because min() requires an index on a field, and forces the query to use this index, you may prefer the $gte operator for the query if possible. Consider the following example:

db.collection.find( { _id: 7 } ).min( { age: 25 } )

The query will use the index on the age field, even if the index on _id may be better.

Index Bounds

If you use $max with $min to specify a range, the index bounds specified in $min and $max must both refer to the keys of the same index.

$min without $max

The min and max operators indicate that the system should avoid normal query planning. Instead they construct an index scan where the index bounds are explicitly specified by the values given in min and max.

If one of the two boundaries is not specified, then the query plan will be an index scan that is unbounded on one side. This may degrade performance compared to a query containing neither operator, or one that uses both operators to more tightly constrain the index scan.

Examples

The following examples use the mongo shell wrappers.

Specify Inclusive Lower Bound

Consider the following operations on a collection named collection that has an index { age: 1 }:

db.collection.find().min( { age: 20 } )

This operation limits the query to those documents where the field age is at least 20 and forces a query plan which scans the { age: 1 } index from 20 to MaxKey.

Index Selection

You can explicitly specify the corresponding index with hint(). Otherwise, MongoDB selects the index using the fields in the $max and $min bounds; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous.

Consider a collection named collection that has the following two indexes:

{ age: 1, type: -1 }
{ age: 1, type: 1 }

Without explicitly using hint(), it is unclear which index the following operation will select:

db.collection.find().min( { age: 20, type: 'C' } )

Use with $max

You can use $min in conjunction with $max to limit results to a specific range for the same index, as in the following example:

db.collection.find().min( { age: 20 } ).max( { age: 25 } )

$orderby

$orderby

The $orderby operator sorts the results of a query in ascending or descending order.

The mongo shell provides the cursor.sort() method:

db.collection.find().sort( { age: -1 } )

You can also specify the option in either of the following forms:

db.collection.find()._addSpecial( "$orderby", { age : -1 } )
db.collection.find( { $query: {}, $orderby: { age : -1 } } )

These examples return all documents in the collection named collection sorted by the age field in descending order. Specify a value to $orderby of negative one (e.g. -1, as above) to sort in descending order or a positive value (e.g. 1) to sort in ascending order.

Behavior

The sort function requires that the entire sort be able to complete within 32 megabytes. When the sort option consumes more than 32 megabytes, MongoDB will return an error.

To avoid this error, create an index to support the sort operation or use $orderby in conjunction with $maxScan and/or cursor.limit(). The cursor.limit() increases the speed and reduces the amount of memory required to return this query by way of an optimized algorithm. The specified limit must result in a number of documents that fall within the 32 megabyte limit.

$returnKey

$returnKey

Only return the index field or fields for the results of the query. If $returnKey is set to true and the query does not use an index to perform the read operation, the returned documents will not contain any fields. Use one of the following forms:

db.collection.find( { <query> } )._addSpecial( "$returnKey", true )
db.collection.find( { $query: { <query> }, $returnKey: true } )

$showDiskLoc

$showDiskLoc

$showDiskLoc option adds a field $diskLoc to the returned documents. The value of the added $diskLoc field is a document that contains the disk location information:

"$diskLoc": {
  "file": <int>,
  "offset": <int>
}

The mongo shell provides the cursor.showDiskLoc() method for $showDiskLoc:

db.collection.find().showDiskLoc()

You can also specify the $showDiskLoc option in either of the following forms:

db.collection.find( { <query> } )._addSpecial("$showDiskLoc" , true)
db.collection.find( { $query: { <query> }, $showDiskLoc: true } )

Example

The following operation appends the showDiskLoc() method to the db.collection.find() method in order to include in the matching documents the disk location information:

db.collection.find( { a: 1 } ).showDiskLoc()

The operation returns the following documents, which includes the $diskLoc field:

{
  "_id" : ObjectId("53908ccb18facd50a75bfbac"),
  "a" : 1,
  "b" : 1,
  "$diskLoc" : { "file" : 0, "offset" : 16195760 }
}
{
   "_id" : ObjectId("53908cd518facd50a75bfbad"),
   "a" : 1,
   "b" : 2,
   "$diskLoc" : { "file" : 0, "offset" : 16195824 }
}

The projection can also access the added field $diskLoc, as in the following example:

db.collection.find( { a: 1 }, { $diskLoc: 1 } ).showDiskLoc()

The operation returns just the _id field and the $diskLoc field in the matching documents:

{
  "_id" : ObjectId("53908ccb18facd50a75bfbac"),
  "$diskLoc" : { "file" : 0, "offset" : 16195760 }
}
{
   "_id" : ObjectId("53908cd518facd50a75bfbad"),
   "$diskLoc" : { "file" : 0, "offset" : 16195824 }
}

$snapshot

$snapshot

The $snapshot operator prevents the cursor from returning a document more than once because an intervening write operation results in a move of the document.

Even in snapshot mode, objects inserted or deleted during the lifetime of the cursor may or may not be returned.

The mongo shell provides the cursor.snapshot() method:

db.collection.find().snapshot()

You can also specify the option in either of the following forms:

db.collection.find()._addSpecial( "$snapshot", true )
db.collection.find( { $query: {}, $snapshot: true } )

The $snapshot operator traverses the index on the _id field [1].

Warning

You cannot use $snapshot with sharded collections.

Do not use $snapshot with $hint or $orderby (or the corresponding cursor.hint() and cursor.sort() methods.)

[1]
You can achieve the $snapshot isolation behavior using any unique index on invariable fields.

$query

$query

The $query operator provides an interface to describe queries. Consider the following operation:

db.collection.find( { $query: { age : 25 } } )

This is equivalent to the more familiar db.collection.find() method:

db.collection.find( { age : 25 } )

These operations return only those documents in the collection named collection where the age field equals 25.

Note

Do not mix query forms. If you use the $query format, do not append cursor methods to the find(). To modify the query use the meta-query operators, such as $explain.

Therefore, the following two operations are equivalent:

db.collection.find( { $query: { age : 25 }, $explain: true } )
db.collection.find( { age : 25 } ).explain()

See also

For more information about queries in MongoDB see Read Operations, db.collection.find(), and Getting Started with MongoDB.

$natural

Definition

$natural

Use the $natural operator to use natural order for the results of a sort operation. Natural order refers to the logical ordering of documents internally within the database.

The $natural operator uses the following syntax to return documents in the order they exist on disk:

db.collection.find().sort( { $natural: 1 } )

Behavior

On a sharded collection the $natural operator returns a collection scan sorted in natural order, the order the database inserts and stores documents on disk.

You cannot specify $natural sort order if the query includes a $text expression.

Examples

Reverse Order

Use -1 to return documents in the reverse order as they occur on disk:

db.collection.find().sort( { $natural: -1 } )

Natural Order Comparison

To demonstrate natural ordering:

Create an { normal: 1 } index on a collection (e.g. coll).

Insert relevant objects with _id and normal values, for example, a document with _id and normal fields that both hold the same string:

db.coll.insert( { _id: "01", normal: "01" } )

Use values with different types for each document, but both fields in the document should have the same value:

Use .find().sort().explain() for all operations.

This scenario returns these results when using find() for different _id values; sorting with the $natural operator, _id index, and normal index; and a description of the explain() method output:

|  | sort() |
find() | $natural:1 | _id:1 | normal:1
_id:ObjectId() | explain() used B-Tree cursor | explain() used B-Tree cursor | explain() used B-Tree cursor
_id:Object() | explain() used B-Tree cursor | explain() used B-Tree cursor | explain() used B-Tree cursor
_id:string() | explain() used B-Tree cursor | explain() used B-Tree cursor | explain() used B-Tree cursor
_id:integer() | explain() used B-Tree cursor | explain() used B-Tree cursor | explain() used B-Tree cursor
_id:BinData() | explain() scanned entire collection | explain() used B-Tree cursor | explain() used B-Tree cursor
normal:(any query) | explain() scanned entire collection | explain() used B-Tree cursor | explain() used B-Tree cursor

Additional Information

cursor.sort()

Database Commands

All command documentation outlined below describes a command and its available parameters and provides a document template or prototype for each command. Some command documentation also includes the relevant mongo shell helpers.

User Commands

Aggregation Commands

Aggregation Commands

aggregate

count

distinct

group

mapReduce

Geospatial Commands

Geospatial Commands

geoNear

geoSearch

geoWalk

Query and Write Operation Commands

Query and Write Operation Commands

insert

update

delete

findAndModify

text

getLastError

getPrevError

resetError

eval

parallelCollectionScan

Query Plan Cache Commands

Query Plan Cache Commands

planCacheListFilters

planCacheSetFilter

planCacheClearFilters

planCacheListQueryShapes

planCacheListPlans

planCacheClear

Database Operations

Authentication Commands

Authentication Commands

logout

authenticate

copydbgetnonce

getnonce

authSchemaUpgrade

User Management Commands

User Management Commands

createUser

updateUser

dropUser

dropAllUsersFromDatabase

grantRolesToUser

revokeRolesFromUser

usersInfo

Role Management Commands

Role Management Commands

createRole

updateRole

dropRole

dropAllRolesFromDatabase

grantPrivilegesToRole

revokePrivilegesFromRole

grantRolesToRole

revokeRolesFromRole

rolesInfo

invalidateUserCache

Replication Commands

Replication Commands

replSetFreeze

replSetGetStatus

replSetInitiate

replSetMaintenance

replSetReconfig

replSetStepDown

replSetSyncFrom

resync

applyOps

isMaster

getoptime

See also

Replication for more information regarding replication.

Sharding Commands

Sharding Commands

flushRouterConfig

addShard

cleanupOrphaned

checkShardingIndex

enableSharding

listShards

removeShard

getShardMap

getShardVersion

mergeChunks

setShardVersion

shardCollection

shardingState

unsetSharding

split

splitChunk

splitVector

medianKey

moveChunk

movePrimary

isdbgrid

See also

Sharding for more information about MongoDB’s sharding functionality.

Instance Administration Commands

Administration Commands

renameCollection

copydb

dropDatabase

drop

create

clone

cloneCollection

cloneCollectionAsCapped

closeAllDatabases

convertToCapped

filemd5

createIndexes

dropIndexes

fsync

clean

connPoolSync

connectionStatus

compact

collMod

reIndex

setParameter

getParameter

repairDatabase

touch

shutdown

logRotate

Diagnostic Commands

Diagnostic Commands

listDatabases

dbHash

driverOIDTest

listCommands

availableQueryOptions

buildInfo

collStats

connPoolStats

shardConnPoolStats

dbStats

cursorInfo

dataSize

diagLogging

getCmdLineOpts

netstat

ping

profile

validate

top

indexStats

whatsmyuri

getLog

hostInfo

serverStatus

features

isSelf

Internal Commands

Internal Commands

handshake

recvChunkAbort

recvChunkCommit

recvChunkStart

recvChunkStatus

replSetFresh

mapreduce.shardedfinish

transferMods

replSetHeartbeat

replSetGetRBID

migrateClone

replSetElect

writeBacksQueued

writebacklisten

Testing Commands

Testing Commands

testDistLockWithSkew

testDistLockWithSyncCluster

captrunc

emptycapped

godinsert

_hashBSONElement

journalLatencyTest

sleep

replSetTest

forceerror

skewClockCommand

configureFailPoint

Auditing Commands

System Events Auditing Commands

logApplicationMessage

Aggregation Commands

Name | Description
aggregate | Performs aggregation tasks such as group using the aggregation framework.
count | Counts the number of documents in a collection.
distinct | Displays the distinct values found for a specified key in a collection.
group | Groups documents in a collection by the specified key and performs simple aggregation.
mapReduce | Performs map-reduce aggregation for large data sets.

aggregate

count

distinct

group

mapReduce

For a detailed comparison of the different approaches, see Aggregation Commands Comparison.

aggregate

aggregate

New in version 2.2.

Performs aggregation operation using the aggregation pipeline. The pipeline allows users to process data from a collection with a sequence of stage-based manipulations.

Changed in version 2.6.

The aggregate command adds support for returning a cursor, supports the explain option, and enhances its sort operations with an external sort facility.

aggregation pipeline introduces the $out operator to allow aggregate command to store results to a collection.

The command has following syntax:

Changed in version 2.6.

{
  aggregate: "<collection>",
  pipeline: [ <stage>, <...> ],
  explain: <boolean>,
  allowDiskUse: <boolean>,
  cursor: <document>
}

The aggregate command takes the following fields as arguments:

Field
Description

aggregate
The name of the collection to as the input for the aggregation pipeline.

pipeline
An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline.

explain

Optional. Specifies to return the information on the processing of the pipeline.

New in version 2.6.

allowDiskUse

Optional. Enables writing to temporary files. When set to true, aggregation stages can write data to the _tmp subdirectory in the dbPath directory.

New in version 2.6.

cursor

Optional. Specify a document that contains options that control the creation of the cursor object.

New in version 2.6.

field string aggregate:

The name of the collection to as the input for the aggregation pipeline.

field array pipeline:

An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline.

field boolean explain:

Optional. Specifies to return the information on the processing of the pipeline.

New in version 2.6.

field boolean allowDiskUse:

Optional. Enables writing to temporary files. When set to true, aggregation stages can write data to the _tmp subdirectory in the dbPath directory.

New in version 2.6.

field document cursor:

Optional. Specify a document that contains options that control the creation of the cursor object.

New in version 2.6.

For more information about the aggregation pipeline Aggregation Pipeline, Aggregation Reference, and Aggregation Pipeline Limits.

Example

Aggregate Data with Multi-Stage Pipeline

A collection articles contains documents such as the following:

{
   _id: ObjectId("52769ea0f3dc6ead47c9a1b2"),
   author: "abc123",
   title: "zzz",
   tags: [ "programming", "database", "mongodb" ]
}

The following example performs an aggregate operation on the articles collection to calculate the count of each distinct element in the tags array that appears in the collection.

db.runCommand(
   { aggregate: "articles",
     pipeline: [
                 { $project: { tags: 1 } },
                 { $unwind: "$tags" },
                 { $group: {
                             _id: "$tags",
                             count: { $sum : 1 }
                           }
                 }
               ]
   }
)

In the mongo shell, this operation can use the aggregate() helper as in the following:

db.articles.aggregate(
                       [
                          { $project: { tags: 1 } },
                          { $unwind: "$tags" },
                          { $group: {
                                      _id: "$tags",
                                      count: { $sum : 1 }
                                    }
                          }
                       ]
)

Note

In 2.6 and later, the aggregate() helper always returns a cursor.

Changed in version 2.4: If an error occurs, the aggregate() helper throws an exception. In previous versions, the helper returned a document with the error message and code, and ok status field not equal to 1, same as the aggregate command.

Return Information on the Aggregation Operation

The following aggregation operation sets the optional field explain to true to return information about the aggregation operation.

db.runCommand( { aggregate: "orders",
                 pipeline: [
                             { $match: { status: "A" } },
                             { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                             { $sort: { total: -1 } }
                           ],
                 explain: true
              } )

Note

The intended readers of the explain output document are humans, and not machines, and the output format is subject to change between releases.

See also

db.collection.aggregate() method

Aggregate Data using External Sort

Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set allowDiskUse option to true to enable writing data to temporary files, as in the following example:

db.runCommand(
   { aggregate: "stocks",
     pipeline: [
                 { $project : { cusip: 1, date: 1, price: 1, _id: 0 } },
                 { $sort : { cusip : 1, date: 1 } }
               ],
     allowDiskUse: true
   }
)

See also

db.collection.aggregate()

Aggregate Command Returns a Cursor

Note

Using the aggregate command to return a cursor is a low-level operation, intended for authors of drivers. Most users should use the db.collection.aggregate() helper provided in the mongo shell or in their driver. In 2.6 and later, the aggregate() helper always returns a cursor.

The following command returns a document that contains results with which to instantiate a cursor object.

db.runCommand(
   { aggregate: "records",
     pipeline: [
        { $project: { name: 1, email: 1, _id: 0 } },
        { $sort: { name: 1 } }
     ],
     cursor: { }
   }
)

To specify an initial batch size, specify the batchSize in the cursor field, as in the following example:

db.runCommand(
   { aggregate: "records",
     pipeline: [
        { $project: { name: 1, email: 1, _id: 0 } },
        { $sort: { name: 1 } }
     ],
     cursor: { batchSize: 0 }
   }
)

The {batchSize: 0 } document specifies the size of the initial batch size only. Specify subsequent batch sizes to OP_GET_MORE [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/#wire-op-get-more] operations as with other MongoDB cursors. A batchSize of 0 means an empty first batch and is useful if you want to quickly get back a cursor or failure message, without doing significant server-side work.

See also

db.collection.aggregate()

count

Definition

count

Counts the number of documents in a collection. Returns a document that contains this count and as well as the command status. count has the following form:

Changed in version 2.6: count now accepts the hint option to specify an index.

{ count: <collection>, query: <query>, limit: <limit>, skip: <skip>, hint: <hint> }

count has the following fields:

Field
Description

count
The name of the collection to count.

query
Optional. A query that selects which documents to count in a collection.

limit
Optional. The maximum number of matching documents to return.

skip
Optional. The number of matching documents to skip before returning results.

hint

Optional. The index to use. Specify either the index name as a string or the index specification document.

New in version 2.6.

field string count:

The name of the collection to count.

field document query:

Optional. A query that selects which documents to count in a collection.

field integer limit:

Optional. The maximum number of matching documents to return.

field integer skip:

Optional. The number of matching documents to skip before returning results.

field String, document hint:

Optional. The index to use. Specify either the index name as a string or the index specification document.

New in version 2.6.

MongoDB also provides the count() and db.collection.count() wrapper methods in the mongo shell.

Behavior

On a sharded cluster, count can result in an inaccurate count if orphaned documents exist or if a chunk migration is in progress.

To avoid these situations, on a sharded cluster, use the $group stage of the db.collection.aggregate() method to $sum the documents. For example, the following operation counts the documents in a collection:

db.collection.aggregate(
   [
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

To get a count of documents that match a query condition, include the $match stage as well:

db.collection.aggregate(
   [
      { $match: <query condition> },
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

See Perform a Count for an example.

Examples

The following sections provide examples of the count command.

Count All Documents

The following operation counts the number of all documents in the orders collection:

db.runCommand( { count: 'orders' } )

In the result, the n, which represents the count, is 26, and the command status ok is 1:

{ "n" : 26, "ok" : 1 }

Count Documents That Match a Query

The following operation returns a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012'):

db.runCommand( { count:'orders',
                 query: { ord_dt: { $gt: new Date('01/01/2012') } }
               } )

In the result, the n, which represents the count, is 13 and the command status ok is 1:

{ "n" : 13, "ok" : 1 }

Skip Documents in Count

The following operation returns a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012') and skip the first 10 matching documents:

db.runCommand( { count:'orders',
                 query: { ord_dt: { $gt: new Date('01/01/2012') } },
                 skip: 10 }  )

In the result, the n, which represents the count, is 3 and the command status ok is 1:

{ "n" : 3, "ok" : 1 }

Specify the Index to Use

The following operation uses the index { status: 1 } to return a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012') and the status field is equal to "D":

db.runCommand(
   {
     count:'orders',
     query: {
              ord_dt: { $gt: new Date('01/01/2012') },
              status: "D"
            },
     hint: { status: 1 }
   }
)

In the result, the n, which represents the count, is 1 and the command status ok is 1:

{ "n" : 1, "ok" : 1 }

distinct

Definition

distinct

Finds the distinct values for a specified field across a single collection. distinct returns a document that contains an array of the distinct values. The return document also contains an embedded document with query statistics and the query plan.

The command takes the following form:

{ distinct: "<collection>", key: "<field>", query: <query> }

The command contains the following fields:

Field | Description
distinct | The name of the collection to query for distinct values.
key | The field for which to return distinct values.
query | Optional. A query that specifies the documents from which to retrieve the distinct values.

field string distinct:
| The name of the collection to query for distinct values.
field string key:
| The field for which to return distinct values.
field document query:
| Optional. A query that specifies the documents from which to retrieve the distinct values.

MongoDB also provides the shell wrapper method db.collection.distinct() for the distinct command. Additionally, many MongoDB drivers also provide a wrapper method. Refer to the specific driver documentation.

Behavior

Array Fields

If the value of the specified field is an array, distinct considers each element of the array as a separate value.

For instance, if a field has as its value [ 1, [1], 1 ], then distinct considers 1, [1], and 1 as separate values.

For an example, see Return Distinct Values for an Array Field.

Index Use

When possible, distinct operations can use indexes.

Indexes can also cover distinct operations. See Covering a Query for more information on queries covered by indexes.

Examples

The examples use the inventory collection that contains the following documents:

{ "_id": 1, "dept": "A", "item": { "sku": "111", "color": "red" }, "sizes": [ "S", "M" ] }
{ "_id": 2, "dept": "A", "item": { "sku": "111", "color": "blue" }, "sizes": [ "M", "L" ] }
{ "_id": 3, "dept": "B", "item": { "sku": "222", "color": "blue" }, "sizes": "S" }
{ "_id": 4, "dept": "A", "item": { "sku": "333", "color": "black" }, "sizes": [ "S" ] }

Return Distinct Values for a Field

The following example returns the distinct values for the field dept from all documents in the inventory collection:

db.runCommand ( { distinct: "inventory", key: "dept" } )

The command returns a document with a field named values that contains the distinct dept values:

{
   "values" : [ "A", "B" ],
   "stats" : { ... },
   "ok" : 1
}

Return Distinct Values for an Embedded Field

The following example returns the distinct values for the field sku, embedded in the item field, from all documents in the inventory collection:

db.runCommand ( { distinct: "inventory", key: "item.sku" } )

The command returns a document with a field named values that contains the distinct sku values:

{
  "values" : [ "111", "222", "333" ],
  "stats" : { ... },
  "ok" : 1
}

See also

Dot Notation for information on accessing fields within embedded documents

Return Distinct Values for an Array Field

The following example returns the distinct values for the field sizes from all documents in the inventory collection:

db.runCommand ( { distinct: "inventory", key: "sizes" } )

The command returns a document with a field named values that contains the distinct sizes values:

{
  "values" : [ "M", "S", "L" ],
  "stats" : { ... },
  "ok" : 1
}

For information on distinct and array fields, see the Behavior section.

Specify Query with distinct

The following example returns the distinct values for the field sku, embedded in the item field, from the documents whose dept is equal to "A":

db.runCommand ( { distinct: "inventory", key: "item.sku", query: { dept: "A"} } )

The command returns a document with a field named values that contains the distinct sku values:

{
  "values" : [ "111", "333" ],
  "stats" : { ... },
  "ok" : 1
}

group

Definition

group

Groups documents in a collection by the specified key and performs simple aggregation functions, such as computing counts and sums. The command is analogous to a SELECT <...> GROUP BY statement in SQL. The command returns a document with the grouped records as well as the command meta-data.

The group command takes the following prototype form:

{
  group:
   {
     ns: <namespace>,
     key: <key>,
     $reduce: <reduce function>,
     $keyf: <key function>,
     cond: <query>,
     finalize: <finalize function>
   }
}

The command accepts a document with the following fields:

Field
Description

ns
The collection from which to perform the group by operation.

key
The field or fields to group. Returns a “key object” for use as the grouping key.

$reduce
An aggregation function that operates on the documents during the grouping operation. These functions may return a sum or a count. The function takes two arguments: the current document and an aggregation result document for that group.

initial
Initializes the aggregation result document.

$keyf
Optional. Alternative to the key field. Specifies a function that creates a “key object” for use as the grouping key. Use $keyf instead of key to group by calculated fields rather than existing document fields.

cond
Optional. The selection criteria to determine which documents in the collection to process. If you omit the cond field, group processes all the documents in the collection for the group operation.

finalize
Optional. A function that runs each item in the result set before group returns the final value. This function can either modify the result document or replace the result document as a whole. Unlike the $keyf and $reduce fields that also specify a function, this field name is finalize, not $finalize.

field string ns:

The collection from which to perform the group by operation.

field document key:

The field or fields to group. Returns a “key object” for use as the grouping key.

field function $reduce:

An aggregation function that operates on the documents during the grouping operation. These functions may return a sum or a count. The function takes two arguments: the current document and an aggregation result document for that group.

field document initial:

Initializes the aggregation result document.

field function $keyf:

Optional. Alternative to the key field. Specifies a function that creates a “key object” for use as the grouping key. Use $keyf instead of key to group by calculated fields rather than existing document fields.

field document cond:

Optional. The selection criteria to determine which documents in the collection to process. If you omit the cond field, group processes all the documents in the collection for the group operation.

field function finalize:

Optional. A function that runs each item in the result set before group returns the final value. This function can either modify the result document or replace the result document as a whole. Unlike the $keyf and $reduce fields that also specify a function, this field name is finalize, not $finalize.

For the shell, MongoDB provides a wrapper method db.collection.group(). However, the db.collection.group() method takes the keyf field and the reduce field whereas the group command takes the $keyf field and the $reduce field.

Behavior

Limits and Restrictions

The group command does not work with sharded clusters. Use the aggregation framework or map-reduce in sharded environments.

The result set must fit within the maximum BSON document size.

Additionally, in version 2.2, the returned array can contain at most 20,000 elements; i.e. at most 20,000 unique groupings. For group by operations that results in more than 20,000 unique groupings, use mapReduce. Previous versions had a limit of 10,000 elements.

Prior to 2.4, the group command took the mongod instance’s JavaScript lock which blocked all other JavaScript execution.

mongo Shell JavaScript Functions/Properties

Changed in version 2.4.

In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties
Available Functions

args

MaxKey

MinKey

assert()

BinData()

DBPointer()

DBRef()

doassert()

emit()

gc()

HexData()

hex_md5()

isNumber()

isObject()

ISODate()

isString()

Map()

MD5()

NumberInt()

NumberLong()

ObjectId()

print()

printjson()

printjsononeline()

sleep()

Timestamp()

tojson()

tojsononeline()

tojsonObject()

UUID()

version()

JavaScript in MongoDB

Although group uses JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

Examples

The following are examples of the db.collection.group() method. The examples assume an orders collection with documents of the following prototype:

{
  _id: ObjectId("5085a95c8fada716c89d0021"),
  ord_dt: ISODate("2012-07-01T04:00:00Z"),
  ship_dt: ISODate("2012-07-02T04:00:00Z"),
  item:
    {
      sku: "abc123",
      price: 1.99,
      uom: "pcs",
      qty: 25
    }
}

Group by Two Fields

The following example groups by the ord_dt and item.sku fields those documents that have ord_dt greater than 01/01/2012:

db.runCommand(
   {
     group:
       {
         ns: 'orders',
         key: { ord_dt: 1, 'item.sku': 1 },
         cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
         $reduce: function ( curr, result ) { },
         initial: { }
       }
   }
)

The result is a document that contain the retval field which contains the group by records, the count field which contains the total number of documents grouped, the keys field which contains the number of unique groupings (i.e. number of elements in the retval), and the ok field which contains the command status:

{ "retval" :
      [ { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc456"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "bcd123"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "efg456"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "efg456"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "ijk123"},
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc456"},
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc456"}
      ],
  "count" : 13,
  "keys" : 11,
  "ok" : 1 }

The method call is analogous to the SQL statement:

SELECT ord_dt, item_sku
FROM orders
WHERE ord_dt > '01/01/2012'
GROUP BY ord_dt, item_sku

Calculate the Sum

The following example groups by the ord_dt and item.sku fields those documents that have ord_dt greater than 01/01/2012 and calculates the sum of the qty field for each grouping:

db.runCommand(
   { group:
       {
         ns: 'orders',
         key: { ord_dt: 1, 'item.sku': 1 },
         cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
         $reduce: function ( curr, result ) {
                     result.total += curr.item.qty;
                  },
         initial: { total : 0 }
       }
    }
)

The retval field of the returned document is an array of documents that contain the group by fields and the calculated aggregation field:

{ "retval" :
      [ { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc456", "total" : 25 },
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "bcd123", "total" : 10 },
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "efg456", "total" : 10 },
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "efg456", "total" : 15 },
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "ijk123", "total" : 20 },
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc123", "total" : 45 },
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc456", "total" : 25 },
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc456", "total" : 25 }
      ],
  "count" : 13,
  "keys" : 11,
  "ok" : 1 }

The method call is analogous to the SQL statement:

SELECT ord_dt, item_sku, SUM(item_qty) as total
FROM orders
WHERE ord_dt > '01/01/2012'
GROUP BY ord_dt, item_sku

Calculate Sum, Count, and Average

The following example groups by the calculated day_of_week field, those documents that have ord_dt greater than 01/01/2012 and calculates the sum, count, and average of the qty field for each grouping:

db.runCommand(
   {
     group:
       {
         ns: 'orders',
         $keyf: function(doc) {
                    return { day_of_week: doc.ord_dt.getDay() };
                },
         cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
         $reduce: function( curr, result ) {
                      result.total += curr.item.qty;
                      result.count++;
                  },
         initial: { total : 0, count: 0 },
         finalize: function(result) {
                      var weekdays = [
                           "Sunday", "Monday", "Tuesday",
                           "Wednesday", "Thursday",
                           "Friday", "Saturday"
                          ];
                      result.day_of_week = weekdays[result.day_of_week];
                      result.avg = Math.round(result.total / result.count);
                   }
       }
   }
)

The retval field of the returned document is an array of documents that contain the group by fields and the calculated aggregation field:

{
  "retval" :
      [
        { "day_of_week" : "Sunday", "total" : 70, "count" : 4, "avg" : 18 },
        { "day_of_week" : "Friday", "total" : 110, "count" : 6, "avg" : 18 },
        { "day_of_week" : "Tuesday", "total" : 70, "count" : 3, "avg" : 23 }
      ],
  "count" : 13,
  "keys" : 3,
  "ok" : 1
}

See also

Aggregation Concepts

mapReduce

mapReduce

The mapReduce command allows you to run map-reduce aggregation operations over a collection. The mapReduce command has the following prototype form:

db.runCommand(
               {
                 mapReduce: <collection>,
                 map: <function>,
                 reduce: <function>,
                 finalize: <function>,
                 out: <output>,
                 query: <document>,
                 sort: <document>,
                 limit: <number>,
                 scope: <document>,
                 jsMode: <boolean>,
                 verbose: <boolean>
               }
             )

Pass the name of the collection to the mapReduce command (i.e. <collection>) to use as the source documents to perform the map reduce operation. The command also accepts the following parameters:

Field
Description

mapReduce
The name of the collection on which you want to perform map-reduce. This collection will be filtered using query before being processed by the map function.

map

A JavaScript function that associates or “maps” a value with a key and emits the key and value pair.

See Requirements for the map Function for more information.

reduce

A JavaScript function that “reduces” to a single object all the values associated with a particular key.

See Requirements for the reduce Function for more information.

out

Specifies where to output the result of the map-reduce operation. You can either output to a collection or return the result inline. On a primary member of a replica set you can output either to a collection or inline, but on a secondary, only inline output is possible.

See out Options for more information.

query
Optional. Specifies the selection criteria using query operators for determining the documents input to the map function.

sort
Optional. Sorts the input documents. This option is useful for optimization. For example, specify the sort key to be the same as the emit key so that there are fewer reduce operations. The sort key must be in an existing index for this collection.

limit
Optional. Specifies a maximum number of documents for the input into the map function.

finalize

Optional. Follows the reduce method and modifies the output.

See Requirements for the finalize Function for more information.

scope
Optional. Specifies global variables that are accessible in the map, reduce and finalize functions.

jsMode

Optional. Specifies whether to convert intermediate data into BSON format between the execution of the map and reduce functions. Defaults to false.

If false:

Internally, MongoDB converts the JavaScript objects emitted by the map function to BSON objects. These BSON objects are then converted back to JavaScript objects when calling the reduce function.

The map-reduce operation places the intermediate BSON objects in temporary, on-disk storage. This allows the map-reduce operation to execute over arbitrarily large data sets.

If true:

Internally, the JavaScript objects emitted during map function remain as JavaScript objects. There is no need to convert the objects for the reduce function, which can result in faster execution.

You can only use jsMode for result sets with fewer than 500,000 distinct key arguments to the mapper’s emit() function.

The jsMode defaults to false.

verbose
Optional. Specifies whether to include the timing information in the result information. The verbose defaults to true to include the timing information.

field collection mapReduce:

The name of the collection on which you want to perform map-reduce. This collection will be filtered using query before being processed by the map function.

field Javascript function map:

A JavaScript function that associates or “maps” a value with a key and emits the key and value pair.

See Requirements for the map Function for more information.

field JavaScript function reduce:

A JavaScript function that “reduces” to a single object all the values associated with a particular key.

See Requirements for the reduce Function for more information.

field string or document out:

Specifies where to output the result of the map-reduce operation. You can either output to a collection or return the result inline. On a primary member of a replica set you can output either to a collection or inline, but on a secondary, only inline output is possible.

See out Options for more information.

field document query:

Optional. Specifies the selection criteria using query operators for determining the documents input to the map function.

field document sort:

Optional. Sorts the input documents. This option is useful for optimization. For example, specify the sort key to be the same as the emit key so that there are fewer reduce operations. The sort key must be in an existing index for this collection.

field number limit:

Optional. Specifies a maximum number of documents for the input into the map function.

field Javascript function finalize:

Optional. Follows the reduce method and modifies the output.

See Requirements for the finalize Function for more information.

field document scope:

Optional. Specifies global variables that are accessible in the map, reduce and finalize functions.

field Boolean jsMode:

Optional. Specifies whether to convert intermediate data into BSON format between the execution of the map and reduce functions. Defaults to false.

If false:

Internally, MongoDB converts the JavaScript objects emitted by the map function to BSON objects. These BSON objects are then converted back to JavaScript objects when calling the reduce function.

The map-reduce operation places the intermediate BSON objects in temporary, on-disk storage. This allows the map-reduce operation to execute over arbitrarily large data sets.

If true:

Internally, the JavaScript objects emitted during map function remain as JavaScript objects. There is no need to convert the objects for the reduce function, which can result in faster execution.

You can only use jsMode for result sets with fewer than 500,000 distinct key arguments to the mapper’s emit() function.

The jsMode defaults to false.

field Boolean verbose:

Optional. Specifies whether to include the timing information in the result information. The verbose defaults to true to include the timing information.

The following is a prototype usage of the mapReduce command:

var mapFunction = function() { ... };
var reduceFunction = function(key, values) { ... };

db.runCommand(
               {
                 mapReduce: <input-collection>,
                 map: mapFunction,
                 reduce: reduceFunction,
                 out: { merge: <output-collection> },
                 query: <query>
               }
             )

JavaScript in MongoDB

Although mapReduce uses JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

Note

Changed in version 2.4.

In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties
Available Functions

args

MaxKey

MinKey

assert()

BinData()

DBPointer()

DBRef()

doassert()

emit()

gc()

HexData()

hex_md5()

isNumber()

isObject()

ISODate()

isString()

Map()

MD5()

NumberInt()

NumberLong()

ObjectId()

print()

printjson()

printjsononeline()

sleep()

Timestamp()

tojson()

tojsononeline()

tojsonObject()

UUID()

version()

Requirements for the map Function

The map function is responsible for transforming each input document into zero or more documents. It can access the variables defined in the scope parameter, and has the following prototype:

function() {
   ...
   emit(key, value);
}

The map function has the following requirements:

In the map function, reference the current document as this within the function.

The map function should not access the database for any reason.

The map function should be pure, or have no impact outside of the function (i.e. side effects.)

A single emit can only hold half of MongoDB’s maximum BSON document size.

The map function may optionally call emit(key,value) any number of times to create an output document associating key with value.

The following map function will call emit(key,value) either 0 or 1 times depending on the value of the input document’s status field:

function() {
    if (this.status == 'A')
        emit(this.cust_id, 1);
}

The following map function may call emit(key,value) multiple times depending on the number of elements in the input document’s items field:

function() {
    this.items.forEach(function(item){ emit(item.sku, 1); });
}

Requirements for the reduce Function

The reduce function has the following prototype:

function(key, values) {
   ...
   return result;
}

The reduce function exhibits the following behaviors:

The reduce function should not access the database, even to perform read operations.

The reduce function should not affect the outside system.

MongoDB will not call the reduce function for a key that has only a single value. The values argument is an array whose elements are the value objects that are “mapped” to the key.

MongoDB can invoke the reduce function more than once for the same key. In this case, the previous output from the reduce function for that key will become one of the input values to the next reduce function invocation for that key.

The reduce function can access the variables defined in the scope parameter.

The inputs to reduce must not be larger than half of MongoDB’s maximum BSON document size. This requirement may be violated when large documents are returned and then joined together in subsequent reduce steps.

Because it is possible to invoke the reduce function more than once for the same key, the following properties need to be true:

the type of the return object must be identical to the type of the value emitted by the map function.

the reduce function must be associative. The following statement must be true:

reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce( key, [ C, A, B ] )

the reduce function must be idempotent. Ensure that the following statement is true:

reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray )

the reduce function should be commutative: that is, the order of the elements in the valuesArray should not affect the output of the reduce function, so that the following statement is true:

reduce( key, [ A, B ] ) == reduce( key, [ B, A ] )

Requirements for the finalize Function

The finalize function has the following prototype:

function(key, reducedValue) {
   ...
   return modifiedObject;
}

The finalize function receives as its arguments a key value and the reducedValue from the reduce function. Be aware that:

The finalize function should not access the database for any reason.

The finalize function should be pure, or have no impact outside of the function (i.e. side effects.)

The finalize function can access the variables defined in the scope parameter.

out Options

You can specify the following options for the out parameter:

Output to a Collection

This option outputs to a new collection, and is not available on secondary members of replica sets.

out: <collectionName>

Output to a Collection with an Action

This option is only available when passing a collection that already exists to out. It is not available on secondary members of replica sets.

out: { <action>: <collectionName>
        [, db: <dbName>]
        [, sharded: <boolean> ]
        [, nonAtomic: <boolean> ] }

When you output to a collection with an action, the out has the following parameters:

<action>: Specify one of the following actions:

replace

Replace the contents of the <collectionName> if the collection with the <collectionName> exists.

merge

Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, overwrite that existing document.

reduce

Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, apply the reduce function to both the new and the existing documents and overwrite the existing document with the result.

db:

Optional. The name of the database that you want the map-reduce operation to write its output. By default this will be the same database as the input collection.

sharded:

Optional. If true and you have enabled sharding on output database, the map-reduce operation will shard the output collection using the _id field as the shard key.

nonAtomic:

New in version 2.2.

Optional. Specify output operation as non-atomic. This applies only to the merge and reduce output modes, which may take minutes to execute.

By default nonAtomic is false, and the map-reduce operation locks the database during post-processing.

If nonAtomic is true, the post-processing step prevents MongoDB from locking the database: during this time, other clients will be able to read intermediate states of the output collection.

Output Inline

Perform the map-reduce operation in memory and return the result. This option is the only available option for out on secondary members of replica sets.

out: { inline: 1 }

The result must fit within the maximum size of a BSON document.

Map-Reduce Examples

In the mongo shell, the db.collection.mapReduce() method is a wrapper around the mapReduce command. The following examples use the db.collection.mapReduce() method:

Consider the following map-reduce operations on a collection orders that contains documents of the following prototype:

{
     _id: ObjectId("50a8240b927d5d8b5891743c"),
     cust_id: "abc123",
     ord_date: new Date("Oct 04, 2012"),
     status: 'A',
     price: 25,
     items: [ { sku: "mmm", qty: 5, price: 2.5 },
              { sku: "nnn", qty: 5, price: 2.5 } ]
}

Return the Total Price Per Customer

Perform the map-reduce operation on the orders collection to group by the cust_id, and calculate the sum of the price for each cust_id:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

The function maps the price to the cust_id for each document and emits the cust_id and price pair.

var mapFunction1 = function() {
                       emit(this.cust_id, this.price);
                   };

Define the corresponding reduce function with two arguments keyCustId and valuesPrices:

The valuesPrices is an array whose elements are the price values emitted by the map function and grouped by keyCustId.

The function reduces the valuesPrice array to the sum of its elements.

var reduceFunction1 = function(keyCustId, valuesPrices) {
                          return Array.sum(valuesPrices);
                      };

Perform the map-reduce on all documents in the orders collection using the mapFunction1 map function and the reduceFunction1 reduce function.

db.orders.mapReduce(
                     mapFunction1,
                     reduceFunction1,
                     { out: "map_reduce_example" }
                   )

This operation outputs the results to a collection named map_reduce_example. If the map_reduce_example collection already exists, the operation will replace the contents with the results of this map-reduce operation:

Calculate Order and Total Quantity with Average Quantity Per Item

In this example, you will perform a map-reduce operation on the orders collection for all documents that have an ord_date value greater than 01/01/2012. The operation groups by the item.sku field, and calculates the number of orders and the total quantity ordered for each sku. The operation concludes by calculating the average quantity per order for each sku value:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

For each item, the function associates the sku with a new object value that contains the count of 1 and the item qty for the order and emits the sku and value pair.

var mapFunction2 = function() {
                       for (var idx = 0; idx < this.items.length; idx++) {
                           var key = this.items[idx].sku;
                           var value = {
                                         count: 1,
                                         qty: this.items[idx].qty
                                       };
                           emit(key, value);
                       }
                    };

Define the corresponding reduce function with two arguments keySKU and countObjVals:

countObjVals is an array whose elements are the objects mapped to the grouped keySKU values passed by map function to the reducer function.

The function reduces the countObjVals array to a single object reducedValue that contains the count and the qty fields.

In reducedVal, the count field contains the sum of the count fields from the individual array elements, and the qty field contains the sum of the qty fields from the individual array elements.

var reduceFunction2 = function(keySKU, countObjVals) {
                     reducedVal = { count: 0, qty: 0 };

                     for (var idx = 0; idx < countObjVals.length; idx++) {
                         reducedVal.count += countObjVals[idx].count;
                         reducedVal.qty += countObjVals[idx].qty;
                     }

                     return reducedVal;
                  };

Define a finalize function with two arguments key and reducedVal. The function modifies the reducedVal object to add a computed field named avg and returns the modified object:

var finalizeFunction2 = function (key, reducedVal) {

                       reducedVal.avg = reducedVal.qty/reducedVal.count;

                       return reducedVal;

                    };

Perform the map-reduce operation on the orders collection using the mapFunction2, reduceFunction2, and finalizeFunction2 functions.

db.orders.mapReduce( mapFunction2,
                     reduceFunction2,
                     {
                       out: { merge: "map_reduce_example" },
                       query: { ord_date:
                                  { $gt: new Date('01/01/2012') }
                              },
                       finalize: finalizeFunction2
                     }
                   )

This operation uses the query field to select only those documents with ord_date greater than new Date(01/01/2012). Then it output the results to a collection map_reduce_example. If the map_reduce_example collection already exists, the operation will merge the existing contents with the results of this map-reduce operation.

For more information and examples, see the Map-Reduce page and Perform Incremental Map-Reduce.

Output

If you set the out parameter to write the results to a collection, the mapReduce command returns a document in the following form:

{
    "result" : <string or document>,
    "timeMillis" : <int>,
    "counts" : {
        "input" : <int>,
        "emit" : <int>,
        "reduce" : <int>,
        "output" : <int>
    },
    "ok" : <int>,
}

If you set the out parameter to output the results inline, the mapReduce command returns a document in the following form:

{
    "results" : [
       {
          "_id" : <key>,
          "value" :<reduced or finalizedValue for key>
       },
       ...
    ],
    "timeMillis" : <int>,
    "counts" : {
       "input" : <int>,
       "emit" : <int>,
       "reduce" : <int>,
       "output" : <int>
    },
    "ok" : <int>
}

mapReduce.result

For output sent to a collection, this value is either:

a string for the collection name if out did not specify the database name, or

a document with both db and collection fields if out specified both a database and collection name.

mapReduce.results

For output written inline, an array of resulting documents. Each resulting document contains two fields:

_id field contains the key value,

value field contains the reduced or finalized value for the associated key.

mapReduce.timeMillis

The command execution time in milliseconds.

mapReduce.counts

Various count statistics from the mapReduce command.

mapReduce.counts.input

The number of documents the mapReduce command called the map function.

mapReduce.counts.emit

The number of times the mapReduce command called the emit function.

mapReduce.counts.reduce

The number of times the mapReduce command called the reduce function.

mapReduce.counts.output

The number of output values produced.

mapReduce.ok

A value of 1 indicates the mapReduce command ran successfully. A value of 0 indicates an error.

Additional Information

Troubleshoot the Map Function

Troubleshoot the Reduce Function

db.collection.mapReduce()

Aggregation Concepts

Geospatial Commands

Name | Description
geoNear | Performs a geospatial query that returns the documents closest to a given point.
geoSearch | Performs a geospatial query that uses MongoDB’s haystack index functionality.
geoWalk | An internal command to support geospatial queries.

geoNear

geoSearch

geoWalk

geoNear

Definition

geoNear

Returns documents in order of proximity to a specified point, from the nearest to farthest. geoNear requires a geospatial index.

The geoNear command accepts a document that contains the following fields. Specify all distances in the same units as the document coordinate system:

Field
Description

geoNear
The collection to query.

near

The point for which to find the closest documents.

If using a 2dsphere index, you can specify the point as either a GeoJSON point or legacy coordinate pair.

If using a 2d index, specify the point as a legacy coordinate pair.

spherical

Required if using a 2dsphere index. Determines how MongoDB calculates the distance. The default value is false.

If true, then MongoDB uses spherical geometry to calculate distances in meters if the specified (near) point is a GeoJSON point and in radians if the specified (near) point is a legacy coordinate pair.

If false, then MongoDB uses 2d planar geometry to calculate distance between points.

If using a 2dsphere index, spherical must be true.

limit
Optional. The maximum number of documents to return. The default value is 100. See also the num option.

num
Optional. The num option provides the same function as the limit option. Both define the maximum number of documents to return. If both options are included, the num value overrides the limit value.

minDistance

Optional. The minimum distance from the center point that the documents must be. MongoDB filters the results to those documents that are at least the specified distance from the center point.

Only available for use with 2dsphere index.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

New in version 2.6.

maxDistance

Optional. The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

query

Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax.

You cannot specify a $near predicate in the query field of the geoNear command.

distanceMultiplier
Optional. The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.

includeLocs
Optional. If this is true, the query returns the location of the matching documents in the results. The default is false. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.

uniqueDocs

Optional. If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query.

Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.

field string geoNear:

The collection to query.

:field GeoJSON point, legacy coordinate pair near:

The point for which to find the closest documents.

If using a 2dsphere index, you can specify the point as either a GeoJSON point or legacy coordinate pair.

If using a 2d index, specify the point as a legacy coordinate pair.

field Boolean spherical:

Required if using a 2dsphere index. Determines how MongoDB calculates the distance. The default value is false.

If true, then MongoDB uses spherical geometry to calculate distances in meters if the specified (near) point is a GeoJSON point and in radians if the specified (near) point is a legacy coordinate pair.

If false, then MongoDB uses 2d planar geometry to calculate distance between points.

If using a 2dsphere index, spherical must be true.

field number limit:

Optional. The maximum number of documents to return. The default value is 100. See also the num option.

field number num:

Optional. The num option provides the same function as the limit option. Both define the maximum number of documents to return. If both options are included, the num value overrides the limit value.

field number minDistance:

Optional. The minimum distance from the center point that the documents must be. MongoDB filters the results to those documents that are at least the specified distance from the center point.

Only available for use with 2dsphere index.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

New in version 2.6.

field number maxDistance:

Optional. The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point.

Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.

field document query:

Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax.

You cannot specify a $near predicate in the query field of the geoNear command.

field number distanceMultiplier:

Optional. The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.

field Boolean includeLocs:

Optional. If this is true, the query returns the location of the matching documents in the results. The default is false. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.

field Boolean uniqueDocs:

Optional. If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query.

Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.

Considerations

geoNear requires a geospatial index. However, the geoNear command requires that a collection have at most only one 2d index and/or only one 2dsphere.

Queries that use a 2d index return a limit of 100 documents.

You cannot specify a $near predicate in the query field of the geoNear command.

Command Syntax

2dsphere Index

If using a 2dsphere index, you can specify either a GeoJSON point or a legacy coordinate pair for the near value.

You must include spherical: true in the syntax.

With spherical: true, if you specify a GeoJSON point, MongoDB uses meters as the unit of measurement:

db.runCommand( {
   geoNear: <collection> ,
   near: { type: "Point" , coordinates: [ <coordinates> ] } ,
   spherical: true,
   ...
} )

With spherical: true, if you specify a legacy coordinate pair, MongoDB uses radians as the unit of measurement:

db.runCommand( {
   geoNear: <collection> ,
   near: [ <coordinates> ],
   spherical: true,
   ...
} )

2d Index

To query a 2d index, use the following syntax:

db.runCommand( {
   geoNear: <collection>,
   near : [ <coordinates> ],
   ...
} )

If you specify spherical: true, MongoDB uses spherical geometry to calculate distances in radians. Otherwise, MongoDB uses planar geometry to calculate distances between points.

Behavior

geoNear always returns the documents sorted by distance. Any other sort order requires to sort the documents in memory, which can be inefficient. To return results in a different sort order, use the $geoWithin operator and the sort() method.

Because geoNear orders the documents from nearest to farthest, the minDistance field effectively skips over the first n documents where n is determined by the distance requirement.

The geoNear command provides an alternative to the $near operator. In addition to the functionality of $near, geoNear returns additional diagnostic information.

Examples

The following examples run the geoNear command on the collection places that has a 2dsphere index.

Specify a Query Condition

The following geoNear command queries for documents whose category equals "public" and returns the matching documents in order of nearest to farthest to the specified point:

db.runCommand(
   {
     geoNear: "places",
     near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
     spherical: true,
     query: { category: "public" }
   }
)

The operation returns the following output, the documents in the results from nearest to farthest:

{
  "results" : [
     {
       "dis" : 0,
       "obj" : {
          "_id" : 2,
          "location" : { "type" : "Point", "coordinates" : [ -73.9667, 40.78 ] },
          "name" : "Central Park",
          "category" : "public"
       }
     },
     {
       "dis" : 3245.988787957091,
       "obj" : {
          "_id" : 3,
          "location" : { "type" : "Point", "coordinates" : [ -73.9836, 40.7538 ] },
          "name" : "Bryant Park",
          "category" : "public"
       }
     },
     {
       "dis" : 7106.506152782733,
       "obj" : {
          "_id" : 4,
          "location" : { "type" : "Point", "coordinates" : [ -73.9928, 40.7193 ] },
          "name" : "Sara D. Roosevelt Park",
          "category" : "public"
       }
     },

  ],
  "stats" : {
     "nscanned" : NumberLong(47),
     "objectsLoaded" : NumberLong(47),
     "avgDistance" : 3450.8316469132747,
     "maxDistance" : 7106.506152782733,
     "time" : 4
  },
  "ok" : 1
}

Specify a minDistance and maxDistance

The following example specifies a minDistance of 3000 meters and maxDistance of 7000 meters:

db.runCommand(
   {
     geoNear: "places",
     near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
     spherical: true,
     query: { category: "public" },
     minDistance: 3000,
     maxDistance: 7000
   }
)

The operation returns the following output:

{
  "results" : [
     {
       "dis" : 3245.988787957091,
       "obj" : {
          "_id" : 3,
          "location" : { "type" : "Point", "coordinates" : [ -73.9836, 40.7538 ] },
          "name" : "Bryant Park",
          "category" : "public"
       }
     }
  ],
  "stats" : {
      "nscanned" : NumberLong(11),
      "objectsLoaded" : NumberLong(11),
      "avgDistance" : 3245.988787957091,
      "maxDistance" : 3245.988787957091,
      "time" : 0
  },
  "ok" : 1
}

Output

The geoNear command returns a document with the following fields:

geoNear.results

An array with the results of the geoNear command, sorted by distance with the nearest result listed first and farthest last.

geoNear.results[n].dis

For each document in the results, the distance from the coordinates defined in the geoNear command.

geoNear.results[n].obj

The document from the collection.

geoNear.stats

An object with statistics about the query used to return the results of the geoNear search.

geoNear.stats.nscanned

The total number of index entries scanned during the database operation.

geoNear.stats.objectsLoaded

The total number of documents read from disk during the database operation.

geoNear.stats.avgDistance

The average distance between the coordinates defined in the geoNear command and coordinates of the documents returned as results.

geoNear.stats.maxDistance

The maximum distance between the coordinates defined in the geoNear command and coordinates of the documents returned as results.

geoNear.stats.time

The execution time of the database operation, in milliseconds.

geoNear.ok

A value of 1 indicates the geoNear search succeeded. A value of 0 indicates an error.

geoSearch

geoSearch

The geoSearch command provides an interface to MongoDB’s haystack index functionality. These indexes are useful for returning results based on location coordinates after collecting results based on some other query (i.e. a “haystack.”) Consider the following example:

{ geoSearch : "places", near : [33, 33], maxDistance : 6, search : { type : "restaurant" }, limit : 30 }

The above command returns all documents with a type of restaurant having a maximum distance of 6 units from the coordinates [30,33] in the collection places up to a maximum of 30 results.

Unless specified otherwise, the geoSearch command limits results to 50 documents.

Important

geoSearch is not supported for sharded clusters.

geoWalk

geoWalk

geoWalk is an internal command.

Query and Write Operation Commands

Name | Description
insert | Inserts one or more documents.
update | Updates one or more documents.
delete | Deletes one or more documents.
findAndModify | Returns and modifies a single document.
text | Performs a text search.
getLastError | Returns the success status of the last operation.
getPrevError | Returns status document containing all errors since the last resetError command.
resetError | Resets the last error status.
eval | Runs a JavaScript function on the database server.
parallelCollectionScan | Lets applications use multiple parallel cursors when reading documents from a collection.

insert

update

delete

findAndModify

text

getLastError

getPrevError

resetError

eval

parallelCollectionScan

insert

Definition

insert

New in version 2.6.

The insert command inserts one or more documents and returns a document containing the status of all inserts. The insert methods provided by the MongoDB drivers use this command internally.

The command has the following syntax:

{
   insert: <collection>,
   documents: [ <document>, <document>, <document>, ... ],
   ordered: <boolean>,
   writeConcern: { <write concern> }
}

The insert command takes the following fields:

Field | Description
insert | The name of the target collection.
documents | An array of one or more documents to insert into the named collection.
ordered | Optional. If true, then when an insert of a document fails, return without inserting any remaining documents listed in the inserts array. If false, then when an insert of a document fails, continue to insert the remaining documents. Defaults to true.
writeConcern | Optional. A document expressing the write concern of the insert command. Omit to use the default write concern.

field string insert:
| The name of the target collection.
field array documents:
| An array of one or more documents to insert into the named collection.
field boolean ordered:
| Optional. If true, then when an insert of a document fails, return without inserting any remaining documents listed in the inserts array. If false, then when an insert of a document fails, continue to insert the remaining documents. Defaults to true.
field document writeConcern:
| Optional. A document expressing the write concern of the insert command. Omit to use the default write concern.

Returns:
A document that contains the status of the operation. See Output for details.

Behavior

The total size of all the documents array elements must be less than or equal to the maximum BSON document size.

The total number of documents in the documents array must be less than or equal to the maximum bulk size.

Examples

Insert a Single Document

Insert a document into the users collection:

db.runCommand(
   {
      insert: "users",
      documents: [ { _id: 1, user: "abc123", status: "A" } ]
   }
)

The returned document shows that the command successfully inserted a document. See Output for details.

{ "ok" : 1, "n" : 1 }

Bulk Insert

Insert three documents into the users collection:

db.runCommand(
   {
      insert: "users",
      documents: [
         { _id: 2, user: "ijk123", status: "A" },
         { _id: 3, user: "xyz123", status: "P" },
         { _id: 4, user: "mop123", status: "P" }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command successfully inserted the three documents. See Output for details.

{ "ok" : 1, "n" : 3 }

Output

The returned document contains a subset of the following fields:

insert.ok

The status of the command.

insert.n

The number of documents inserted.

insert.writeErrors

An array of documents that contains information regarding any error encountered during the insert operation. The writeErrors array contains an error document for each insert that errors.

Each error document contains the following fields:

insert.writeErrors.index

An integer that identifies the document in the documents array, which uses a zero-based index.

insert.writeErrors.code

An integer value identifying the error.

insert.writeErrors.errmsg

A description of the error.

insert.writeConcernError

Document that describe error related to write concern and contains the field:

insert.writeConcernError.code

An integer value identifying the cause of the write concern error.

insert.writeConcernError.errmsg

A description of the cause of the write concern error.

The following is an example document returned for a successful insert of a single document:

{ ok: 1, n: 1 }

The following is an example document returned for an insert of two documents that successfully inserted one document but encountered an error with the other document:

{
   "ok" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
      }
   ]
}

update

Definition

update

New in version 2.6.

The update command modifies documents in a collection. A single update command can contain multiple update statements. The update methods provided by the MongoDB drivers use this command internally.

The update command has the following syntax:

{
   update: <collection>,
   updates:
      [
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean> },
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean> },
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean> },
         ...
      ],
   ordered: <boolean>,
   writeConcern: { <write concern> }
}

The command takes the following fields:

Field | Description
update | The name of the target collection.
updates | An array of one or more update statements to perform in the named collection.
ordered | Optional. If true, then when an update statement fails, return without performing the remaining update statements. If false, then when an update fails, continue with the remaining update statements, if any. Defaults to true.
writeConcern | Optional. A document expressing the write concern of the update command. Omit to use the default write concern.

field string update:
| The name of the target collection.
field array updates:
| An array of one or more update statements to perform in the named collection.
field boolean ordered:
| Optional. If true, then when an update statement fails, return without performing the remaining update statements. If false, then when an update fails, continue with the remaining update statements, if any. Defaults to true.
field document writeConcern:
| Optional. A document expressing the write concern of the update command. Omit to use the default write concern.

Each element of the updates array contains the following fields:

Field | Description
q | The query that matches documents to update. Use the same query selectors as used in the find() method.
u | The modifications to apply. For details, see Behaviors.
upsert | Optional. If true, perform an insert if no documents match the query. If both upsert and multi are true and no documents match the query, the update operation inserts only a single document.
multi | Optional. If true, updates all documents that meet the query criteria. If false, limit the update to one document that meet the query criteria. Defaults to false.

field document q:
| The query that matches documents to update. Use the same query selectors as used in the find() method.
field document u:
| The modifications to apply. For details, see Behaviors.
field boolean upsert:
| Optional. If true, perform an insert if no documents match the query. If both upsert and multi are true and no documents match the query, the update operation inserts only a single document.
field boolean multi:
| Optional. If true, updates all documents that meet the query criteria. If false, limit the update to one document that meet the query criteria. Defaults to false.

Returns:
A document that contains the status of the operation. See Output for details.

Behaviors

The <update> document can contain either all update operator expressions or all field:value expressions.

Update Operator Expressions

If the <update> document contains all update operator expressions, as in:

{
  $set: { status: "D" },
  $inc: { quantity: 2 }
}

Then, the update command updates only the corresponding fields in the document.

Field: Value Expressions

If the <update> document contains only field:value expressions, as in:

{
  status: "D",
  quantity: 4
}

Then the update command replaces the matching document with the update document. The update command can only replace a single matching document; i.e. the multi field cannot be true. The update command does not replace the _id value.

Limits

For each update element in the updates array, the sum of the query and the update sizes (i.e. q and u ) must be less than or equal to the maximum BSON document size.

The total number of update statements in the updates array must be less than or equal to the maximum bulk size.

Examples

Update Specific Fields of One Document

Use update operators to update only the specified fields of a document.

For example, given a users collection, the following command uses the $set and $inc operators to modify the status and the points fields respectively of a document where the user equals "abc123":

db.runCommand(
   {
      update: "users",
      updates: [
         {
           q: { user: "abc123" }, u: { $set: { status: "A" }, $inc: { points: 1 } }
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Because <update> document does not specify the optional multi field, the update only modifies one document, even if more than one document matches the q match condition.

The returned document shows that the command found and updated a single document. See Output for details.

{ "ok" : 1, "nModified" : 1, "n" : 1 }

Update Specific Fields of Multiple Documents

Use update operators to update only the specified fields of a document, and include the multi field set to true in the update statement.

For example, given a users collection, the following command uses the $set and $inc operators to modify the status and the points fields respectively of all documents in the collection:

db.runCommand(
   {
      update: "users",
      updates: [
         { q: { }, u: { $set: { status: "A" }, $inc: { points: 1 } }, multi: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The update modifies all documents that match the query specified in the q field, namely the empty query which matches all documents in the collection.

The returned document shows that the command found and updated multiple documents. See Output for details.

{ "ok" : 1, "nModified" : 100, "n" : 100 }

Bulk Update

The following example performs multiple update operations on the users collection:

db.runCommand(
   {
      update: "users",
      updates: [
         { q: { status: "P" }, u: { $set: { status: "D" } }, multi: true },
         { q: { _id: 5 }, u: { _id: 5, name: "abc123", status: "A" }, upsert: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command modified 10 documents and inserted a document with the _id value 5. See Output for details.

{
   "ok" : 1,
   "nModified" : 10,
   "n" : 11,
   "upserted" : [
      {
         "index" : 1,
         "_id" : 5
      }
   ]
}

Output

The returned document contains a subset of the following fields:

update.ok

The status of the command.

update.n

The number of documents selected for update. If the update operation results in no change to the document, e.g. $set expression updates the value to the current value, n can be greater than nModified.

update.nModified

The number of documents updated. If the update operation results in no change to the document, such as setting the value of the field to its current value, nModified can be less than n.

update.upserted

An array of documents that contains information for each document inserted through the update with upsert: true.

Each document contains the following information:

update.upserted.index

An integer that identifies the update with upsert:true statement in the updates array, which uses a zero-based index.

update.upserted._id

The _id value of the added document.

update.writeErrors

An array of documents that contains information regarding any error encountered during the update operation. The writeErrors array contains an error document for each update statement that errors.

Each error document contains the following fields:

update.writeErrors.index

An integer that identifies the update statement in the updates array, which uses a zero-based index.

update.writeErrors.code

An integer value identifying the error.

update.writeErrors.errmsg

A description of the error.

update.writeConcernError

Document that describe error related to write concern and contains the field:

update.writeConcernError.code

An integer value identifying the cause of the write concern error.

update.writeConcernError.errmsg

A description of the cause of the write concern error.

The following is an example document returned for a successful update command that performed an upsert:

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

The following is an example document returned for a bulk update involving three update statements, where one update statement was successful and two other update statements encountered errors:

{
   "ok" : 1,
   "nModified" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 1.0} to {_id: 5.0}."
      },
      {
         "index" : 2,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 2.0} to {_id: 6.0}."
      },
   ]
}

delete

Definition

delete

New in version 2.6.

The delete command removes documents from a collection. A single delete command can contain multiple delete specifications. The command cannot operate on capped collections. The remove methods provided by the MongoDB drivers use this command internally.

The delete command has the following syntax:

{
   delete: <collection>,
   deletes: [
      { q : <query>, limit : <integer> },
      { q : <query>, limit : <integer> },
      { q : <query>, limit : <integer> },
      ...
   ],
   ordered: <boolean>,
   writeConcern: { <write concern> }
}

The command takes the following fields:

Field | Description
delete | The name of the target collection.
deletes | An array of one or more delete statements to perform in the named collection.
ordered | Optional. If true, then when a delete statement fails, return without performing the remaining delete statements. If false, then when a delete statement fails, continue with the remaining delete statements, if any. Defaults to true.
writeConcern | Optional. A document expressing the write concern of the delete command. Omit to use the default write concern.

field string delete:
| The name of the target collection.
field array deletes:
| An array of one or more delete statements to perform in the named collection.
field boolean ordered:
| Optional. If true, then when a delete statement fails, return without performing the remaining delete statements. If false, then when a delete statement fails, continue with the remaining delete statements, if any. Defaults to true.
field document writeConcern:
| Optional. A document expressing the write concern of the delete command. Omit to use the default write concern.

Each element of the deletes array contains the following fields:

Field | Description
q | The query that matches documents to delete.
limit | The number of matching documents to delete. Specify either a 0 to delete all matching documents or 1 to delete a single document.

field document q:
| The query that matches documents to delete.
field integer limit:
| The number of matching documents to delete. Specify either a 0 to delete all matching documents or 1 to delete a single document.

Returns:
A document that contains the status of the operation. See Output for details.

Behavior

The total size of all the queries (i.e. the q field values) in the deletes array must be less than or equal to the maximum BSON document size.

The total number of delete documents in the deletes array must be less than or equal to the maximum bulk size.

Examples

Limit the Number of Documents Deleted

The following example deletes from the orders collection one document that has the status equal to D by specifying the limit of 1:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { status: "D" }, limit: 1 } ]
   }
)

The returned document shows that the command deleted 1 document. See Output for details.

{ "ok" : 1, "n" : 1 }

Delete All Documents That Match a Condition

The following example deletes from the orders collection all documents that have the status equal to D by specifying the limit of 0:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { status: "D" }, limit: 0 } ],
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command found and deleted 13 documents. See Output for details.

{ "ok" : 1, "n" : 13 }

Delete All Documents from a Collection

Delete all documents in the orders collection by specifying an empty query condition and a limit of 0:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { }, limit: 0 } ],
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command found and deleted 35 documents in total. See Output for details.

{ "ok" : 1, "n" : 35 }

Bulk Delete

The following example performs multiple delete operations on the orders collection:

db.runCommand(
   {
      delete: "orders",
      deletes: [
         { q: { status: "D" }, limit: 0 },
         { q: { cust_num: 99999, item: "abc123", status: "A" }, limit: 1 }
      ],
      ordered: false,
      writeConcern: { w: 1 }
   }
)

The returned document shows that the command found and deleted 21 documents in total for the two delete statements. See Output for details.

{ "ok" : 1, "n" : 21 }

Output

The returned document contains a subset of the following fields:

delete.ok

The status of the command.

delete.n

The number of documents deleted.

delete.writeErrors

An array of documents that contains information regarding any error encountered during the delete operation. The writeErrors array contains an error document for each delete statement that errors.

Each error document contains the following information:

delete.writeErrors.index

An integer that identifies the delete statement in the deletes array, which uses a zero-based index.

delete.writeErrors.code

An integer value identifying the error.

delete.writeErrors.errmsg

A description of the error.

delete.writeConcernError

Document that describe error related to write concern and contains the field:

delete.writeConcernError.code

An integer value identifying the cause of the write concern error.

delete.writeConcernError.errmsg

A description of the cause of the write concern error.

The following is an example document returned for a successful delete command:

{ ok: 1, n: 1 }

The following is an example document returned for a delete command that encountered an error:

{
   "ok" : 1,
   "n" : 0,
   "writeErrors" : [
      {
         "index" : 0,
         "code" : 10101,
         "errmsg" : "can't remove from a capped collection: test.cappedLog"
      }
   ]
}

findAndModify

Definition

findAndModify

The findAndModify command modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the new option.

The command has the following syntax:

{
  findAndModify: <collection-name>,
  query: <document>,
  sort: <document>,
  remove: <boolean>,
  update: <document>,
  new: <boolean>,
  fields: <document>,
  upsert: <boolean>
}

The findAndModify command takes the following fields:

Field
Description

query
Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify will only select one document to modify.

sort
Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify modifies the first document in the sort order specified by this argument.

remove
Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.

update
Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.

new
Optional. When true, returns the modified document rather than the original. The findAndModify method ignores the new option for remove operations. The default is false.

fields
Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { <field1>: 1, <field2>: 1, ... }. See projection.

upsert

Optional. Used in conjunction with the update field.

When true, findAndModify creates a new document if no document matches the query, or if documents match the query, findAndModify performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed.

The default is false.

findAndModify
The collection against which to run the command.

field document query:

Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify will only select one document to modify.

field document sort:

Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify modifies the first document in the sort order specified by this argument.

field Boolean remove:

Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.

field document update:

Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.

field Boolean new:

Optional. When true, returns the modified document rather than the original. The findAndModify method ignores the new option for remove operations. The default is false.

field document fields:

Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { <field1>: 1, <field2>: 1, ... }. See projection.

field Boolean upsert:

Optional. Used in conjunction with the update field.

When true, findAndModify creates a new document if no document matches the query, or if documents match the query, findAndModify performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed.

The default is false.

field string findAndModify:

The collection against which to run the command.

Output

The return document contains the following fields:

The lastErrorObject field that returns the details of the command:

The updatedExisting field only appears if the command specifies an update or an update with upsert: true; i.e. the field does not appear for a remove.

The upserted field only appears if the update with the upsert: true operation results in an insertion.

The value field that returns either:

the original (i.e. pre-modification) document if new is false, or

the modified or inserted document if new: true.

The ok field that returns the status of the command.

Note

If the findAndModify finds no matching document, then:

for update or remove operations, lastErrorObject does not appear in the return document and the value field holds a null.

{ "value" : null, "ok" : 1 }

for update with upsert: true operation that results in an insertion, if the command also specifies new is false and specifies a sort, the return document has a lastErrorObject, value, and ok fields, but the value field holds an empty document {}.

for update with upsert: true operation that results in an insertion, if the command also specifies new is false but does not specify a sort, the return document has a lastErrorObject, value, and ok fields, but the value field holds a null.

Behavior

Upsert and Unique Index

When the findAndModify command includes the upsert: true option and the query field(s) is not uniquely indexed, the command could insert a document multiple times in certain circumstances.

Consider an example where no document with the name Andy exists and multiple clients issue the following command:

db.runCommand(
   {
     findAndModify: "people",
     query: { name: "Andy" },
     sort: { rating: 1 },
     update: { $inc: { score: 1 } },
     upsert: true
   }
 )

If all the commands finish the query phase before any command starts the modify phase, and there is no unique index on the name field, the commands may each perform an upsert, creating multiple duplicate documents.

To prevent the creation of multiple duplicate documents, create a unique index on the name field. With the unique index in place, then the multiple findAndModify commands will exhibit one of the following behaviors:

Exactly one findAndModify successfully inserts a new document.

Zero or more findAndModify commands update the newly inserted document.

Zero or more findAndModify commands fail when they attempt to insert a duplicate. If the command fails due to a unique index constraint violation, you can retry the command. Absent a delete of the document, the retry should not fail.

Sharded Collections

When using findAndModify in a sharded environment, the query must contain the shard key for all operations against the shard cluster. findAndModify operations issued against mongos instances for non-sharded collections function normally.

Concurrency

This command obtains a write lock on the affected database and will block other operations until it has completed; however, typically the write lock is short lived and equivalent to other similar update() operations.

Comparisons with the update Method

When updating a document, findAndModify and the update() method operate differently:

By default, both operations modify a single document. However, the update() method with its multi option can modify more than one document.

If multiple documents match the update criteria, for findAndModify, you can specify a sort to provide some measure of control on which document to update.

With the default behavior of the update() method, you cannot specify which single document to update when multiple documents match.

By default, findAndModify method returns an object that contains the pre-modified version of the document, as well as the status of the operation. To obtain the updated document, use the new option.

The update() method returns a WriteResult object that contains the status of the operation. To return the updated document, use the find() method. However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.

You cannot specify a write concern to findAndModify to override the default write concern whereas, starting in MongoDB 2.6, you can specify a write concern to the update() method.

When modifying a single document, both findAndModify and the update() method atomically update the document. See Atomicity and Transactions for more details about interactions and order of operations of these methods.

Examples

Update and Return

The following command updates an existing document in the people collection where the document matches the query criteria:

db.runCommand(
   {
     findAndModify: "people",
     query: { name: "Tom", state: "active", rating: { $gt: 10 } },
     sort: { rating: 1 },
     update: { $inc: { score: 1 } }
   }
)

This command performs the following actions:

The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.

The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the command will select for modification the first document as ordered by this sort.

The update increments the value of the score field by 1.

The command returns a document with the following fields:

The lastErrorObject field that contains the details of the command, including the field updatedExisting which is true, and

The value field that contains the original (i.e. pre-modification) document selected for this update:

{
  "lastErrorObject" : {
     "updatedExisting" : true,
     "n" : 1,
     "connectionId" : 1,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("50f1d54e9beb36a0f45c6452"),
     "name" : "Tom",
     "state" : "active",
     "rating" : 100,
     "score" : 5
  },
  "ok" : 1
}

To return the modified document in the value field, add the new:true option to the command.

If no document match the query condition, the command returns a document that contains null in the value field:

{ "value" : null, "ok" : 1 }

The mongo shell and many drivers provide a findAndModify() helper method. Using the shell helper, this previous operation can take the following form:

db.people.findAndModify( {
   query: { name: "Tom", state: "active", rating: { $gt: 10 } },
   sort: { rating: 1 },
   update: { $inc: { score: 1 } }
} );

However, the findAndModify() shell helper method returns only the unmodified document, or if new is true, the modified document.

{
   "_id" : ObjectId("50f1d54e9beb36a0f45c6452"),
   "name" : "Tom",
   "state" : "active",
   "rating" : 100,
   "score" : 5
}

upsert: true

The following findAndModify command includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:

db.runCommand(
               {
                 findAndModify: "people",
                 query: { name: "Gus", state: "active", rating: 100 },
                 sort: { rating: 1 },
                 update: { $inc: { score: 1 } },
                 upsert: true
               }
             )

If the command finds a matching document, the command performs an update.

If the command does not find a matching document, the update with upsert: true operation results in an insertion and returns a document with the following fields:

The lastErrorObject field that contains the details of the command, including the field upserted that contains the ObjectId of the newly inserted document, and

The value field that contains an empty document {} as the original document because the command included the sort option:

{
  "lastErrorObject" : {
     "updatedExisting" : false,
     "upserted" : ObjectId("50f2329d0092b46dae1dc98e"),
     "n" : 1,
     "connectionId" : 1,
     "err" : null,
     "ok" : 1
  },
  "value" : {

  },
  "ok" : 1
}

If the command did not include the sort option, the value field would contain null:

{
  "value" : null,
  "lastErrorObject" : {
     "updatedExisting" : false,
     "n" : 1,
     "upserted" : ObjectId("5102f7540cb5c8be998c2e99")
  },
  "ok" : 1
}

Return New Document

The following findAndModify command includes both upsert: true option and the new:true option. The command either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.

In the following example, no document in the people collection matches the query condition:

db.runCommand(
   {
     findAndModify: "people",
     query: { name: "Pascal", state: "active", rating: 25 },
     sort: { rating: 1 },
     update: { $inc: { score: 1 } },
     upsert: true,
     new: true
   }
)

The command returns the newly inserted document in the value field:

{
  "lastErrorObject" : {
     "updatedExisting" : false,
     "upserted" : ObjectId("50f47909444c11ac2448a5ce"),
     "n" : 1,
     "connectionId" : 1,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("50f47909444c11ac2448a5ce"),
     "name" : "Pascal",
     "rating" : 25,
     "score" : 1,
     "state" : "active"
  },
  "ok" : 1
}

text

Definition

text

Deprecated since version 2.6: Use $text query operator instead.

For document on the text, refer to the 2.4 Manual 2.4 Manual [http://docs.mongodb.org/v2.4/reference/command/text].

getLastError

Definition

getLastError

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations, eliminating the need for a separate getLastError command. Write methods now return the status of the write operation, including error information.

In previous versions, clients typically used the getLastError command in combination with the write operations to ensure that the write succeeds.

Returns the error status of the preceding write operation on the current connection.

getLastError uses the following prototype form:

{ getLastError: 1 }

getLastError uses the following fields:

Field
Description

j
If true, wait for the next journal commit before returning, rather than waiting for a full disk flush. If mongod does not have journaling enabled, this option has no effect. If this option is enabled for a write operation, mongod will wait no more than 1/3 of the current commitIntervalMs before writing data to the journal.

w
When running with replication, this is the number of servers to replicate to before returning. A w value of 1 indicates the primary only. A w value of 2 includes the primary and at least one secondary, etc. In place of a number, you may also set w to majority to indicate that the command should wait until the latest write propagates to a majority of replica set members. If using w, you should also use wtimeout. Specifying a value for w without also providing a wtimeout may cause getLastError to block indefinitely.

fsync
If true, wait for mongod to write this data to disk before returning. Defaults to false. In most cases, use the j option to ensure durability and consistency of the data set.

wtimeout
Optional. Milliseconds. Specify a value in milliseconds to control how long to wait for write propagation to complete. If replication does not complete in the given timeframe, the getLastError command will return with an error status.

field Boolean j:

If true, wait for the next journal commit before returning, rather than waiting for a full disk flush. If mongod does not have journaling enabled, this option has no effect. If this option is enabled for a write operation, mongod will wait no more than 1/3 of the current commitIntervalMs before writing data to the journal.

field integer, string w:

When running with replication, this is the number of servers to replicate to before returning. A w value of 1 indicates the primary only. A w value of 2 includes the primary and at least one secondary, etc. In place of a number, you may also set w to majority to indicate that the command should wait until the latest write propagates to a majority of replica set members. If using w, you should also use wtimeout. Specifying a value for w without also providing a wtimeout may cause getLastError to block indefinitely.

field Boolean fsync:

If true, wait for mongod to write this data to disk before returning. Defaults to false. In most cases, use the j option to ensure durability and consistency of the data set.

field integer wtimeout:

Optional. Milliseconds. Specify a value in milliseconds to control how long to wait for write propagation to complete. If replication does not complete in the given timeframe, the getLastError command will return with an error status.

See also

Write Concern, Write Concern Reference, and Replica Acknowledged.

Output

Each getLastError() command returns a document containing a subset of the fields listed below.

getLastError.ok

ok is true when the getLastError command completes successfully.

Note

A value of true does not indicate that the preceding operation did not produce an error.

getLastError.err

err is null unless an error occurs. When there was an error with the preceding operation, err contains a textual description of the error.

getLastError.code

code reports the preceding operation’s error code.

getLastError.connectionId

The identifier of the connection.

getLastError.lastOp

When issued against a replica set member and the preceding operation was a write or update, lastOp is the optime timestamp in the oplog of the change.

getLastError.n

n reports the number of documents updated or removed, if the preceding operation was an update or remove operation.

getLastError.shards

When issued against a sharded cluster after a write operation, shards identifies the shards targeted in the write operation. shards is present in the output only if the write operation targets multiple shards.

getLastError.singleShard

When issued against a sharded cluster after a write operation, identifies the shard targeted in the write operation. singleShard is only present if the write operation targets exactly one shard.

getLastError.updatedExisting

updatedExisting is true when an update affects at least one document and does not result in an upsert.

getLastError.upserted

If the update results in an insert, upserted is the value of _id field of the document.

Changed in version 2.6: Earlier versions of MongoDB included upserted only if _id was an ObjectId.

getLastError.wnote

If set, wnote indicates that the preceding operation’s error relates to using the w parameter to getLastError.

See

Write Concern Reference for more information about w values.

getLastError.wtimeout

wtimeout is true if the getLastError timed out because of the wtimeout setting to getLastError.

getLastError.waited

If the preceding operation specified a timeout using the wtimeout setting to getLastError, then waited reports the number of milliseconds getLastError waited before timing out.

getLastError.wtime

getLastError.wtime is the number of milliseconds spent waiting for the preceding operation to complete. If getLastError timed out, wtime and getLastError.waited are equal.

Examples

Confirm Replication to Two Replica Set Members

The following example ensures the operation has replicated to two members (the primary and one other member):

db.runCommand( { getLastError: 1, w: 2 } )

Confirm Replication to a Majority of a Replica Set

The following example ensures the write operation has replicated to a majority of the configured members of the set.

db.runCommand( { getLastError: 1, w: "majority" } )

Changed in version 2.6: In Master/Slave deployments, MongoDB treats w: "majority" as equivalent to w: 1. In earlier versions of MongoDB, w: "majority" produces an error in master/slave deployments.

Set a Timeout for a getLastError Response

Unless you specify a timeout, a getLastError command may block forever if MongoDB cannot satisfy the requested write concern. To specify a timeout of 5000 milliseconds, use an invocation that resembles the following:

db.runCommand( { getLastError: 1, w: 2, wtimeout:5000 } )

When wtimeout is 0, the getLastError operation will never time out.

getPrevError

getPrevError

The getPrevError command returns the errors since the last resetError command.

See also

db.getPrevError()

resetError

resetError

The resetError command resets the last error status.

See also

db.resetError()

eval

eval

The eval command evaluates JavaScript functions on the database server.

The eval command has the following form:

{
  eval: <function>,
  args: [ <arg1>, <arg2> ... ],
  nolock: <boolean>
}

The command contains the following fields:

Field
Description

eval
A JavaScript function.

args
Optional. An array of arguments to pass to the JavaScript function. Omit if the function does not take arguments.

nolock
Optional. By default, eval takes a global write lock before evaluating the JavaScript function. As a result, eval blocks all other read and write operations to the database while the eval operation runs. Set nolock to true on the eval command to prevent the eval command from taking the global write lock before evaluating the JavaScript. nolock does not impact whether operations within the JavaScript code itself takes a write lock.

field function eval:

A JavaScript function.

field array args:

Optional. An array of arguments to pass to the JavaScript function. Omit if the function does not take arguments.

field boolean nolock:

Optional. By default, eval takes a global write lock before evaluating the JavaScript function. As a result, eval blocks all other read and write operations to the database while the eval operation runs. Set nolock to true on the eval command to prevent the eval command from taking the global write lock before evaluating the JavaScript. nolock does not impact whether operations within the JavaScript code itself takes a write lock.

JavaScript in MongoDB

Although eval uses JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

Behavior

Write Lock

By default, eval takes a global write lock while evaluating the JavaScript function. As a result, eval blocks all other read and write operations to the database while the eval operation runs.

To prevent the taking of the global write lock while evaluating the JavaScript code, use the eval command with nolock set to true. nolock does not impact whether the operations within the JavaScript code take write locks.

For long running eval operation, consider using either the eval command with nolock: true or using other server side code execution options.

Sharded Data

You can not use eval with sharded collections. In general, you should avoid using eval in sharded clusters; nevertheless, it is possible to use eval with non-sharded collections and databases stored in a sharded cluster.

Access Control

Changed in version 2.6.

If authorization is enabled, you must have access to all actions on all resources in order to run eval. Providing such access is not recommended, but if your organization requires a user to run eval, create a role that grants anyAction on anyResource. Do not assign this role to any other user.

JavaScript Engine

Changed in version 2.4.

The V8 JavaScript engine, which became the default in 2.4, allows multiple JavaScript operations to execute at the same time. Prior to 2.4, eval executed in a single thread.

Example

The following example uses eval to perform an increment and calculate the average on the server:

db.runCommand( {
      eval: function(name, incAmount) {
               var doc = db.myCollection.findOne( { name : name } );

               doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };

               doc.num++;
               doc.total += incAmount;
               doc.avg = doc.total / doc.num;

               db.myCollection.save( doc );
               return doc;
            },
      args: [ "eliot", 5 ]
   }
);

The db in the function refers to the current database.

The mongo shell provides a helper method db.eval() [1], so you can express the above as follows:

db.eval( function(name, incAmount) {
            var doc = db.myCollection.findOne( { name : name } );

            doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };

            doc.num++;
            doc.total += incAmount;
            doc.avg = doc.total / doc.num;

            db.myCollection.save( doc );
            return doc;
         },
         "eliot", 5 );

If you want to use the server’s interpreter, you must run eval. Otherwise, the mongo shell’s JavaScript interpreter evaluates functions entered directly into the shell.

If an error occurs, eval throws an exception. The following invalid function uses the variable x without declaring it as an argument:

db.runCommand(
               {
                 eval: function() { return x + x; },
                 args: [ 3 ]
               }
             )

The statement will result in the following exception:

{
   "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ",
   "code" : 16722,
   "ok" : 0
}

See also

Server-side JavaScript

[1]
The helper db.eval() in the mongo shell wraps the eval command. Therefore, the helper method shares the characteristics and behavior of the underlying command with one exception: db.eval() method does not support the nolock option.

parallelCollectionScan

parallelCollectionScan

New in version 2.6.

Allows applications to use multiple parallel cursors when reading all the documents from a collection, thereby increasing throughput. The parallelCollectionScan command returns a document that contains an array of cursor information.

Each cursor provides access to the return of a partial set of documents from a collection. Iterating each cursor returns every document in the collection. Cursors do not contain the results of the database command. The result of the database command identifies the cursors, but does not contain or constitute the cursors.

The server may return fewer cursors than requested.

The command has the following syntax:

{
  parallelCollectionScan: "<collection>",
  numCursors: <integer>
}

The parallelCollectionScan command takes the following fields:

Field | Description
parallelCollectionScan | The name of the collection.
numCursors | The maximum number of cursors to return. Must be between 1 and 10000, inclusive.

field string parallelCollectionScan:
| The name of the collection.
field integer numCursors:
| The maximum number of cursors to return. Must be between 1 and 10000, inclusive.

Output

The parallelCollectionScan command returns a document containing the array of cursor information:

{
    "cursors" : [
        {
            "cursor" : {
                "firstBatch" : [ ],
                "ns" : "<database name>.<collection name>",
                "id" : NumberLong("155949257847")
            },
            "ok" : true
        }
    ],
    "ok" : 1
}

parallelCollectionScan.cursors

An array with one or more cursors returned with the command.

parallelCollectionScan.cursors.cursor

For each cursor returned, a document with details about the cursor.

parallelCollectionScan.cursors.cursor.firstBatch

An empty first batch is useful for quickly returning a cursor or failure message without doing significant server-side work. See cursor batches.

parallelCollectionScan.cursors.cursor.ns

The namespace for each cursor.

parallelCollectionScan.cursors.cursor.id

The unique id for each cursor.

parallelCollectionScan.cursors.ok

The status of each cursor returned with the command.

parallelCollectionScan.ok

A value of 1 indicates the parallelCollectionScan command succeeded. A value of 0 indicates an error.

Query Plan Cache Commands

Name | Description
planCacheListFilters | Lists the index filters for a collection.
planCacheSetFilter | Sets an index filter for a collection.
planCacheClearFilters | Clears index filter(s) for a collection.
planCacheListQueryShapes | Displays the query shapes for which cached query plans exist.
planCacheListPlans | Displays the cached query plans for the specified query shape.
planCacheClear | Removes cached query plan(s) for a collection.

planCacheListFilters

planCacheSetFilter

planCacheClearFilters

planCacheListQueryShapes

planCacheListPlans

planCacheClear

planCacheListFilters

Definition

planCacheListFilters

New in version 2.6.

Lists the index filters associated with query shapes for a collection.

The command has the following syntax:

db.runCommand( { planCacheListFilters: <collection> } )

The planCacheListFilters command has the following field:

Field | Description
planCacheListFilters | The name of the collection.

field string planCacheListFilters:

The name of the collection.

Returns:
Document listing the index filters. See Output.

Required Access

A user must have access that includes the planCacheIndexFilter action.

Output

The planCacheListFilters command returns the document with the following form:

{
   "filters" : [
      {
         "query" : <query>
         "sort" : <sort>,
         "projection" : <projection>,
         "indexes" : [
            <index1>,
            ...
         ]
      },
      ...
   ],
   "ok" : 1
}

planCacheListFilters.filters

The array of documents that contain the index filter information.

Each document contains the following fields:

planCacheListFilters.filters.query

The query predicate associated with this filter. Although the query shows the specific values used to create the index filter, the values in the predicate are insignificant; i.e. query predicates cover similar queries that differ only in the values.

For instance, a query predicate of { "type": "electronics", "status" : "A" } covers the following query predicates:

{ type: "food", status: "A" }
{ type: "utensil", status: "D" }

Together with the sort and the projection, the query make up the query shape for the specified index filter.

planCacheListFilters.filters.sort

The sort associated with this filter. Can be an empty document.

Together with the query and the projection, the sort make up the query shape for the specified index filter.

planCacheListFilters.filters.projection

The projection associated with this filter. Can be an empty document.

Together with the query and the sort, the projection make up the query shape for the specified index filter.

planCacheListFilters.filters.indexes

The array of indexes for this query shape. To choose the optimal query plan, the query optimizer evaluates only the listed indexes and the collection scan.

planCacheListFilters.ok

The status of the command.

See also

planCacheClearFilters, planCacheSetFilter

planCacheSetFilter

Definition

planCacheSetFilter

New in version 2.6.

Set an index filter for a collection. If an index filter already exists for the query shape, the command overrides the previous index filter.

The command has the following syntax:

db.runCommand(
   {
      planCacheSetFilter: <collection>,
      query: <query>,
      sort: <sort>,
      projection: <projection>,
      indexes: [ <index1>, <index2>, ...]
   }
)

The planCacheSetFilter command has the following field:

Field
Description

planCacheSetFilter
The name of the collection.

query

The query predicate associated with the index filter. Together with the sort and the projection, the query predicate make up the query shape for the specified index filter.

Only the structure of the predicate, including the field names, are significant; the values in the query predicate are insignificant. As such, query predicates cover similar queries that differ only in the values.

sort
Optional. The sort associated with the filter. Together with the query and the projection, the sort make up the query shape for the specified index filter.

projection
Optional. The projection associated with the filter. Together with the query and the sort, the projection make up the query shape for the specified index filter.

indexes
An array of index specification documents that act as the index filter for the specified query shape. Because the query optimizer chooses among the collection scan and these indexes, if the indexes are non-existent, the optimizer will choose the collection scan.

field string planCacheSetFilter:

The name of the collection.

field document query:

The query predicate associated with the index filter. Together with the sort and the projection, the query predicate make up the query shape for the specified index filter.

Only the structure of the predicate, including the field names, are significant; the values in the query predicate are insignificant. As such, query predicates cover similar queries that differ only in the values.

field document sort:

Optional. The sort associated with the filter. Together with the query and the projection, the sort make up the query shape for the specified index filter.

field document projection:

Optional. The projection associated with the filter. Together with the query and the sort, the projection make up the query shape for the specified index filter.

field array indexes:

An array of index specification documents that act as the index filter for the specified query shape. Because the query optimizer chooses among the collection scan and these indexes, if the indexes are non-existent, the optimizer will choose the collection scan.

Index filters only exist for the duration of the server process and do not persist after shutdown; however, you can also clear existing index filters using the planCacheClearFilters command.

Required Access

A user must have access that includes the planCacheIndexFilter action.

Examples

The following example creates an index filter on the orders collection such that for queries that consists only of an equality match on the status field without any projection and sort, the query optimizer evaluates only the two specified indexes and the collection scan for the winning plan:

db.runCommand(
   {
      planCacheSetFilter: "orders",
      query: { status: "A" },
      indexes: [
         { cust_id: 1, status: 1 },
         { status: 1, order_date: -1 }
      ]
   }
)

In the query predicate, only the structure of the predicate, including the field names, are significant; the values are insignificant. As such, the created filter applies to the following operations:

db.orders.find( { status: "D" } )
db.orders.find( { status: "P" } )

To see whether MongoDB applied an index filter for a query, check the explain.filterSet field of the explain() output.

See also

planCacheClearFilters, planCacheListFilters

planCacheClearFilters

Definition

planCacheClearFilters

New in version 2.6.

Removes index filters on a collection. Although index filters only exist for the duration of the server process and do not persist after shutdown, you can also clear existing index filters with the planCacheClearFilters command.

Specify the query shape to remove a specific index filter. Omit the query shape to clear all index filters on a collection.

The command has the following syntax:

db.runCommand(
   {
      planCacheClearFilters: <collection>,
      query: <query pattern>,
      sort: <sort specification>,
      projection: <projection specification>
   }
)

The planCacheClearFilters command has the following field:

Field
Description

planCacheClearFilters
The name of the collection.

query

Optional. The query predicate associated with the filter to remove. If omitted, clears all filters from the collection.

The values in the query predicate are insignificant in determining the query shape, so the values used in the query need not match the values shown using planCacheListFilters.

sort
Optional. The sort associated with the filter to remove, if any.

projection
Optional. The projection associated with the filter to remove, if any.

field string planCacheClearFilters:

The name of the collection.

field document query:

Optional. The query predicate associated with the filter to remove. If omitted, clears all filters from the collection.

The values in the query predicate are insignificant in determining the query shape, so the values used in the query need not match the values shown using planCacheListFilters.

field document sort:

Optional. The sort associated with the filter to remove, if any.

field document projection:

Optional. The projection associated with the filter to remove, if any.

Required Access

A user must have access that includes the planCacheIndexFilter action.

Examples

Clear Specific Index Filter on Collection

The orders collection contains the following two filters:

{
  "query" : { "status" : "A" },
  "sort" : { "ord_date" : -1 },
  "projection" : { },
  "indexes" : [ { "status" : 1, "cust_id" : 1 } ]
}

{
  "query" : { "status" : "A" },
  "sort" : { },
  "projection" : { },
  "indexes" : [ { "status" : 1, "cust_id" : 1 } ]
}

The following command removes the second index filter only:

db.runCommand(
   {
      planCacheClearFilters: "orders",
      query: { "status" : "A" }
   }
)

Because the values in the query predicate are insignificant in determining the query shape, the following command would also remove the second index filter:

db.runCommand(
   {
      planCacheClearFilters: "orders",
      query: { "status" : "P" }
   }
)

Clear all Index Filters on a Collection

The following example clears all index filters on the orders collection:

db.runCommand(
   {
      planCacheClearFilters: "orders"
   }
)

See also

planCacheListFilters, planCacheSetFilter

planCacheListQueryShapes

Definition

planCacheListQueryShapes

New in version 2.6.

Displays the query shapes for which cached query plans exist for a collection.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

The mongo shell provides the wrapper PlanCache.listQueryShapes() for this command.

The command has the following syntax:

db.runCommand(
   {
      planCacheListQueryShapes: <collection>
   }

The planCacheListQueryShapes command has the following field:

Field | Description
planCacheListQueryShapes | The name of the collection.

field string planCacheListQueryShapes:

The name of the collection.

Returns:
A document that contains an array of query shapes for which cached query plans exist.

Required Access

On systems running with authorization, a user must have access that includes the planCacheRead action.

Example

The following returns the query shapes that have cached plans for the orders collection:

db.runCommand(
   {
      planCacheListQueryShapes: "orders"
   }
)

The command returns a document that contains the field shapes that contains an array of the query shapes currently in the cache. In the example, the orders collection had cached query plans associated with the following shapes:

{
  "shapes" : [
     {
       "query" : { "qty" : { "$gt" : 10 } },
        "sort" : { "ord_date" : 1 },
        "projection" : { }
     },
     {
        "query" : { "$or" : [ { "qty" : { "$gt" : 15 } }, { "status" : "A" } ] },
        "sort" : { },
        "projection" : { }
     },
     {
       "query" : { "$or" :
          [
            { "qty" : { "$gt" : 15 }, "item" : "xyz123" },
            { "status" : "A" }
          ]
        },
        "sort" : { },
        "projection" : { }
      }
   ],
   "ok" : 1
}

See also

PlanCache.listQueryShapes()

planCacheListPlans

Definition

planCacheListPlans

New in version 2.6.

Displays the cached query plans for the specified query shape.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

The mongo shell provides the wrapper PlanCache.getPlansByQuery() for this command.

The planCacheListPlans command has the following syntax:

db.runCommand(
   {
      planCacheListPlans: <collection>,
      query: <query>,
      sort: <sort>,
      projection: <projection>
   }

The planCacheListPlans command has the following field:

Field | Description
query | The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
projection | Optional. The projection associated with the query shape.
sort | Optional. The sort associated with the query shape.

field document query:
| The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
field document projection:
| Optional. The projection associated with the query shape.
field document sort:
| Optional. The sort associated with the query shape.

To see the query shapes for which cached query plans exist, use the planCacheListQueryShapes command.

Required Access

On systems running with authorization, a user must have access that includes the planCacheRead action.

Example

If a collection orders has the following query shape:

{
  "query" : { "qty" : { "$gt" : 10 } },
  "sort" : { "ord_date" : 1 },
  "projection" : { }
}

The following operation displays the query plan cached for the shape:

db.runCommand(
   {
      planCacheListPlans: "orders",
      query: { "qty" : { "$gt" : 10 } },
      sort: { "ord_date" : 1 }
   }
)

See also

planCacheListQueryShapes

PlanCache.getPlansByQuery()

PlanCache.listQueryShapes()

planCacheClear

Definition

planCacheClear

New in version 2.6.

Removes cached query plans for a collection. Specify a query shape to remove cached query plans for that shape. Omit the query shape to clear all cached query plans.

The command has the following syntax:

db.runCommand(
   {
      planCacheClear: <collection>,
      query: <query>,
      sort: <sort>,
      projection: <projection>
   }
)

The planCacheClear command has the following field:

Field | Description
query | Optional. The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
projection | Optional. The projection associated with the query shape.
sort | Optional. The sort associated with the query shape.

field document query:
| Optional. The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
field document projection:
| Optional. The projection associated with the query shape.
field document sort:
| Optional. The sort associated with the query shape.

To see the query shapes for which cached query plans exist, use the planCacheListQueryShapes command.

Required Access

On systems running with authorization, a user must have access that includes the planCacheWrite action.

Examples

Clear Cached Plans for a Query Shape

If a collection orders has the following query shape:

{
  "query" : { "qty" : { "$gt" : 10 } },
  "sort" : { "ord_date" : 1 },
  "projection" : { }
}

The following operation clears the query plan cached for the shape:

db.runCommand(
   {
      planCacheClear: "orders",
      query: { "qty" : { "$gt" : 10 } },
      sort: { "ord_date" : 1 }
   }
)

Clear All Cached Plans for a Collection

The following example clears all the cached query plans for the orders collection:

db.runCommand(
   {
      planCacheClear: "orders"
   }
)

See also

PlanCache.clearPlansByQuery()

PlanCache.clear()

Authentication Commands

Name | Description
logout | Terminates the current authenticated session.
authenticate | Starts an authenticated session using a username and password.
copydbgetnonce | This is an internal command to generate a one-time password for use with the copydb command.
getnonce | This is an internal command to generate a one-time password for authentication.
authSchemaUpgrade | Supports the upgrade process for user data between version 2.4 and 2.6.

logout

authenticate

copydbgetnonce

getnonce

authSchemaUpgrade

logout

logout

The logout command terminates the current authenticated session:

{ logout: 1 }

Note

If you’re not logged in and using authentication, logout has no effect.

Changed in version 2.4: Because MongoDB now allows users defined in one database to have privileges on another database, you must call logout while using the same database context that you authenticated to.

If you authenticated to a database such as users or $external, you must issue logout against this database in order to successfully log out.

Example

Use the use <database-name> helper in the interactive mongo shell, or the following db.getSiblingDB() in the interactive shell or in mongo shell scripts to change the db object:

db = db.getSiblingDB('<database-name>')

When you have set the database context and db object, you can use the logout to log out of database as in the following operation:

db.runCommand( { logout: 1 } )

authenticate

authenticate

Clients use authenticate to authenticate a connection. When using the shell, use the db.auth() helper as follows:

db.auth( "username", "password" )

See

db.auth() and Security Concepts for more information.

copydbgetnonce

copydbgetnonce

Client libraries use copydbgetnonce to get a one-time password for use with the copydb command.

Note

This command obtains a write lock on the affected database and will block other operations until it has completed; however, the write lock for this operation is short lived.

getnonce

getnonce

Client libraries use getnonce to generate a one-time password for authentication.

authSchemaUpgrade

New in version 2.6.

authSchemaUpgrade

authSchemaUpgrade supports the upgrade from 2.4 to 2.6 process for existing systems that use authentication and authorization. Between 2.4 and 2.6 the schema for user credential documents changed requiring the authSchemaUpgrade process.

See Upgrade User Authorization Data to 2.6 Format for more information.

User Management Commands

Name | Description
createUser | Creates a new user.
updateUser | Updates a user’s data.
dropUser | Removes a single user.
dropAllUsersFromDatabase | Deletes all users associated with a database.
grantRolesToUser | Grants a role and its privileges to a user.
revokeRolesFromUser | Removes a role from a user.
usersInfo | Returns information about the specified users.

createUser

updateUser

dropUser

dropAllUsersFromDatabase

grantRolesToUser

revokeRolesFromUser

usersInfo

createUser

Definition

createUser

Creates a new user on the database where you run the command. The createUser command returns a duplicate user error if the user exists. The createUser command uses the following syntax:

{ createUser: "<name>",
  pwd: "<cleartext password>",
  customData: { <any information> },
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: { <write concern> }
}

createUser has the following fields:

Field | Description
createUser | The name of the new user.
pwd | The user’s password. The pwd field is not required if you run createUser on the $external database to create users who have credentials stored externally to MongoDB.
customData | Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
roles | The roles granted to the user. Can specify an empty array [] to create users without roles.
digestPassword | Optional. When true, the mongod instance will create the hash of the user password; otherwise, the client is responsible for creating the hash of the password. Defaults to true.
writeConcern | Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.

field string createUser:
| The name of the new user.
field string pwd:
| The user’s password. The pwd field is not required if you run createUser on the $external database to create users who have credentials stored externally to MongoDB.
field document customData:
| Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
field array roles:
| The roles granted to the user. Can specify an empty array [] to create users without roles.
field boolean digestPassword:
| Optional. When true, the mongod instance will create the hash of the user password; otherwise, the client is responsible for creating the hash of the password. Defaults to true.
field document writeConcern:
| Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where createUser runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Behavior

Encryption

createUser sends password to the MongoDB instance in cleartext. To encrypt the password in transit, use SSL.

External Credentials

Users created on the $external database should have credentials stored externally to MongoDB, as, for example, with MongoDB Enterprise installations that use Kerberos.

local Database

You cannot create users on the local database.

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

Example

The following createUser command creates a user accountAdmin01 on the products database. The command gives accountAdmin01 the clusterAdmin and readAnyDatabase roles on the admin database and the readWrite role on the products database:

db.getSiblingDB("products").runCommand( { createUser: "accountAdmin01",
                                          pwd: "cleartext password",
                                          customData: { employeeId: 12345 },
                                          roles: [
                                                   { role: "clusterAdmin", db: "admin" },
                                                   { role: "readAnyDatabase", db: "admin" },
                                                   "readWrite"
                                                 ],
                                          writeConcern: { w: "majority" , wtimeout: 5000 }
                                       } )

updateUser

Definition

updateUser

Updates the user’s profile on the database on which you run the command. An update to a field completely replaces the previous field’s values, including updates to the user’s roles array.

Warning

When you update the roles array, you completely replace the previous array’s values. To add or remove roles without replacing all the user’s existing roles, use the grantRolesToUser or revokeRolesFromUser commands.

The updateUser command uses the following syntax. To update a user, you must specify the updateUser field and at least one other field, other than writeConcern:

{ updateUser: "<username>",
  pwd: "<cleartext password>",
  customData: { <any information> },
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: { <write concern> }
}

The command has the following fields:

Field | Description
updateUser | The name of the user to update.
pwd | Optional. The user’s password.
customData | Optional. Any arbitrary information.
roles | Optional. The roles granted to the user. An update to the roles array overrides the previous array’s values.
digestPassword | Optional. When true, the mongod instance will create the hash of the user password; otherwise, the client is responsible for creating the hash of the password. Defaults to true.
writeConcern | Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.

field string updateUser:
| The name of the user to update.
field string pwd:
| Optional. The user’s password.
field document customData:
| Optional. Any arbitrary information.
field array roles:
| Optional. The roles granted to the user. An update to the roles array overrides the previous array’s values.
field boolean digestPassword:
| Optional. When true, the mongod instance will create the hash of the user password; otherwise, the client is responsible for creating the hash of the password. Defaults to true.
field document writeConcern:
| Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where updateUser runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Behavior

updateUser sends the password to the MongoDB instance in cleartext. To encrypt the password in transit, use SSL.

Required Access

You must have access that includes the revokeRole action on all databases in order to update a user’s roles array.

You must have the grantRole action on a role’s database to add a role to a user.

To change another user’s pwd or customData field, you must have the changeAnyPassword and changeAnyCustomData actions respectively on that user’s database.

To modify your own password and custom data, you must have privileges that grant changeOwnPassword and changeOwnCustomData actions respectively on the user’s database.

Example

Given a user appClient01 in the products database with the following user info:

{
   "_id" : "products.appClient01",
   "user" : "appClient01",
   "db" : "products",
   "customData" : { "empID" : "12345", "badge" : "9156" },
   "roles" : [
       { "role" : "readWrite",
         "db" : "products"
       },
       { "role" : "read",
         "db" : "inventory"
       }
   ]
}

The following updateUser command completely replaces the user’s customData and roles data:

use products
db.runCommand( { updateUser : "appClient01",
                 customData : { employeeId : "0x3039" },
                 roles : [
                           { role : "read", db : "assets"  }
                         ]
             } )

The user appClient01 in the products database now has the following user information:

{
   "_id" : "products.appClient01",
   "user" : "appClient01",
   "db" : "products",
   "customData" : { "employeeId" : "0x3039" },
   "roles" : [
       { "role" : "read",
         "db" : "assets"
       }
   ]
}

dropUser

Definition

dropUser

Removes the user from the database on which you run the command. The dropUser command has the following syntax:

{
  dropUser: "<user>",
  writeConcern: { <write concern> }
}

The dropUser command document has the following fields:

Field | Description
dropUser | The name of the user to delete. You must issue the dropUser command while using the database where the user exists.
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field string dropUser:
| The name of the user to delete. You must issue the dropUser command while using the database where the user exists.
field document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

Required Access

You must have the dropUser action on a database to drop a user from that database.

Example

The following sequence of operations in the mongo shell removes accountAdmin01 from the products database:

use products
db.runCommand( { dropUser: "accountAdmin01",
                 writeConcern: { w: "majority", wtimeout: 5000 }
                 } )

dropAllUsersFromDatabase

Definition

dropAllUsersFromDatabase

Removes all users from the database on which you run the command.

Warning

The dropAllUsersFromDatabase removes all users from the database.

The dropAllUsersFromDatabase command has the following syntax:

{ dropAllUsersFromDatabase: 1,
  writeConcern: { <write concern> }
}

The dropAllUsersFromDatabase document has the following fields:

Field | Description
dropAllUsersFromDatabase | Specify 1 to drop all the users from the current database.
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field integer dropAllUsersFromDatabase:
| Specify 1 to drop all the users from the current database.
field document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

Required Access

You must have the dropUser action on a database to drop a user from that database.

Example

The following sequence of operations in the mongo shell drops every user from the products database:

use products
db.runCommand( { dropAllUsersFromDatabase: 1, writeConcern: { w: "majority" } } )

The n field in the results document shows the number of users removed:

{ "n" : 12, "ok" : 1 }

grantRolesToUser

Definition

grantRolesToUser

Grants additional roles to a user.

The grantRolesToUser command uses the following syntax:

{ grantRolesToUser: "<user>",
  roles: [ <roles> ],
  writeConcern: { <write concern> }
}

The command has the following fields:

Field | Description
grantRolesToUser | The name of the user to give additional roles.
roles | An array of additional roles to grant to the user.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

field string grantRolesToUser:
| The name of the user to give additional roles.
field array roles:
| An array of additional roles to grant to the user.
field document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where grantRolesToUser runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Required Access

You must have the grantRole action on a database to grant a role on that database.

Example

Given a user accountUser01 in the products database with the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    }
]

The following grantRolesToUser operation gives accountUser01 the read role on the stock database and the readWrite role on the products database.

use products
db.runCommand( { grantRolesToUser: "accountUser01",
                 roles: [
                    { role: "read", db: "stock"},
                    "readWrite"
                 ],
                 writeConcern: { w: "majority" , wtimeout: 2000 }
             } )

The user accountUser01 in the products database now has the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    },
    { "role" : "read",
      "db" : "stock"
    },
    { "role" : "readWrite",
      "db" : "products"
    }
]

revokeRolesFromUser

Definition

revokeRolesFromUser

Removes a one or more roles from a user on the database where the roles exist. The revokeRolesFromUser command uses the following syntax:

{ revokeRolesFromUser: "<user>",
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: { <write concern> }
}

The command has the following fields:

Field | Description
revokeRolesFromUser | The user to remove roles from.
roles | The roles to remove from the user.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

field string revokeRolesFromUser:
| The user to remove roles from.
field array roles:
| The roles to remove from the user.
field document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where revokeRolesFromUser runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Required Access

You must have the revokeRole action on a database to revoke a role on that database.

Example

The accountUser01 user in the products database has the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    },
    { "role" : "read",
      "db" : "stock"
    },
    { "role" : "readWrite",
      "db" : "products"
    }
]

The following revokeRolesFromUser command removes the two of the user’s roles: the read role on the stock database and the readWrite role on the products database, which is also the database on which the command runs:

use products
db.runCommand( { revokeRolesFromUser: "accountUser01",
                 roles: [
                          { role: "read", db: "stock" },
                          "readWrite"
                 ],
                 writeConcern: { w: "majority" }
             } )

The user accountUser01 in the products database now has only one remaining role:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    }
]

usersInfo

Definition

usersInfo

Returns information about one or more users. To match a single user on the database, use the following form:

{ usersInfo: { user: <name>, db: <db> },
  showCredentials: <Boolean>,
  showPrivileges: <Boolean>
}

The command has the following fields:

Field | Description
usersInfo | The user(s) about whom to return information. See Behavior for type and syntax.
showCredentials | Optional. Set the field to true to display the user’s password hash. By default, this field is false.
showPrivileges | Optional. Set the field to true to show the user’s full set of privileges, including expanded information for the inherited roles. By default, this field is false. If viewing all users, you cannot specify this field.

field various usersInfo:
| The user(s) about whom to return information. See Behavior for type and syntax.
field Boolean showCredentials:
| Optional. Set the field to true to display the user’s password hash. By default, this field is false.
field Boolean showPrivileges:
| Optional. Set the field to true to show the user’s full set of privileges, including expanded information for the inherited roles. By default, this field is false. If viewing all users, you cannot specify this field.

Required Access

Users can always view their own information.

To view another user’s information, the user running the command must have privileges that include the viewUser action on the other user’s database.

Behavior

The argument to the usersInfo command has multiple forms depending on the requested information:

Specify a Single User

In the usersInfo field, specify a document with the user’s name and database:

{ usersInfo: { user: <name>, db: <db> } }

Alternatively, for a user that exists on the same database where the command runs, you can specify the user by its name only.

{ usersInfo: <name> }

Specify Multiple Users

In the usersInfo field, specify an array of documents:

{ usersInfo: [ { user: <name>, db: <db> },  { user: <name>, db: <db> }, ... ] }

Specify All Users for a Database

In the usersInfo field, specify 1:

{ usersInfo: 1 }

Examples

View Specific Users

To see information and privileges, but not the credentials, for the user "Kari" defined in "home" database, run the following command:

db.runCommand(
               {
                 usersInfo:  { user: "Kari", db: "home" },
                 showPrivileges: true
               }
)

To view a user that exists in the current database, you can specify the user by name only. For example, if you are in the home database and a user named "Kari" exists in the home database, you can run the following command:

db.getSiblingDB("home").runCommand(
                                    {
                                      usersInfo:  "Kari",
                                      showPrivileges: true
                                    }
)

View Multiple Users

To view info for several users, use an array, with or without the optional fields showPrivileges and showCredentials. For example:

db.runCommand( { usersInfo: [ { user: "Kari", db: "home" }, { user: "Li", db: "myApp" } ],
                 showPrivileges: true
             } )

View All Users for a Database

To view all users on the database the command is run, use a command document that resembles the following:

db.runCommand( { usersInfo: 1 } )

When viewing all users, you can specify the showCredentials field but not the showPrivileges field.

Role Management Commands

Name | Description
createRole | Creates a role and specifies its privileges.
updateRole | Updates a user-defined role.
dropRole | Deletes the user-defined role.
dropAllRolesFromDatabase | Deletes all user-defined roles from a database.
grantPrivilegesToRole | Assigns privileges to a user-defined role.
revokePrivilegesFromRole | Removes the specified privileges from a user-defined role.
grantRolesToRole | Specifies roles from which a user-defined role inherits privileges.
revokeRolesFromRole | Removes specified inherited roles from a user-defined role.
rolesInfo | Returns information for the specified role or roles.
invalidateUserCache | Flushes the in-memory cache of user information, including credentials and roles.

createRole

updateRole

dropRole

dropAllRolesFromDatabase

grantPrivilegesToRole

revokePrivilegesFromRole

grantRolesToRole

revokeRolesFromRole

rolesInfo

invalidateUserCache

createRole

Definition

createRole

Creates a role and specifies its privileges. The role applies to the database on which you run the command. The createRole command returns a duplicate role error if the role already exists in the database.

The createRole command uses the following syntax:

{ createRole: "<new role>",
  privileges: [
    { resource: { <resource> }, actions: [ "<action>", ... ] },
    ...
  ],
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: <write concern document>
}

The createRole command has the following fields:

Field | Description
createRole | The name of the new role.
privileges | The privileges to grant the role. A privilege consists of a resource and permitted actions. You must specify the privileges field. Use an empty array to specify no privileges. For the syntax of a privilege, see the privileges array.
roles | An array of roles from which this role inherits privileges. You must specify the roles field. Use an empty array to specify no roles.
writeConcern | Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.

field string createRole:
| The name of the new role.
field array privileges:
| The privileges to grant the role. A privilege consists of a resource and permitted actions. You must specify the privileges field. Use an empty array to specify no privileges. For the syntax of a privilege, see the privileges array.
field array roles:
| An array of roles from which this role inherits privileges. You must specify the roles field. Use an empty array to specify no roles.
field document writeConcern:
| Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where createRole runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Behavior

A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

Required Access

To create a role in a database, the user must have:

the createRole action on that database resource.

the grantRole action on that database to specify privileges for the new role as well as to specify roles to inherit from.

Built-in roles userAdmin and userAdminAnyDatabase provide createRole and grantRole actions on their respective resources.

Example

The following createRole command creates the myClusterwideAdmin role on the admin database:

use admin
db.runCommand({ createRole: "myClusterwideAdmin",
  privileges: [
    { resource: { cluster: true }, actions: [ "addShard" ] },
    { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
    { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
    { resource: { db: "", collection: "" }, actions: [ "find" ] }
  ],
  roles: [
    { role: "read", db: "admin" }
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
})

updateRole

Definition

updateRole

Updates a user-defined role. The updateRole command must run on the role’s database.

An update to a field completely replaces the previous field’s values. To grant or remove roles or privileges without replacing all values, use one or more of the following commands:

grantRolesToRole

grantPrivilegesToRole

revokeRolesFromRole

revokePrivilegesFromRole

Warning

An update to the privileges or roles array completely replaces the previous array’s values.

The updateRole command uses the following syntax. To update a role, you must provide the privileges array, roles array, or both:

{
  updateRole: "<role>",
  privileges:
      [
        { resource: { <resource> }, actions: [ "<action>", ... ] },
        ...
      ],
  roles:
      [
        { role: "<role>", db: "<database>" } | "<role>",
        ...
      ],
  writeConcern: <write concern document>
}

The updateRole command has the following fields:

Field | Description
updateRole | The name of the user-defined role role to update.
privileges | Optional. Required if you do not specify roles array. The privileges to grant the role. An update to the privileges array overrides the previous array’s values. For the syntax for specifying a privilege, see the privileges array.
roles | Optional. Required if you do not specify privileges array. The roles from which this role inherits privileges. An update to the roles array overrides the previous array’s values.
writeConcern | Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.

field string updateRole:
| The name of the user-defined role role to update.
field array privileges:
| Optional. Required if you do not specify roles array. The privileges to grant the role. An update to the privileges array overrides the previous array’s values. For the syntax for specifying a privilege, see the privileges array.
field array roles:
| Optional. Required if you do not specify privileges array. The roles from which this role inherits privileges. An update to the roles array overrides the previous array’s values.
field document writeConcern:
| Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where updateRole runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Behavior

A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

Required Access

You must have the revokeRole action on all databases in order to update a role.

You must have the grantRole action on the database of each role in the roles array to update the array.

You must have the grantRole action on the database of each privilege in the privileges array to update the array. If a privilege’s resource spans databases, you must have grantRole on the admin database. A privilege spans databases if the privilege is any of the following:

a collection in all databases

all collections and all database

the cluster resource

Example

The following is an example of the updateRole command that updates the myClusterwideAdmin role on the admin database. While the privileges and the roles arrays are both optional, at least one of the two is required:

use admin
db.runCommand(
   {
     updateRole: "myClusterwideAdmin",
     privileges:
         [
           {
             resource: { db: "", collection: "" },
             actions: [ "find" , "update", "insert", "remove" ]
           }
         ],
     roles:
         [
           { role: "dbAdminAnyDatabase", db: "admin" }
         ],
     writeConcern: { w: "majority" }
   }
)

To view a role’s privileges, use the rolesInfo command.

dropRole

Definition

dropRole

Deletes a user-defined role from the database on which you run the command.

The dropRole command uses the following syntax:

{
  dropRole: "<role>",
  writeConcern: { <write concern> }
}

The dropRole command has the following fields:

Field | Description
dropRole | The name of the user-defined role to remove from the database.
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field string dropRole:
| The name of the user-defined role to remove from the database.
field document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

Required Access

You must have the dropRole action on a database to drop a role from that database.

Example

The following operations remove the readPrices role from the products database:

use products
db.runCommand(
   {
     dropRole: "readPrices",
     writeConcern: { w: "majority" }
   }
)

dropAllRolesFromDatabase

Definition

dropAllRolesFromDatabase

Deletes all user-defined roles on the database where you run the command.

Warning

The dropAllRolesFromDatabase removes all user-defined roles from the database.

The dropAllRolesFromDatabase command takes the following form:

{
  dropAllRolesFromDatabase: 1,
  writeConcern: { <write concern> }
}

The command has the following fields:

Field | Description
dropAllRolesFromDatabase | Specify 1 to drop all user-defined roles from the database where the command is run.
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field integer dropAllRolesFromDatabase:
| Specify 1 to drop all user-defined roles from the database where the command is run.
field document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

Required Access

You must have the dropRole action on a database to drop a role from that database.

Example

The following operations drop all user-defined roles from the products database:

use products
db.runCommand(
   {
     dropAllRolesFromDatabase: 1,
     writeConcern: { w: "majority" }
   }
)

The n field in the results document reports the number of roles dropped:

{ "n" : 4, "ok" : 1 }

grantPrivilegesToRole

Definition

grantPrivilegesToRole

Assigns additional privileges to a user-defined role defined on the database on which the command is run. The grantPrivilegesToRole command uses the following syntax:

{
  grantPrivilegesToRole: "<role>",
  privileges: [
      {
        resource: { <resource> }, actions: [ "<action>", ... ]
      },
      ...
  ],
  writeConcern: { <write concern> }
}

The grantPrivilegesToRole command has the following fields:

Field | Description
grantPrivilegesToRole | The name of the user-defined role to grant privileges to.
privileges | The privileges to add to the role. For the format of a privilege, see privileges.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

field string grantPrivilegesToRole:
| The name of the user-defined role to grant privileges to.
field array privileges:
| The privileges to add to the role. For the format of a privilege, see privileges.
field document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

Behavior

A role’s privileges apply to the database where the role is created. A role created on the admin database can include privileges that apply to all databases or to the cluster.

Required Access

You must have the grantRole action on the database a privilege targets in order to grant the privilege. To grant a privilege on multiple databases or on the cluster resource, you must have the grantRole action on the admin database.

Example

The following grantPrivilegesToRole command grants two additional privileges to the service role that exists in the products database:

use products
db.runCommand(
   {
     grantPrivilegesToRole: "service",
     privileges: [
         {
           resource: { db: "products", collection: "" }, actions: [ "find" ]
         },
         {
           resource: { db: "products", collection: "system.indexes" }, actions: [ "find" ]
         }
     ],
     writeConcern: { w: "majority" , wtimeout: 5000 }
   }
)

The first privilege in the privileges array allows the user to search on all non-system collections in the products database. The privilege does not allow searches on system collections, such as the system.indexes collection. To grant access to these system collections, explicitly provision access in the privileges array. See Resource Document.

The second privilege explicitly allows the find action on system.indexes collections on all databases.

revokePrivilegesFromRole

Definition

revokePrivilegesFromRole

Removes the specified privileges from the user-defined role on the database where the command is run. The revokePrivilegesFromRole command has the following syntax:

{
  revokePrivilegesFromRole: "<role>",
  privileges:
      [
        { resource: { <resource> }, actions: [ "<action>", ... ] },
        ...
      ],
  writeConcern: <write concern document>
}

The revokePrivilegesFromRole command has the following fields:

Field | Description
revokePrivilegesFromRole | The user-defined role to revoke privileges from.
privileges | An array of privileges to remove from the role. See privileges for more information on the format of the privileges.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

field string revokePrivilegesFromRole:
| The user-defined role to revoke privileges from.
field array privileges:
| An array of privileges to remove from the role. See privileges for more information on the format of the privileges.
field document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

Behavior

To revoke a privilege, the resource document pattern must match exactly the resource field of that privilege. The actions field can be a subset or match exactly.

For example, consider the role accountRole in the products database with the following privilege that specifies the products database as the resource:

{
  "resource" : {
      "db" : "products",
      "collection" : ""
  },
  "actions" : [
      "find",
      "update"
  ]
}

You cannot revoke find and/or update from just one collection in the products database. The following operations result in no change to the role:

use products
db.runCommand(
    {
      revokePrivilegesFromRole: "accountRole",
      privileges:
        [
          {
            resource : {
                db : "products",
                collection : "gadgets"
            },
            actions : [
                "find",
                "update"
            ]
          }
        ]
    }
)

db.runCommand(
    {
      revokePrivilegesFromRole: "accountRole",
      privileges:
        [
          {
            resource : {
                db : "products",
                collection : "gadgets"
            },
            actions : [
                "find"
            ]
          }
        ]
    }
)

To revoke the "find" and/or the "update" action from the role accountRole, you must match the resource document exactly. For example, the following operation revokes just the "find" action from the existing privilege.

use products
db.runCommand(
    {
      revokePrivilegesFromRole: "accountRole",
      privileges:
        [
          {
            resource : {
                db : "products",
                collection : ""
            },
            actions : [
                "find"
            ]
          }
        ]
    }
)

Required Access

You must have the revokeRole action on the database a privilege targets in order to revoke that privilege. If the privilege targets multiple databases or the cluster resource, you must have the revokeRole action on the admin database.

Example

The following operation removes multiple privileges from the associates role in the products database:

use products
db.runCommand(
   {
     revokePrivilegesFromRole: "associate",
     privileges:
      [
        {
          resource: { db: "products", collection: "" },
          actions: [ "createCollection", "createIndex", "find" ]
        },
        {
          resource: { db: "products", collection: "orders" },
          actions: [ "insert" ]
        }
      ],
     writeConcern: { w: "majority" }
   }
)

grantRolesToRole

Definition

grantRolesToRole

Grants roles to a user-defined role.

The grantRolesToRole command affects roles on the database where the command runs. grantRolesToRole has the following syntax:

{ grantRolesToRole: "<role>",
  roles: [
             { role: "<role>", db: "<database>" },
             ...
         ],
  writeConcern: { <write concern> }
}

The grantRolesToRole command has the following fields:

Field | Description
grantRolesToRole | The name of a role to add subsidiary roles.
roles | An array of roles from which to inherit.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

field string grantRolesToRole:
| The name of a role to add subsidiary roles.
field array roles:
| An array of roles from which to inherit.
field document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where grantRolesToRole runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Behavior

A role can inherit privileges from other roles in its database. A role created on the admin database can inherit privileges from roles in any database.

Required Access

You must have the grantRole action on a database to grant a role on that database.

Example

The following grantRolesToRole command updates the productsReaderWriter role in the products database to inherit the privileges of the productsReader role in the products database:

use products
db.runCommand(
   { grantRolesToRole: "productsReaderWriter",
     roles: [
              "productsReader"
     ],
     writeConcern: { w: "majority" , wtimeout: 5000 }
   }
)

revokeRolesFromRole

Definition

revokeRolesFromRole

Removes the specified inherited roles from a role. The revokeRolesFromRole command has the following syntax:

{ revokeRolesFromRole: "<role>",
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: { <write concern> }
}

The command has the following fields:

Field | Description
revokeRolesFromRole | The role from which to remove inherited roles.
roles | The inherited roles to remove.
writeConcern | Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.

field string revokeRolesFromRole:
| The role from which to remove inherited roles.
field array roles:
| The inherited roles to remove.
field document writeConcern:
| Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where revokeRolesFromRole runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Required Access

You must have the revokeRole action on a database to revoke a role on that database.

Example

The purchaseAgents role in the emea database inherits privileges from several other roles, as listed in the roles array:

{
   "_id" : "emea.purchaseAgents",
   "role" : "purchaseAgents",
   "db" : "emea",
   "privileges" : [],
   "roles" : [
      {
         "role" : "readOrdersCollection",
         "db" : "emea"
      },
      {
         "role" : "readAccountsCollection",
         "db" : "emea"
      },
      {
         "role" : "writeOrdersCollection",
         "db" : "emea"
      }
   ]
}

The following revokeRolesFromRole operation on the emea database removes two roles from the purchaseAgents role:

use emea
db.runCommand( { revokeRolesFromRole: "purchaseAgents",
                 roles: [
                          "writeOrdersCollection",
                          "readOrdersCollection"
                        ],
                  writeConcern: { w: "majority" , wtimeout: 5000 }
             } )

The purchaseAgents role now contains just one role:

{
   "_id" : "emea.purchaseAgents",
   "role" : "purchaseAgents",
   "db" : "emea",
   "privileges" : [],
   "roles" : [
      {
         "role" : "readAccountsCollection",
         "db" : "emea"
      }
   ]
}

rolesInfo

Definition

rolesInfo

Returns inheritance and privilege information for specified roles, including both user-defined roles and built-in roles.

The rolesInfo command can also retrieve all roles scoped to a database.

The command has the following fields:

Field | Description
rolesInfo | The role(s) to return information about. For the syntax for specifying roles, see Behavior.
showPrivileges | Optional. Set the field to true to show role privileges, including both privileges inherited from other roles and privileges defined directly. By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.
showBuiltinRoles | Optional. When the rolesInfo field is set to 1, set showBuiltinRoles to true to include built-in roles in the output. By default this field is set to false, and the output for rolesInfo: 1 displays only user-defined roles.

field string, document, array, integer rolesInfo:
| The role(s) to return information about. For the syntax for specifying roles, see Behavior.
field Boolean showPrivileges:
| Optional. Set the field to true to show role privileges, including both privileges inherited from other roles and privileges defined directly. By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.
field Boolean showBuiltinRoles:
| Optional. When the rolesInfo field is set to 1, set showBuiltinRoles to true to include built-in roles in the output. By default this field is set to false, and the output for rolesInfo: 1 displays only user-defined roles.

Behavior

Return Information for a Single Role

To specify a role from the current database, specify the role by its name:

{ rolesInfo: "<rolename>" }

To specify a role from another database, specify the role by a document that specifies the role and database:

{ rolesInfo: { role: "<rolename>", db: "<database>" } }

Return Information for Multiple Roles

To specify multiple roles, use an array. Specify each role in the array as a document or string. Use a string only if the role exists on the database on which the command runs:

{
  rolesInfo: [
     "<rolename>",
     { role: "<rolename>", db: "<database>" },
     ...
  ]
}

Return Information for All Roles in the Database

To specify all roles in the database on which the command runs, specify rolesInfo: 1. By default MongoDB displays all the user-defined roles in the database. To include built-in roles as well, include the parameter-value pair showBuiltinRoles: true:

{ rolesInfo: 1, showBuiltinRoles: true }

Required Access

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Output

rolesInfo.role

The name of the role.

rolesInfo.db

The database on which the role is defined. Every database has built-in roles. A database might also have user-defined roles.

rolesInfo.isBuiltin

A value of true indicates the role is a built-in role. A value of false indicates the role is a user-defined role.

rolesInfo.roles

The roles that directly provide privileges to this role and the databases on which the roles are defined.

rolesInfo.inheritedRoles

All roles from which this role inherits privileges. This includes the roles in the rolesInfo.roles array as well as the roles from which the roles in the rolesInfo.roles array inherit privileges. All privileges apply to the current role. The documents in this field list the roles and the databases on which they are defined.

rolesInfo.privileges

The privileges directly specified by this role; i.e. the array excludes privileges inherited from other roles. By default the output does not include the privileges field. To include the field, specify showPrivileges: true when running the rolesInfo command.

Each privilege document specifies the resources and the actions allowed on the resources.

rolesInfo.inheritedPrivileges

All privileges granted by this role, including those inherited from other roles. By default the output does not include the inheritedPrivileges field. To include the field, specify showPrivileges: true when running the rolesInfo command.

Each privilege document specifies the resources and the actions allowed on the resources.

Examples

View Information for a Single Role

The following command returns the role inheritance information for the role associate defined in the products database:

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" }
    }
)

The following command returns the role inheritance information for the role siteManager on the database on which the command runs:

db.runCommand(
    {
      rolesInfo: "siteManager"
    }
)

The following command returns both the role inheritance and the privileges for the role associate defined on the products database:

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" },
      showPrivileges: true
    }
)

View Information for Several Roles

The following command returns information for two roles on two different databases:

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ]
    }
)

The following returns both the role inheritance and the privileges:

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ],
      showPrivileges: true
    }
)

View All User-Defined Roles for a Database

The following operation returns all user-defined roles on the database on which the command runs and includes privileges:

db.runCommand(
    {
      rolesInfo: 1,
      showPrivileges: true
    }
)

View All User-Defined and Built-In Roles for a Database

The following operation returns all roles on the database on which the command runs, including both built-in and user-defined roles:

db.runCommand(
    {
      rolesInfo: 1,
      showBuiltinRoles: true
    }
)

invalidateUserCache

Definition

invalidateUserCache

New in version 2.6.

Flushes user information from in-memory cache, including removal of each user’s credentials and roles. This allows you to purge the cache at any given moment, regardless of the interval set in the userCacheInvalidationIntervalSecs parameter.

invalidateUserCache has the following syntax:

db.runCommand( { invalidateUserCache: 1 } )

Required Access

You must have privileges that include the invalidateUserCache action on the cluster resource in order to use this command.

Replication Commands

Name | Description
replSetFreeze | Prevents the current member from seeking election as primary for a period of time.
replSetGetStatus | Returns a document that reports on the status of the replica set.
replSetInitiate | Initializes a new replica set.
replSetMaintenance | Enables or disables a maintenance mode, which puts a secondary node in a RECOVERING state.
replSetReconfig | Applies a new configuration to an existing replica set.
replSetStepDown | Forces the current primary to step down and become a secondary, forcing an election.
replSetSyncFrom | Explicitly override the default logic for selecting a member to replicate from.
resync | Forces a mongod to re-synchronize from the master. For master-slave replication only.
applyOps | Internal command that applies oplog entries to the current data set.
isMaster | Displays information about this member’s role in the replica set, including whether it is the master.
getoptime | Internal command to support replication, returns the optime.

replSetFreeze

replSetGetStatus

replSetInitiate

replSetMaintenance

replSetReconfig

replSetStepDown

replSetSyncFrom

resync

applyOps

isMaster

getoptime

replSetFreeze

replSetFreeze

The replSetFreeze command prevents a replica set member from seeking election for the specified number of seconds. Use this command in conjunction with the replSetStepDown command to make a different node in the replica set a primary.

The replSetFreeze command uses the following syntax:

{ replSetFreeze: <seconds> }

If you want to unfreeze a replica set member before the specified number of seconds has elapsed, you can issue the command with a seconds value of 0:

{ replSetFreeze: 0 }

Restarting the mongod process also unfreezes a replica set member.

replSetFreeze is an administrative command, and you must issue it against the admin database.

replSetGetStatus

Definition

replSetGetStatus

The replSetGetStatus command returns the status of the replica set from the point of view of the current server. You must run the command against the admin database. The command has the following prototype format:

{ replSetGetStatus: 1 }

The value specified does not affect the output of the command. Data provided by this command derives from data included in heartbeats sent to the current instance by other members of the replica set. Because of the frequency of heartbeats, these data can be several seconds out of date.

You can also access this functionality through the rs.status() helper in the mongo shell.

The mongod must have replication enabled and be a member of a replica set for the for replSetGetStatus to return successfully.

Example

The following example runs the replSetGetStatus command on the admin database of the replica set primary:

use admin
db.runCommand( { replSetGetStatus : 1 } )

Consider the following example output:

{
    "set" : "replset",
    "date" : ISODate("2014-05-01T14:44:03Z"),
    "myState" : 1,
    "members" : [
        {
            "_id" : 0,
            "name" : "m1.example.net:27017",
            "health" : 1,
            "state" : 1,
            "stateStr" : "PRIMARY",
            "uptime" : 269,
            "optime" : Timestamp(1404225575, 11),
            "optimeDate" : ISODate("2014-05-01T14:39:35Z"),
            "electionTime" : Timestamp(1404225586, 1),
            "electionDate" : ISODate("2014-05-01T14:39:46Z"),
            "self" : true
        },
        {
            "_id" : 1,
            "name" : "m2.example.net:27017",
            "health" : 1,
            "state" : 2,
            "stateStr" : "SECONDARY",
            "uptime" : 265,
            "optime" : Timestamp(1404225575, 11),
            "optimeDate" : ISODate("2014-05-01T14:39:35Z"),
            "lastHeartbeat" : ISODate("2014-05-01T14:44:03Z"),
            "lastHeartbeatRecv" : ISODate("2014-05-01T14:44:02Z"),
            "pingMs" : 0,
            "syncingTo" : "m1.example.net:27017"
        },
        {
            "_id" : 2,
            "name" : "m3.example.net:27017",
            "health" : 1,
            "state" : 2,
            "stateStr" : "SECONDARY",
            "uptime" : 265,
            "optime" : Timestamp(1404225575, 11),
            "optimeDate" : ISODate("2014-05-01T14:39:35Z"),
            "lastHeartbeat" : ISODate("2014-05-01T14:44:02Z"),
            "lastHeartbeatRecv" : ISODate("2014-05-01T14:44:02Z"),
            "pingMs" : 0,
            "syncingTo" : "m1.example.net:27017"
        }
    ],
    "ok" : 1
}

Output

The replSetGetStatus command returns a document with the following fields:

replSetGetStatus.set

The set value is the name of the replica set, configured in the replSetName setting. This is the same value as _id in rs.conf().

replSetGetStatus.date

The value of the date field is an ISODate of the current time, according to the current server. Compare this to the value of the lastHeartbeat to find the operational lag between the current host and the other hosts in the set.

replSetGetStatus.myState

The value of myState is an integer between 0 and 10 that represents the replica state of the current member.

replSetGetStatus.members

The members field holds an array that contains a document for every member in the replica set.

replSetGetStatus.members.name

The name field holds the name of the server.

replSetGetStatus.members.self

The self field is only included in the document for the current mongod instance in the members array. It’s value is true.

replSetGetStatus.members.health

The health value is only present for the other members of the replica set (i.e. not the member that returns rs.status.) This field conveys if the member is up (i.e. 1) or down (i.e. 0.)

replSetGetStatus.members.state

The value of state is an integer between 0 and 10 that represents the replica state of the member.

replSetGetStatus.members.stateStr

A string that describes state.

replSetGetStatus.members.uptime

The uptime field holds a value that reflects the number of seconds that this member has been online.

This value does not appear for the member that returns the rs.status() data.

replSetGetStatus.members.optime

Information regarding the last operation from the operation log that this member has applied.

replSetGetStatus.members.optime.t

A 32-bit timestamp of the last operation applied to this member of the replica set from the oplog.

replSetGetStatus.members.optime.i

An incremented field, which reflects the number of operations in since the last time stamp. This value only increases if there is more than one operation per second.

replSetGetStatus.members.optimeDate

An ISODate formatted date string that reflects the last entry from the oplog that this member applied. If this differs significantly from lastHeartbeat this member is either experiencing “replication lag” or there have not been any new operations since the last update. Compare members.optimeDate between all of the members of the set.

replSetGetStatus.members.electionTime

For the current primary, information regarding the election time from the operation log. See Replica Set Elections for more information about elections.

replSetGetStatus.members.electionTime.t

For the current primary, a 32-bit timestamp of the election time applied to this member of the replica set from the oplog.

replSetGetStatus.members.electionTime.i

For the current primary, an incremented field which reflects the number of operations in since the last time stamp. This value only increases if there is more than one operation per second.

replSetGetStatus.members.electionDate

For the current primary, an ISODate formatted date string that reflects the election date. See Replica Set Elections for more information about elections.

replSetGetStatus.members.self

Indicates which replica set member processed the replSetGetStatus command.

replSetGetStatus.members.lastHeartbeat

The lastHeartbeat value provides an ISODate formatted date and time of the transmission time of last heartbeat received from this member. Compare this value to the value of the date and lastHeartBeatRecv field to track latency between these members.

This value does not appear for the member that returns the rs.status() data.

replSetGetStatus.members.lastHeartbeatRecv

The lastHeartbeatRecv value provides an ISODate formatted date and time that the last heartbeat was received from this member. Compare this value to the value of the date and lastHeartBeat field to track latency between these members.

replSetGetStatus.members.lastHeartbeatMessage

When the last heartbeat included an extra message, the lastHeartbeatMessage contains a string representation of that message.

replSetGetStatus.members.pingMs

The pingMs represents the number of milliseconds (ms) that a round-trip packet takes to travel between the remote member and the local instance.

This value does not appear for the member that returns the rs.status() data.

replSetGetStatus.syncingTo

The syncingTo field is only present on the output of rs.status() on secondary and recovering members, and holds the hostname of the member from which this instance is syncing.

replSetInitiate

replSetInitiate

The replSetInitiate command initializes a new replica set. Use the following syntax:

{ replSetInitiate : <config_document> }

The <config_document> is a document that specifies the replica set’s configuration. For instance, here’s a config document for creating a simple 3-member replica set:

{
    _id : <setname>,
     members : [
         {_id : 0, host : <host0>},
         {_id : 1, host : <host1>},
         {_id : 2, host : <host2>},
     ]
}

A typical way of running this command is to assign the config document to a variable and then to pass the document to the rs.initiate() helper:

config = {
    _id : "my_replica_set",
     members : [
         {_id : 0, host : "rs1.example.net:27017"},
         {_id : 1, host : "rs2.example.net:27017"},
         {_id : 2, host : "rs3.example.net", arbiterOnly: true},
     ]
}

rs.initiate(config)

Notice that omitting the port cause the host to use the default port of 27017. Notice also that you can specify other options in the config documents such as the arbiterOnly setting in this example.

See also

Replica Set Configuration, Replica Set Tutorials, and Replica Set Reconfiguration.

replSetMaintenance

Definition

replSetMaintenance

The replSetMaintenance admin command enables or disables the maintenance mode for a secondary member of a replica set.

The command has the following prototype form:

{ replSetMaintenance: <boolean> }

Behavior

Consider the following behavior when running the replSetMaintenance command:

You cannot run the command on the Primary.

You must run the command against the admin database.

When enabled replSetMaintenance: true, the member enters the RECOVERING state. While the secondary is RECOVERING:

The member is not accessible for read operations.

The member continues to sync its oplog from the Primary.

On secondaries, the compact command forces the secondary to enter RECOVERING state. Read operations issued to an instance in the RECOVERING state will fail. This prevents clients from reading during the operation. When the operation completes, the secondary returns to:replstate:SECONDARY state.

See Replica Set Member States for more information about replica set member states.

See Perform Maintenance on Replica Set Members for an example replica set maintenance procedure to maximize availability during maintenance operations.

replSetReconfig

replSetReconfig

The replSetReconfig command modifies the configuration of an existing replica set. You can use this command to add and remove members, and to alter the options set on existing members. Use the following syntax:

{ replSetReconfig: <new_config_document>, force: false }

You may also run replSetReconfig with the shell’s rs.reconfig() method.

Behaviors

Be aware of the following replSetReconfig behaviors:

You must issue this command against the admin database of the current primary member of the replica set.

You can optionally force the replica set to accept the new configuration by specifying force: true. Use this option if the current member is not primary or if a majority of the members of the set are not accessible.

Warning

Forcing the replSetReconfig command can lead to a rollback situation. Use with caution.

Use the force option to restore a replica set to new servers with different hostnames. This works even if the set members already have a copy of the data.

A majority of the set’s members must be operational for the changes to propagate properly.

This command can cause downtime as the set renegotiates primary-status. Typically this is 10-20 seconds, but could be as long as a minute or more. Therefore, you should attempt to reconfigure only during scheduled maintenance periods.

In some cases, replSetReconfig forces the current primary to step down, initiating an election for primary among the members of the replica set. When this happens, the set will drop all current connections.

replSetReconfig obtains a special mutually exclusive lock to prevent more than one replSetReconfig operation from occurring at the same time.

Additional Information

Replica Set Configuration, rs.reconfig(), and rs.conf().

replSetStepDown

Description

replSetStepDown

Forces the primary of the replica set to become a secondary. This initiates an election for primary.

replSetStepDown has the following prototype form:

db.runCommand( { replSetStepDown: <seconds> , force: <true|false> } )

replSetStepDown has the following fields:

Field | Description
replSetStepDown | Optional. A number of seconds for the member to avoid election to primary. If you do not specify a value for <seconds>, replSetStepDown will attempt to avoid reelection to primary for 60 seconds.
force | Optional. New in version 2.0: Forces the primary to step down even if there are no secondary members within 10 seconds of the primary’s latest optime.

field number replSetStepDown:
| Optional. A number of seconds for the member to avoid election to primary. If you do not specify a value for <seconds>, replSetStepDown will attempt to avoid reelection to primary for 60 seconds.
field Boolean force:
| Optional. New in version 2.0: Forces the primary to step down even if there are no secondary members within 10 seconds of the primary’s latest optime.

Warning

replSetStepDown forces all clients currently connected to the database to disconnect. This helps ensure that clients maintain an accurate view of the replica set.

New in version 2.0: If there is no secondary within 10 seconds of the primary, replSetStepDown will not succeed to prevent long running elections.

Example

The following example specifies that the former primary avoids reelection to primary for 120 seconds:

db.runCommand( { replSetStepDown: 120 } )

replSetSyncFrom

Description

replSetSyncFrom

New in version 2.2.

Explicitly configures which host the current mongod pulls oplog entries from. This operation is useful for testing different patterns and in situations where a set member is not replicating from the desired host.

The replSetSyncFrom command has the following form:

{ replSetSyncFrom: "hostname<:port>" }

The replSetSyncFrom command has the following field:

Field | Description
replSetSyncFrom | The name and port number of the replica set member that this member should replicate from. Use the [hostname]:[port] form.

field string replSetSyncFrom:

The name and port number of the replica set member that this member should replicate from. Use the [hostname]:[port] form.

For more information the use of replSetSyncFrom, see Configure a Secondary’s Sync Target.

resync

resync

The resync command forces an out-of-date slave mongod instance to re-synchronize itself. Note that this command is relevant to master-slave replication only. It does not apply to replica sets.

Warning

This command obtains a global write lock and will block other operations until it has completed.

applyOps

Definition

applyOps

Applies specified oplog entries to a mongod instance. The applyOps command is primarily an internal command.

If authorization is enabled, you must have access to all actions on all resources in order to run applyOps. Providing such access is not recommended, but if your organization requires a user to run applyOps, create a role that grants anyAction on anyResource. Do not assign this role to any other user.

The applyOps command has the following prototype form:

db.runCommand( { applyOps: [ <operations> ],
                 preCondition: [ { ns: <namespace>, q: <query>, res: <result> } ] } )

The applyOps command takes a document with the following fields:

Field
Description

applyOps
The oplog entries to apply.

preCondition
Optional. An array of documents that contain the conditions that must be true in order to apply the oplog entry. Each document contains a set of conditions, as described in the next table.

alwaysUpsert
Optional. A flag that indicates whether to apply update operations in the oplog as ref:upserts <write-operations-upsert-behavior>. When true, all updates become upserts to prevent failures as a results of sequences of updates followed by deletes: this is the same mode of operation as normal replication in secondaries. When false, updates are applied unmodified: this is the same mode of operation used during initial sync operations. true by default.

field array applyOps:

The oplog entries to apply.

field array preCondition:

Optional. An array of documents that contain the conditions that must be true in order to apply the oplog entry. Each document contains a set of conditions, as described in the next table.

field array alwaysUpsert:

Optional. A flag that indicates whether to apply update operations in the oplog as ref:upserts <write-operations-upsert-behavior>. When true, all updates become upserts to prevent failures as a results of sequences of updates followed by deletes: this is the same mode of operation as normal replication in secondaries. When false, updates are applied unmodified: this is the same mode of operation used during initial sync operations. true by default.

The preCondition array takes one or more documents with the following fields:

Field | Description
ns | A namespace. If you use this field, applyOps applies oplog entries only for the collection described by this namespace.
q | Specifies the query that produces the results specified in the res field.
res | The results of the query in the q field that must match to apply the oplog entry.

field string ns:
| A namespace. If you use this field, applyOps applies oplog entries only for the collection described by this namespace.
field string q: | Specifies the query that produces the results specified in the res field.
field string res:
| The results of the query in the q field that must match to apply the oplog entry.

Behavior

Warning

This command obtains a global write lock and will block other operations until it has completed.

isMaster

Definition

isMaster

isMaster returns a document that describes the role of the mongod instance.

If the instance is a member of a replica set, then isMaster returns a subset of the replica set configuration and status including whether or not the instance is the primary of the replica set.

When sent to a mongod instance that is not a member of a replica set, isMaster returns a subset of this information.

MongoDB drivers and clients use isMaster to determine the state of the replica set members and to discover additional members of a replica set.

The db.isMaster() method in the mongo shell provides a wrapper around isMaster.

The command takes the following form:

{ isMaster: 1 }

See also

db.isMaster()

Output

All Instances

The following isMaster fields are common across all roles:

isMaster.ismaster

A boolean value that reports when this node is writable. If true, then this instance is a primary in a replica set, or a master in a master-slave configuration, or a mongos instance, or a standalone mongod.

This field will be false if the instance is a secondary member of a replica set or if the member is an arbiter of a replica set.

isMaster.maxBsonObjectSize

The maximum permitted size of a BSON object in bytes for this mongod process. If not provided, clients should assume a max size of “16 * 1024 * 1024”.

isMaster.maxMessageSizeBytes

New in version 2.4.

The maximum permitted size of a BSON wire protocol message. The default value is 48000000 bytes.

isMaster.localTime

New in version 2.2.

Returns the local server time in UTC. This value is an ISO date.

isMaster.minWireVersion

New in version 2.6.

The earliest version of the wire protocol that this mongod or mongos instance is capable of using to communicate with clients.

Clients may use minWireVersion to help negotiate compatibility with MongoDB.

isMaster.maxWireVersion

New in version 2.6.

The latest version of the wire protocol that this mongod or mongos instance is capable of using to communicate with clients.

Clients may use maxWireVersion to help negotiate compatibility with MongoDB.

Sharded Instances

mongos instances add the following field to the isMaster response document:

isMaster.msg

Contains the value isdbgrid when isMaster returns from a mongos instance.

Replica Sets

isMaster contains these fields when returned by a member of a replica set:

isMaster.setName

The name of the current :replica set.

isMaster.secondary

A boolean value that, when true, indicates if the mongod is a secondary member of a replica set.

isMaster.hosts

An array of strings in the format of "[hostname]:[port]" that lists all members of the replica set that are neither hidden, passive, nor arbiters.

Drivers use this array and the isMaster.passives to determine which members to read from.

isMaster.passives

An array of strings in the format of "[hostname]:[port]" listing all members of the replica set which have a priority of 0.

This field only appears if there is at least one member with a priority of 0.

Drivers use this array and the isMaster.hosts to determine which members to read from.

isMaster.arbiters

An array of strings in the format of "[hostname]:[port]" listing all members of the replica set that are arbiters.

This field only appears if there is at least one arbiter in the replica set.

isMaster.primary

A string in the format of "[hostname]:[port]" listing the current primary member of the replica set.

isMaster.arbiterOnly

A boolean value that , when true, indicates that the current instance is an arbiter. The arbiterOnly field is only present, if the instance is an arbiter.

isMaster.passive

A boolean value that, when true, indicates that the current instance is passive. The passive field is only present for members with a priority of 0.

isMaster.hidden

A boolean value that, when true, indicates that the current instance is hidden. The hidden field is only present for hidden members.

isMaster.tags

A document that lists any tags assigned to this member. This field is only present if there are tags assigned to the member. See Configure Replica Set Tag Sets for more information.

isMaster.me

The [hostname]:[port] of the member that returned isMaster.

getoptime

getoptime

getoptime is an internal command.

Sharding Commands

Name | Description
flushRouterConfig | Forces an update to the cluster metadata cached by a mongos.
addShard | Adds a shard to a sharded cluster.
cleanupOrphaned | Removes orphaned data with shard key values outside of the ranges of the chunks owned by a shard.
checkShardingIndex | Internal command that validates index on shard key.
enableSharding | Enables sharding on a specific database.
listShards | Returns a list of configured shards.
removeShard | Starts the process of removing a shard from a sharded cluster.
getShardMap | Internal command that reports on the state of a sharded cluster.
getShardVersion | Internal command that returns the config server version.
mergeChunks | Provides the ability to combine chunks on a single shard.
setShardVersion | Internal command to sets the config server version.
shardCollection | Enables the sharding functionality for a collection, allowing the collection to be sharded.
shardingState | Reports whether the mongod is a member of a sharded cluster.
unsetSharding | Internal command that affects connections between instances in a MongoDB deployment.
split | Creates a new chunk.
splitChunk | Internal command to split chunk. Instead use the methods sh.splitFind() and sh.splitAt().
splitVector | Internal command that determines split points.
medianKey | Deprecated internal command. See splitVector.
moveChunk | Internal command that migrates chunks between shards.
movePrimary | Reassigns the primary shard when removing a shard from a sharded cluster.
isdbgrid | Verifies that a process is a mongos.

flushRouterConfig

addShard

cleanupOrphaned

checkShardingIndex

enableSharding

listShards

removeShard

getShardMap

getShardVersion

mergeChunks

setShardVersion

shardCollection

shardingState

unsetSharding

split

splitChunk

splitVector

medianKey

moveChunk

movePrimary

isdbgrid

flushRouterConfig

flushRouterConfig

flushRouterConfig clears the current cluster information cached by a mongos instance and reloads all sharded cluster metadata from the config database.

This forces an update when the configuration database holds data that is newer than the data cached in the mongos process.

Warning

Do not modify the config data, except as explicitly documented. A config database cannot typically tolerate manual manipulation.

flushRouterConfig is an administrative command that is only available for mongos instances.

New in version 1.8.2.

addShard

Definition

addShard

Adds either a database instance or a replica set to a sharded cluster. The optimal configuration is to deploy shards across replica sets.

Run addShard when connected to a mongos instance. The command takes the following form when adding a single database instance as a shard:

{ addShard: "<hostname><:port>", maxSize: <size>, name: "<shard_name>" }

When adding a replica set as a shard, use the following form:

{ addShard: "<replica_set>/<hostname><:port>", maxSize: <size>, name: "<shard_name>" }

The command contains the following fields:

Field | Description
addShard | The hostname and port of the mongod instance to be added as a shard. To add a replica set as a shard, specify the name of the replica set and the hostname and port of a member of the replica set.
maxSize | Optional. The maximum size in megabytes of the shard. If you set maxSize to 0, MongoDB does not limit the size of the shard.
name | Optional. A name for the shard. If this is not specified, MongoDB automatically provides a unique name.

field string addShard:
| The hostname and port of the mongod instance to be added as a shard. To add a replica set as a shard, specify the name of the replica set and the hostname and port of a member of the replica set.
field integer maxSize:
| Optional. The maximum size in megabytes of the shard. If you set maxSize to 0, MongoDB does not limit the size of the shard.
field string name:
| Optional. A name for the shard. If this is not specified, MongoDB automatically provides a unique name.

The addShard command stores shard configuration information in the config database. Always run addShard when using the admin database.

Specify a maxSize when you have machines with different disk capacities, or if you want to limit the amount of data on some shards. The maxSize constraint prevents the balancer from migrating chunks to the shard when the value of mem.mapped exceeds the value of maxSize.

Considerations

Balancing

When you add a shard to a sharded cluster, you affect the balance of chunks among the shards of a cluster for all existing sharded collections. The balancer will begin migrating chunks so that the cluster will achieve balance. See Sharded Collection Balancing for more information.

Hidden Members

Important

You cannot include a hidden member in the seed list provided to addShard.

Examples

The following command adds the database instance running on port 27027 on the host mongodb0.example.net as a shard:

use admin
db.runCommand({addShard: "mongodb0.example.net:27027"})

Warning

Do not use localhost for the hostname unless your configuration server is also running on localhost.

The following command adds a replica set as a shard:

use admin
db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} )

You may specify all members in the replica set. All additional hostnames must be members of the same replica set.

cleanupOrphaned

Definition

cleanupOrphaned

New in version 2.6.

Deletes from a shard the orphaned documents whose shard key values fall into a single or a single contiguous range that do not belong to the shard. For example, if two contiguous ranges do not belong to the shard, the cleanupOrphaned examines both ranges for orphaned documents.

cleanupOrphaned has the following syntax:

db.runCommand( {
   cleanupOrphaned: "<database>.<collection>",
   startingFromKey: <minimumShardKeyValue>,
   secondaryThrottle: <boolean>
} )

cleanupOrphaned has the following fields:

Field
Description

cleanupOrphaned
The namespace, i.e. both the database and the collection name, of the sharded collection for which to clean the orphaned data.

startingFromKey

Optional. The shard key value that determines the lower bound of the cleanup range. The default value is MinKey.

If the range that contains the specified startingFromKey value belongs to a chunk owned by the shard, cleanupOrphaned continues to examine the next ranges until it finds a range not owned by the shard. See Determine Range for details.

secondaryThrottle

Optional. If true, each delete operation must be replicated to another secondary before the cleanup operation proceeds further. If false, do not wait for replication. Defaults to false.

Independent of the secondaryThrottle setting, after the final delete, cleanupOrphaned waits for all deletes to replicate to a majority of replica set members before returning.

field string cleanupOrphaned:

The namespace, i.e. both the database and the collection name, of the sharded collection for which to clean the orphaned data.

field document startingFromKey:

Optional. The shard key value that determines the lower bound of the cleanup range. The default value is MinKey.

If the range that contains the specified startingFromKey value belongs to a chunk owned by the shard, cleanupOrphaned continues to examine the next ranges until it finds a range not owned by the shard. See Determine Range for details.

field boolean secondaryThrottle:

Optional. If true, each delete operation must be replicated to another secondary before the cleanup operation proceeds further. If false, do not wait for replication. Defaults to false.

Independent of the secondaryThrottle setting, after the final delete, cleanupOrphaned waits for all deletes to replicate to a majority of replica set members before returning.

Behavior

Run cleanupOrphaned in the admin database directly on the mongod instance that is the primary replica set member of the shard. Do not run cleanupOrphaned on a mongos instance.

You do not need to disable the balancer before running cleanupOrphaned.

Determine Range

The cleanupOrphaned command uses the startingFromKey value, if specified, to determine the start of the range to examine for orphaned document:

If the startingFromKey value falls into a range for a chunk not owned by the shard, cleanupOrphaned begins examining at the start of this range, which may not necessarily be the startingFromKey.

If the startingFromKey value falls into a range for a chunk owned by the shard, cleanupOrphaned moves onto the next range until it finds a range for a chunk not owned by the shard.

The cleanupOrphaned deletes orphaned documents from the start of the determined range and ends at the start of the chunk range that belongs to the shard.

Consider the following key space with documents distributed across Shard A and Shard B.

Shard A owns:

Chunk 1 with the range { x: minKey } --> { x: -75 },

Chunk 2 with the range { x: -75 } --> { x: 25 }, and

Chunk 4 with the range { x: 175 } --> { x: 200 }.

Shard B owns:

Chunk 3 with the range { x: 25 } --> { x: 175 } and

Chunk 5 with the range { x: 200 } --> { x: maxKey }.

If on Shard A, the cleanupOrphaned command runs with startingFromKey: { x: -70 } or any other value belonging to range for Chunk 1 or Chunk 2, the cleanupOrphaned command examines the Chunk 3 range of { x: 25 } --> { x: 175 } to delete orphaned data.

If on Shard B, the cleanupOrphaned command runs with the startingFromKey: { x: -70 } or any other value belonging to range for Chunk 1, the cleanupOrphaned command examines the combined contiguous range for Chunk 1 and Chunk 2, namely { x: minKey } --> { x: 25 } to delete orphaned data.

Required Access

On systems running with authorization, you must have clusterAdmin privileges to run cleanupOrphaned.

Output

Return Document

Each cleanupOrphaned command returns a document containing a subset of the following fields:

cleanupOrphaned.ok

Equal to 1 on success.

A value of 1 indicates that cleanupOrphaned scanned the specified shard key range, deleted any orphaned documents found in that range, and confirmed that all deletes replicated to a majority of the members of that shard’s replica set. If confirmation does not arrive within 1 hour, cleanupOrphaned times out.

A value of 0 could indicate either of two cases:

cleanupOrphaned found orphaned documents on the shard but could not delete them.

cleanupOrphaned found and deleted orphaned documents, but could not confirm replication before the 1 hour timeout. In this case, replication does occur but only after cleanupOrphaned returns.

cleanupOrphaned.stoppedAtKey

The upper bound of the cleanup range of shard keys. If present, the value corresponds to the lower bound of the next chunk on the shard. The absence of the field signifies that the cleanup range was the uppermost range for the shard.

Log Files

The cleanupOrphaned command prints the number of deleted documents to the mongod log. For example:

m30000| 2013-10-31T15:17:28.972-0400 [conn1] Deleter starting delete for: foo.bar from { _id: -35.0 } -> { _id: -10.0 }, with opId: 128
m30000| 2013-10-31T15:17:28.972-0400 [conn1] rangeDeleter deleted 0 documents for foo.bar from { _id: -35.0 } -> { _id: -10.0 } { "stoppedAtKey": { "_id": -10 }, "ok": 1 }

Examples

The following examples run the cleanupOrphaned command directly on the primary of the shard.

Remove Orphaned Documents for a Specific Range

For a sharded collection info in the test database, a shard owns a single chunk with the range: { x: MinKey } --> { x: 10 }.

The shard also contains documents whose shard keys values fall in a range for a chunk not owned by the shard: { x: 10 } --> { x: MaxKey }.

To remove orphaned documents within the { x: 10 } => { x: MaxKey } range, you can specify a startingFromKey with a value that falls into this range, as in the following example:

use admin
db.runCommand( {
   "cleanupOrphaned": "test.info",
   "startingFromKey": { x: 10 },
   "secondaryThrottle": true
} )

Or you can specify a startingFromKey with a value that falls into the previous range, as in the following:

use admin
db.runCommand( {
   "cleanupOrphaned": "test.info",
   "startingFromKey": { x: 2 },
   "secondaryThrottle": true
} )

Since { x: 2 } falls into a range that belongs to a chunk owned by the shard, cleanupOrphaned examines the next range to find a range not owned by the shard, in this case { x: 10 } => { x: MaxKey }.

Remove All Orphaned Documents from a Shard

cleanupOrphaned examines documents from a single contiguous range of shard keys. To remove all orphaned documents from the shard, you can run cleanupOrphaned in a loop, using the returned stoppedAtKey as the next startingFromKey, as in the following:

use admin
var nextKey = { };
var result;

while ( nextKey != null ) {
  result = db.runCommand( { cleanupOrphaned: "test.user", startingFromKey: nextKey } );

  if (result.ok != 1)
     print("Unable to complete at this time: failure or timeout.")

  printjson(result);

  nextKey = result.stoppedAtKey;
}

checkShardingIndex

checkShardingIndex

checkShardingIndex is an internal command that supports the sharding functionality.

enableSharding

enableSharding

The enableSharding command enables sharding on a per-database level. Use the following command form:

{ enableSharding: "<database name>" }

Once you’ve enabled sharding in a database, you can use the shardCollection command to begin the process of distributing data among the shards.

listShards

Definition

listShards

Returns a list of the configured shards. listShards is only available for mongos instances. You can only issue listShards against the admin database.

The command takes the following form:

{ listShards: 1 }

Example

The following example returns the list of shards:

db.getSiblingDB("admin").runCommand( { listShards: 1 } )

removeShard

removeShard

Removes a shard from a sharded cluster. When you run removeShard, MongoDB first moves the shard’s chunks to other shards in the cluster. Then MongoDB removes the shard.

Behavior

Access Requirements

You must run removeShard while connected to a mongos. Issue the command against the admin database or use the sh._adminCommand() helper.

If you have authorization enabled, you must have the clusterManager role or any role that includes the removeShard action.

Database Migration Requirements

Each database in a sharded cluster has a primary shard. If the shard you want to remove is also the primary of one of the cluster’s databases, then you must manually move the databases to a new shard after migrating all data from the shard. See the movePrimary command and the Remove Shards from an Existing Sharded Cluster for more information.

Example

From the mongo shell, the removeShard operation resembles the following:

use admin
db.runCommand( { removeShard : "bristol01" } )

Replace bristol01 with the name of the shard to remove. When you run removeShard, the command returns immediately, with the following message:

{
    "msg" : "draining started successfully",
    "state" : "started",
    "shard" : "bristol01",
    "ok" : 1
}

The balancer begins migrating chunks from the shard named bristol01 to other shards in the cluster. These migrations happens slowly to avoid placing undue load on the overall cluster.

If you run the command again, removeShard returns the following progress output:

{
    "msg" : "draining ongoing",
    "state" : "ongoing",
    "remaining" : {
        "chunks" : 23,
        "dbs" : 1
    },
    "ok" : 1
}

The remaining document specifies how many chunks and databases remain on the shard. Use db.printShardingStatus() to list the databases that you must move from the shard. Use the movePrimary to move databases.

After removing all chunks and databases from the shard, you can issue removeShard again see the following:

{
    "msg" : "removeshard completed successfully",
    "state" : "completed",
    "shard" : "bristol01",
    "ok" : 1
}

getShardMap

getShardMap

getShardMap is an internal command that supports the sharding functionality.

getShardVersion

getShardVersion

getShardVersion is a command that supports sharding functionality and is not part of the stable client facing API.

mergeChunks

Definition

mergeChunks

For a sharded collection, mergeChunks combines two contiguous chunk ranges the same shard into a single chunk. At least one of chunk must not have any documents. Issue the mergeChunks command from a mongos instance.

mergeChunks has the following form:

db.runCommand( { mergeChunks : <namespace> ,
                 bounds : [ { <shardKeyField>: <minFieldValue> },
                            { <shardKeyField>: <maxFieldValue> } ] } )

For compound shard keys, you must include the full shard key in the bounds specification. If the shard key is { x: 1, y: 1 }, mergeChunks has the following form:

db.runCommand( { mergeChunks : <namespace> ,
                 bounds : [ { x: <minValue>, y: <minValue> },
                            { x: <maxValue>, y: <maxValue> } ] } )

The mergeChunks command has the following fields:

Field | Description
mergeChunks | The fully qualified namespace of the collection where both chunks exist. Namespaces take form of <database>.<collection>.
bounds | An array that contains the minimum and maximum key values of the new chunk.

field namespace mergeChunks:
| The fully qualified namespace of the collection where both chunks exist. Namespaces take form of <database>.<collection>.
field array bounds:
| An array that contains the minimum and maximum key values of the new chunk.

Behavior

Note

Use the mergeChunks only in special circumstances such as cleaning up your sharded cluster after removing many documents.

In order to successfully merge chunks, the following must be true

In the bounds field, <minkey> and <maxkey> must correspond to the lower and upper bounds of the chunks to merge.

The two chunks must reside on the same shard.

The two chunks must be contiguous.

One or both chunks must be empty.

mergeChunks returns an error if these conditions are not satisfied.

Return Messages

On success, mergeChunks returns to following document:

{ "ok" : 1 }

Another Operation in Progress

mergeChunks returns the following error message if another metadata operation is in progress on the chunks collection:

errmsg: "The collection's metadata lock is already taken."

If another process, such as balancer process, changes metadata while mergeChunks is running, you may see this error. You can retry the mergeChunks operation without side effects.

Chunks on Different Shards

If the input chunks are not on the same shard, mergeChunks returns an error similar to the following:

{
   "ok" : 0,
   "errmsg" : "could not merge chunks, collection test.users does not contain a chunk ending at { username: \"user63169\" }"
}

Noncontiguous Chunks

If the input chunks are not contiguous, mergeChunks returns an error similar to the following:

{
   "ok" : 0,
   "errmsg" : "could not merge chunks, collection test.users has more than 2 chunks between [{ username: \"user29937\" }, { username: \"user49877\" })"
}

Documents in Both Chunks

If neither input chunk is empty, mergeChunks returns an error similar to the following:

{
   "ok" : 0,
   "errmsg" : "could not merge chunks, collection test.users has more than one non-empty chunk between [{ username: \"user36583\" }, { username: \"user49877\" })"
}

setShardVersion

setShardVersion

setShardVersion is an internal command that supports sharding functionality.

shardCollection

Definition

shardCollection

Enables a collection for sharding and allows MongoDB to begin distributing data among shards. You must run enableSharding on a database before running the shardCollection command. shardCollection has the following form:

{ shardCollection: "<database>.<collection>", key: <shardkey> }

shardCollection has the following fields:

Field
Description

shardCollection
The namespace of the collection to shard in the form <database>.<collection>.

key
The index specification document to use as the shard key. The index must exist prior to the shardCollection command, unless the collection is empty. If the collection is empty, in which case MongoDB creates the index prior to sharding the collection. New in version 2.4: The key may be in the form { field : "hashed" }, which will use the specified field as a hashed shard key.

unique
When true, the unique option ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints.

numInitialChunks
Specifies the number of chunks to create initially when sharding an empty collection with a hashed shard key. MongoDB will then create and balance chunks across the cluster. The numInitialChunks must be less than 8192 per shard. If the collection is not empty, numInitialChunks has no effect.

field string shardCollection:

The namespace of the collection to shard in the form <database>.<collection>.

field document key:

The index specification document to use as the shard key. The index must exist prior to the shardCollection command, unless the collection is empty. If the collection is empty, in which case MongoDB creates the index prior to sharding the collection. New in version 2.4: The key may be in the form { field : "hashed" }, which will use the specified field as a hashed shard key.

field Boolean unique:

When true, the unique option ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints.

field integer numInitialChunks:

Specifies the number of chunks to create initially when sharding an empty collection with a hashed shard key. MongoDB will then create and balance chunks across the cluster. The numInitialChunks must be less than 8192 per shard. If the collection is not empty, numInitialChunks has no effect.

Considerations

Use

Do not run more than one shardCollection command on the same collection at the same time.

MongoDB provides no method to deactivate sharding for a collection after calling shardCollection. Additionally, after shardCollection, you cannot change shard keys or modify the value of any field used in your shard key index.

Shard Keys

Choosing the best shard key to effectively distribute load among your shards requires some planning. Review Shard Keys regarding choosing a shard key.

Hashed Shard Keys

New in version 2.4.

Hashed shard keys use a hashed index of a single field as the shard key.

Note

If chunk migrations are in progress while creating a hashed shard key collection, the initial chunk distribution may be uneven until the balancer automatically balances the collection.

Example

The following operation enables sharding for the people collection in the records database and uses the zipcode field as the shard key:

db.runCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )

Additional Information

Sharding, Sharding Concepts, and Deploy a Sharded Cluster.

shardingState

shardingState

shardingState is an admin command that reports if mongod is a member of a sharded cluster. shardingState has the following prototype form:

{ shardingState: 1 }

For shardingState to detect that a mongod is a member of a sharded cluster, the mongod must satisfy the following conditions:

the mongod is a primary member of a replica set, and

the mongod instance is a member of a sharded cluster.

If shardingState detects that a mongod is a member of a sharded cluster, shardingState returns a document that resembles the following prototype:

{
  "enabled" : true,
  "configServer" : "<configdb-string>",
  "shardName" : "<string>",
  "shardHost" : "string:",
  "versions" : {
       "<database>.<collection>" : Timestamp(<...>),
       "<database>.<collection>" : Timestamp(<...>)
  },
  "ok" : 1
}

Otherwise, shardingState will return the following document:

{ "note" : "from execCommand", "ok" : 0, "errmsg" : "not master" }

The response from shardingState when used with a config server is:

{ "enabled": false, "ok": 1 }

Note

mongos instances do not provide the shardingState.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed; however, the operation is typically short lived.

unsetSharding

unsetSharding

unsetSharding is an internal command that supports sharding functionality.

split

Definition

split

Splits a chunk in a sharded cluster into two chunks. The mongos instance splits and manages chunks automatically, but for exceptional circumstances the split command does allow administrators to manually create splits. See Split Chunks in a Sharded Cluster for information on these circumstances, and on the MongoDB shell commands that wrap split.

The split command uses the following form:

db.adminCommand( { split: <database>.<collection>,
                   <find|middle|bounds> } )

The split command takes a document with the following fields:

Field
Description

split
The name of the collection where the chunk exists. Specify the collection’s full namespace, including the database name.

find

An query statement that specifies an equality match on the shard key. The match selects the chunk that contains the specified document. You must specify only one of the following: find, bounds, or middle.

You cannot use the find option on an empty collection.

bounds

New in version 2.4: The bounds of a chunk to split. bounds applies to chunks in collections partitioned using a hashed shard key. The parameter’s array must consist of two documents specifying the lower and upper shard-key values of the chunk. The values must match the minimum and maximum values of an existing chunk. Specify only one of the following: find, bounds, or middle.

You cannot use the bounds option on an empty collection.

middle
The document to use as the split point to create two chunks. split requires one of the following options: find, bounds, or middle.

field string split:

The name of the collection where the chunk exists. Specify the collection’s full namespace, including the database name.

field document find:

An query statement that specifies an equality match on the shard key. The match selects the chunk that contains the specified document. You must specify only one of the following: find, bounds, or middle.

You cannot use the find option on an empty collection.

field array bounds:

New in version 2.4: The bounds of a chunk to split. bounds applies to chunks in collections partitioned using a hashed shard key. The parameter’s array must consist of two documents specifying the lower and upper shard-key values of the chunk. The values must match the minimum and maximum values of an existing chunk. Specify only one of the following: find, bounds, or middle.

You cannot use the bounds option on an empty collection.

field document middle:

The document to use as the split point to create two chunks. split requires one of the following options: find, bounds, or middle.

Considerations

When used with either the find or the bounds option, the split command splits the chunk along the median. As such, the command cannot use the find or the bounds option to split an empty chunk since an empty chunk has no median.

To create splits in empty chunks, use either the middle option with the split command or use the splitAt command.

Command Formats

To create a chunk split, connect to a mongos instance, and issue the following command to the admin database:

db.adminCommand( { split: <database>.<collection>,
                   find: <document> } )

Or:

db.adminCommand( { split: <database>.<collection>,
                   middle: <document> } )

Or:

db.adminCommand( { split: <database>.<collection>,
                   bounds: [ <lower>, <upper> ] } )

To create a split for a collection that uses a hashed shard key, use the bounds parameter. Do not use the middle parameter for this purpose.

Warning

Be careful when splitting data in a sharded collection to create new chunks. When you shard a collection that has existing data, MongoDB automatically creates chunks to evenly distribute the collection. To split data effectively in a sharded cluster you must consider the number of documents in a chunk and the average document size to create a uniform chunk size. When chunks have irregular sizes, shards may have an equal number of chunks but have very different data sizes. Avoid creating splits that lead to a collection with differently sized chunks.

See also

moveChunk, sh.moveChunk(), sh.splitAt(), and sh.splitFind(), which wrap the functionality of split.

Examples

The following sections provide examples of the split command.

Split a Chunk in Half

db.runCommand( { split : "test.people", find : { _id : 99 } } )

The split command identifies the chunk in the people collection of the test database, that holds documents that match { _id : 99 }. split does not require that a match exist, in order to identify the appropriate chunk. Then the command splits it into two chunks of equal size.

Note

split creates two equal chunks by range as opposed to size, and does not use the selected point as a boundary for the new chunks

Define an Arbitrary Split Point

To define an arbitrary split point, use the following form:

db.runCommand( { split : "test.people", middle : { _id : 99 } } )

The split command identifies the chunk in the people collection of the test database, that would hold documents matching the query { _id : 99 }. split does not require that a match exist, in order to identify the appropriate chunk. Then the command splits it into two chunks, with the matching document as the lower bound of one of the split chunks.

This form is typically used when pre-splitting data in a collection.

Split a Chunk Using Values of a Hashed Shard Key

This example uses the hashed shard key userid in a people collection of a test database. The following command uses an array holding two single-field documents to represent the minimum and maximum values of the hashed shard key to split the chunk:

db.runCommand( { split: "test.people",
                  bounds : [ { userid: NumberLong("-5838464104018346494") },
                             { userid: NumberLong("-5557153028469814163") }
             ] } )

Note

MongoDB uses the 64-bit NumberLong type to represent the hashed value.

Use sh.status() to see the existing bounds of the shard keys.

Metadata Lock Error

If another process in the mongos, such as a balancer process, changes metadata while split is running, you may see a metadata lock error.

errmsg: "The collection's metadata lock is already taken."

This message indicates that the split has failed with no side effects. Retry the split command.

splitChunk

Definition

splitChunk

An internal administrative command. To split chunks, use the sh.splitFind() and sh.splitAt() functions in the mongo shell.

Warning

Be careful when splitting data in a sharded collection to create new chunks. When you shard a collection that has existing data, MongoDB automatically creates chunks to evenly distribute the collection. To split data effectively in a sharded cluster you must consider the number of documents in a chunk and the average document size to create a uniform chunk size. When chunks have irregular sizes, shards may have an equal number of chunks but have very different data sizes. Avoid creating splits that lead to a collection with differently sized chunks.

See also

moveChunk and sh.moveChunk().

The splitChunk command takes a document with the following fields:

Field | Description
ns | The complete namespace of the chunk to split.
keyPattern | The shard key.
min | The lower bound of the shard key for the chunk to split.
max | The upper bound of the shard key for the chunk to split.
from | The shard that owns the chunk to split.
splitKeys | The split point for the chunk.
shardId | The shard.

field string ns:
| The complete namespace of the chunk to split.
field document keyPattern:
| The shard key.
field document min:
| The lower bound of the shard key for the chunk to split.
field document max:
| The upper bound of the shard key for the chunk to split.
field string from:
| The shard that owns the chunk to split.
field document splitKeys:
| The split point for the chunk.
field document shardId:
| The shard.

splitVector

splitVector

Is an internal command that supports meta-data operations in sharded clusters.

medianKey

medianKey

medianKey is an internal command.

moveChunk

Definition

moveChunk

Internal administrative command. Moves chunks between shards. Issue the moveChunk command via a mongos instance while using the admin database. Use the following forms:

db.runCommand( { moveChunk : <namespace> ,
                 find : <query> ,
                 to : <string>,
                 _secondaryThrottle : <boolean>,
                 _waitForDelete : <boolean> } )

Alternately:

db.runCommand( { moveChunk : <namespace> ,
                 bounds : <array> ,
                 to : <string>,
                 _secondaryThrottle : <boolean>,
                 _waitForDelete : <boolean> } )

The moveChunk command has the following fields:

Field | Description
moveChunk | The namespace of the collection where the chunk exists. Specify the collection’s full namespace, including the database name.
find | An equality match on the shard key that specifies the shard-key value of the chunk to move. Specify either the bounds field or the find field but not both. Do not use the find field to select chunks in collections that use a hashed shard key.
bounds | The bounds of a specific chunk to move. The array must consist of two documents that specify the lower and upper shard key values of a chunk to move. Specify either the bounds field or the find field but not both. Use bounds to select chunks in collections that use a hashed shard key.
to | The name of the destination shard for the chunk.
_secondaryThrottle | Optional. Defaults to false. When true, the balancer waits for replication to secondaries when it copies and deletes data during chunk migrations. For details, see Change Replication Behavior for Chunk Migration (Secondary Throttle).
_waitForDelete | Optional. Internal option for testing purposes. The default is false. If set to true, the delete phase of a moveChunk operation blocks.

field string moveChunk:
| The namespace of the collection where the chunk exists. Specify the collection’s full namespace, including the database name.
field document find:
| An equality match on the shard key that specifies the shard-key value of the chunk to move. Specify either the bounds field or the find field but not both. Do not use the find field to select chunks in collections that use a hashed shard key.
field array bounds:
| The bounds of a specific chunk to move. The array must consist of two documents that specify the lower and upper shard key values of a chunk to move. Specify either the bounds field or the find field but not both. Use bounds to select chunks in collections that use a hashed shard key.
field string to:
| The name of the destination shard for the chunk.
field Boolean _secondaryThrottle:
| Optional. Defaults to false. When true, the balancer waits for replication to secondaries when it copies and deletes data during chunk migrations. For details, see Change Replication Behavior for Chunk Migration (Secondary Throttle).
field Boolean _waitForDelete:
| Optional. Internal option for testing purposes. The default is false. If set to true, the delete phase of a moveChunk operation blocks.

The value of bounds takes the form:

[ { hashedField : <minValue> } ,
  { hashedField : <maxValue> } ]

The chunk migration section describes how chunks move between shards on MongoDB.

See also

split, sh.moveChunk(), sh.splitAt(), and sh.splitFind().

Return Messages

moveChunk returns the following error message if another metadata operation is in progress on the chunks collection:

errmsg: "The collection's metadata lock is already taken."

If another process, such as a balancer process, changes meta data while moveChunk is running, you may see this error. You may retry the moveChunk operation without side effects.

Note

Only use the moveChunk in special circumstances such as preparing your sharded cluster for an initial ingestion of data, or a large bulk import operation. In most cases allow the balancer to create and balance chunks in sharded clusters. See Create Chunks in a Sharded Cluster for more information.

movePrimary

movePrimary

In a sharded cluster, movePrimary reassigns the primary shard which holds all un-sharded collections in the database. movePrimary first changes the primary shard in the cluster metadata, and then migrates all un-sharded collections to the specified shard. Use the command with the following form:

{ movePrimary : "test", to : "shard0001" }

When the command returns, the database’s primary location will shift to the designated shard. To fully decommission a shard, use the removeShard command.

movePrimary is an administrative command that is only available for mongos instances.

Considerations

Behavior

Avoid accessing an un-sharded collection during migration. movePrimary does not prevent reading and writing during its operation, and such actions yield undefined behavior.

movePrimary may take significant time to complete, and you should plan for this unavailability.

movePrimary will fail if the destination shard contains a conflicting collection name. This may occur if documents are written to an un-sharded collection while the collection is moved away, and later the original primary shard is restored.

Use

If you use the movePrimary command to move un-sharded collections, you must either restart all mongos instances, or use the flushRouterConfig command on all mongos instances before writing any data to the cluster. This action notifies the mongos of the new shard for the database.

If you do not update the mongos instances’ metadata cache after using movePrimary, the mongos may not write data to the correct shard. To recover, you must manually intervene.

Additional Information

See Remove Shards from an Existing Sharded Cluster for a complete procedure.

isdbgrid

isdbgrid

This command verifies that a process is a mongos.

If you issue the isdbgrid command when connected to a mongos, the response document includes the isdbgrid field set to 1. The returned document is similar to the following:

{ "isdbgrid" : 1, "hostname" : "app.example.net", "ok" : 1 }

If you issue the isdbgrid command when connected to a mongod, MongoDB returns an error document. The isdbgrid command is not available to mongod. The error document, however, also includes a line that reads "isdbgrid" : 1, just as in the document returned for a mongos. The error document is similar to the following:

{
   "errmsg" : "no such cmd: isdbgrid",
   "bad cmd" : {
         "isdbgrid" : 1
   },
   "ok" : 0
}

You can instead use the isMaster command to determine connection to a mongos. When connected to a mongos, the isMaster command returns a document that contains the string isdbgrid in the msg field.

Administration Commands

Name | Description
renameCollection | Changes the name of an existing collection.
copydb | Copies a database from a remote host to the current host.
dropDatabase | Removes the current database.
drop | Removes the specified collection from the database.
create | Creates a collection and sets collection parameters.
clone | Copies a database from a remote host to the current host.
cloneCollection | Copies a collection from a remote host to the current host.
cloneCollectionAsCapped | Copies a non-capped collection as a new capped collection.
closeAllDatabases | Internal command that invalidates all cursors and closes open database files.
convertToCapped | Converts a non-capped collection to a capped collection.
filemd5 | Returns the md5 hash for files stored using GridFS.
createIndexes | Builds one or more indexes for a collection.
dropIndexes | Removes indexes from a collection.
fsync | Flushes pending writes to the storage layer and locks the database to allow backups.
clean | Internal namespace administration command.
connPoolSync | Internal command to flush connection pool.
connectionStatus | Reports the authentication state for the current connection.
compact | Defragments a collection and rebuilds the indexes.
collMod | Add flags to collection to modify the behavior of MongoDB.
reIndex | Rebuilds all indexes on a collection.
setParameter | Modifies configuration options.
getParameter | Retrieves configuration options.
repairDatabase | Repairs any errors and inconsistencies with the data storage.
touch | Loads documents and indexes from data storage to memory.
shutdown | Shuts down the mongod or mongos process.
logRotate | Rotates the MongoDB logs to prevent a single file from taking too much space.

renameCollection

copydb

dropDatabase

drop

create

clone

cloneCollection

cloneCollectionAsCapped

closeAllDatabases

convertToCapped

filemd5

createIndexes

dropIndexes

fsync

clean

connPoolSync

connectionStatus

compact

collMod

reIndex

setParameter

getParameter

repairDatabase

touch

shutdown

logRotate

renameCollection

Definition

renameCollection

Changes the name of an existing collection. Specify collections to renameCollection in the form of a complete namespace, which includes the database name. Issue the renameCollection command against the admin database. The command takes the following form:

{ renameCollection: "<source_namespace>", to: "<target_namespace>", dropTarget: <true|false> }

The command contains the following fields:

Field | Description
renameCollection | The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection.
to | The new namespace of the collection. If the new namespace specifies a different database, the renameCollection command copies the collection to the new database and drops the source collection.
dropTarget | Optional. If true, mongod will drop the target of renameCollection prior to renaming the collection.

field string renameCollection:
| The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection.
field string to:
| The new namespace of the collection. If the new namespace specifies a different database, the renameCollection command copies the collection to the new database and drops the source collection.
field boolean dropTarget:
| Optional. If true, mongod will drop the target of renameCollection prior to renaming the collection.

renameCollection is suitable for production environments; however:

renameCollection blocks all database activity for the duration of the operation.

renameCollection is not compatible with sharded collections.

Warning

renameCollection fails if target is the name of an existing collection and you do not specify dropTarget: true.

If the renameCollection operation does not complete the target collection and indexes will not be usable and will require manual intervention to clean up.

Exceptions

exception 10026:
| Raised if the source namespace does not exist.
exception 10027:
| Raised if the target namespace exists and dropTarget is either false or unspecified.
exception 15967:
| Raised if the target namespace is an invalid collection name.

Shell Helper

The shell helper db.collection.renameCollection() provides a simpler interface to using this command within a database. The following is equivalent to the previous example:

db.source-namespace.renameCollection( "target" )

Warning

You cannot use renameCollection with sharded collections.

Warning

This command obtains a global write lock and will block other operations until it has completed.

copydb

Definition

copydb

Copies a database from a remote host to the current host or copies a database to another database within the current host. Run copydb in the admin database of the destination server with the following syntax:

{ copydb: 1,
  fromhost: <hostname>,
  fromdb: <database>,
  todb: <database>,
  slaveOk: <bool>,
  username: <username>,
  nonce: <nonce>,
  key: <key> }

copydb accepts the following options:

Field | Description
fromhost | Optional. Hostname of the remote source mongod instance. Omit fromhost to copy from one database to another on the same server.
fromdb | Name of the source database.
todb | Name of the target database.
slaveOk | Optional. Set slaveOK to true to allow copydb to copy data from secondary members as well as the primary. fromhost must also be set.
username | Optional. The username credentials on the fromhost MongoDB deployment.
nonce | Optional. A single use shared secret generated on the remote server, i.e. fromhost, using the copydbgetnonce command. See Authentication for details.
key | Optional. A hash of the password used for authentication. See Authentication for details.

field string fromhost:
| Optional. Hostname of the remote source mongod instance. Omit fromhost to copy from one database to another on the same server.
field string fromdb:
| Name of the source database.
field string todb:
| Name of the target database.
field boolean slaveOk:
| Optional. Set slaveOK to true to allow copydb to copy data from secondary members as well as the primary. fromhost must also be set.
field string username:
| Optional. The username credentials on the fromhost MongoDB deployment.
field string nonce:
| Optional. A single use shared secret generated on the remote server, i.e. fromhost, using the copydbgetnonce command. See Authentication for details.
field string key:
| Optional. A hash of the password used for authentication. See Authentication for details.

The mongo shell provides the db.copyDatabase() wrapper for the copydb command.

Behavior

Be aware of the following properties of copydb:

copydb runs on the destination mongod instance, i.e. the host receiving the copied data.

If the destination mongod has authorization enabled, copydb must specify the credentials of a user present in the source database who has the privileges described in Required Access.

copydb creates the target database if it does not exist.

copydb requires enough free disk space on the host instance for the copied database. Use the db.stats() operation to check the size of the database on the source mongod instance.

copydb and clone do not produce point-in-time snapshots of the source database. Write traffic to the source or destination database during the copy process will result in divergent data sets.

copydb does not lock the destination server during its operation, so the copy will occasionally yield to allow other operations to complete.

Required Access

Changed in version 2.6.

On systems running with authorization, the copydb command requires the following authorization on the target and source databases.

Source Database (fromdb)

Source is non-admin Database

If the source database is a non-admin database, you must have privileges that specify find action on the source database, and find action on the system.js collection in the source database. For example:

{ resource: { db: "mySourceDB", collection: "" }, actions: [ "find" ] }
{ resource: { db: "mySourceDB", collection: "system.js" }, actions: [ "find" ] }

If the source database is on a remote server, you also need the find action on the system.indexes and system.namespaces collections in the source database; e.g.

{ resource: { db: "mySourceDB", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "mySourceDB", collection: "system.namespaces" }, actions: [ "find" ] }

Source is admin Database

If the source database is the admin database, you must have privileges that specify find action on the admin database, and find action on the system.js, system.users, system.roles, and system.version collections in the admin database. For example:

{ resource: { db: "admin", collection: "" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.js" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.roles" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find" ] }

If the source database is on a remote server, the you also need the find action on the system.indexes and system.namespaces collections in the admin database; e.g.

{ resource: { db: "admin", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.namespaces" }, actions: [ "find" ] }

Source Database is on a Remote Server

If copying from a remote server and the remote server has authentication enabled, you must authenticate to the remote host as a user with the proper authorization. See Authentication.

Target Database (todb)

Copy from non-admin Database

If the source database is not the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js collection in the target database. For example:

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] }
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] }

Copy from admin Database

If the source database is the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js, system.users, system.roles, and system.version collections in the target database. For example:

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] },
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.users" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.roles" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.version" }, actions: [ "insert" ] }

Authentication

If copying from a remote server and the remote server has authentication enabled, then you must include a username, nonce, and key.

The nonce is a one-time password that you request from the remote server using the copydbgetnonce command, as in the following:

use admin
mynonce = db.runCommand( { copydbgetnonce : 1, fromhost: <hostname> } ).nonce

If running the copydbgetnonce command directly on the remote host, you can omit the fromhost field in the copydbgetnonce command.

The key is a hash generated as follows:

hex_md5(mynonce + username + hex_md5(username + ":mongo:" + password))

Replica Sets

With read preference configured to set the slaveOk option to true, you may run copydb on a secondary member of a replica set.

Sharded Clusters

Do not use copydb from a mongos instance.

Do not use copydb to copy databases that contain sharded collections.

Examples

Copy on the Same Host

To copy from the same host, omit the fromhost field.

The following command copies the test database to a new records database on the current mongod instance:

use admin
db.runCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records"
})

Copy from a Remote Host to the Current Host

To copy from a remote host, include the fromhost field.

The following command copies the test database from the remote host example.net to a new records database on the current mongod instance:

use admin
db.runCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records",
   fromhost: "example.net"
})

Copy Databases from Remote mongod Instances that Enforce Authentication

To copy from a remote host that enforces authentication, include the fromhost, username, nonce and key fields.

The following command copies the test database from a remote host example.net that runs with authorization to a new records database on the local mongod instance. Because the example.net has authorization enabled, the command includes the username, nonce and key fields:

use admin
db.runCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records",
   fromhost: "example.net",
   username: "reportingAdmin",
   nonce: "<nonce>",
   key: "<passwordhash>"
})

See also

db.copyDatabase()

clone and db.cloneDatabase()

MongoDB Backup Methods and Import and Export MongoDB Data

dropDatabase

dropDatabase

The dropDatabase command drops the current database, deleting the associated data files.

Changed in version 2.6: This command does not delete the users associated with the current database. To drop the associated users, run the dropAllUsersFromDatabase command in the database you are deleting.

To run this command, issue the use <database> command in the shell, replacing <database> with the name of the database you wish to delete. Then use the following command form:

{ dropDatabase: 1 }

The mongo shell also provides the following equivalent helper method db.dropDatabase().

Warning

This command obtains a global write lock and will block other operations until it has completed.

See also

dropAllUsersFromDatabase

drop

drop

The drop command removes an entire collection from a database. The command has following syntax:

{ drop: <collection_name> }

The mongo shell provides the equivalent helper method db.collection.drop().

This command also removes any indexes associated with the dropped collection.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed.

create

Definition

create

Explicitly creates a collection. create has the following form:

{ create: <collection_name>,
  capped: <true|false>,
  autoIndexId: <true|false>,
  size: <max_size>,
  max: <max_documents>,
  flags: <0|1>
}

create has the following fields:

Field
Description

create
The name of the new collection.

capped
Optional. To create a capped collection. specify true. If you specify true, you must also set a maximum size in the size field.

autoIndexId
Optional. Specify false to disable the automatic creation of an index on the _id field. Before 2.2, the default value for autoIndexId was false.

size
Optional. The maximum size for the capped collection. Once a capped collection reaches its maximum size, MongoDB overwrites older old documents with new documents. The size field is required for capped collections.

max
Optional. The maximum number of documents to keep in the capped collection. The size limit takes precedence over this limit. If a capped collection reaches its maximum size before it reaches the maximum number of documents, MongoDB removes old documents. If you use this limit, ensure that the size limit is sufficient to contain the documents limit.

flags

Optional. .. versionadded:: 2.6

Set to 0 to disable the usePowerOf2Sizes allocation strategy for this collection, or 1 to enable usePowerOf2Sizes. Defaults to 1 unless the newCollectionsUsePowerOf2Sizes parameter is set to false.

field string create:

The name of the new collection.

field Boolean capped:

Optional. To create a capped collection. specify true. If you specify true, you must also set a maximum size in the size field.

field Boolean autoIndexId:

Optional. Specify false to disable the automatic creation of an index on the _id field. Before 2.2, the default value for autoIndexId was false.

field integer size:

Optional. The maximum size for the capped collection. Once a capped collection reaches its maximum size, MongoDB overwrites older old documents with new documents. The size field is required for capped collections.

field integer max:

Optional. The maximum number of documents to keep in the capped collection. The size limit takes precedence over this limit. If a capped collection reaches its maximum size before it reaches the maximum number of documents, MongoDB removes old documents. If you use this limit, ensure that the size limit is sufficient to contain the documents limit.

field integer flags:

Optional. .. versionadded:: 2.6

Set to 0 to disable the usePowerOf2Sizes allocation strategy for this collection, or 1 to enable usePowerOf2Sizes. Defaults to 1 unless the newCollectionsUsePowerOf2Sizes parameter is set to false.

For more information on the autoIndexId field in versions before 2.2, see _id Fields and Indexes on Capped Collections.

The db.createCollection() method wraps the create command.

Considerations

The create command obtains a write lock on the affected database and will block other operations until it has completed. The write lock for this operation is typically short lived. However, allocations for large capped collections may take longer.

Example

To create a capped collection limited to 64 kilobytes, issue the command in the following form:

db.runCommand( { create: "collection", capped: true, size: 64 * 1024 } )

clone

clone

The clone command clones a database from a remote MongoDB instance to the current host. clone copies the database on the remote instance with the same name as the current database. The command takes the following form:

{ clone: "db1.example.net:27017" }

Replace db1.example.net:27017 above with the resolvable hostname for the MongoDB instance you wish to copy from. Note the following behaviors:

clone can copy from a non-primary member of a replica set.

clone does not snapshot the database. If any clients update the database you’re copying at any point during the clone operation, the resulting database may be inconsistent.

You must run clone on the destination server.

The destination database will be locked periodically during the clone operation. In other words, clone will occasionally yield to allow other operations on the database to complete.

See copydb for similar functionality with greater flexibility.

cloneCollection

Definition

cloneCollection

Copies a collection from a remote mongod instance to the current mongod instance. cloneCollection creates a collection in a database with the same name as the remote collection’s database. cloneCollection takes the following form:

{ cloneCollection: "<namespace>", from: "<hostname>", query: { <query> } }

Important

You cannot clone a collection through a mongos but must connect directly to the mongod instance.

cloneCollection has the following fields:

Field | Description
cloneCollection | The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection.
from | Specify a resolvable hostname and optional port number of the remote server where the specified collection resides.
query | Optional. A query that filters the documents in the remote collection that cloneCollection will copy to the current database.

field string cloneCollection:
| The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection.
field string from:
| Specify a resolvable hostname and optional port number of the remote server where the specified collection resides.
field document query:
| Optional. A query that filters the documents in the remote collection that cloneCollection will copy to the current database.

Example

{ cloneCollection: "users.profiles", from: "mongodb.example.net:27017", query: { active: true } }

This operation copies the profiles collection from the users database on the server at mongodb.example.net. The operation only copies documents that satisfy the query { active: true }. cloneCollection always copies indexes. The query arguments is optional.

If, in the above example, the profiles collection exists in the users database, then MongoDB appends documents from the remote collection to the destination collection.

cloneCollectionAsCapped

cloneCollectionAsCapped

The cloneCollectionAsCapped command creates a new capped collection from an existing, non-capped collection within the same database. The operation does not affect the original non-capped collection.

The command has the following syntax:

{ cloneCollectionAsCapped: <existing collection>, toCollection: <capped collection>, size: <capped size> }

The command copies an existing collection and creates a new capped collection with a maximum size specified by the capped size in bytes. The name of the new capped collection must be distinct and cannot be the same as that of the original existing collection. To replace the original non-capped collection with a capped collection, use the convertToCapped command.

During the cloning, the cloneCollectionAsCapped command exhibit the following behavior:

MongoDB will transverse the documents in the original collection in natural order as they’re loaded.

If the capped size specified for the new collection is smaller than the size of the original uncapped collection, then MongoDB will begin overwriting earlier documents in insertion order, which is first in, first out (e.g “FIFO”).

closeAllDatabases

closeAllDatabases

closeAllDatabases is an internal command that invalidates all cursors and closes the open database files. The next operation that uses the database will reopen the file.

Warning

This command obtains a global write lock and will block other operations until it has completed.

convertToCapped

convertToCapped

The convertToCapped command converts an existing, non-capped collection to a capped collection within the same database.

The command has the following syntax:

{ convertToCapped: <collection>, size: <capped size> }

convertToCapped takes an existing collection (<collection>) and transforms it into a capped collection with a maximum size in bytes, specified by the size argument (<capped size>).

During the conversion process, the convertToCapped command exhibits the following behavior:

MongoDB traverses the documents in the original collection in natural order and loads the documents into a new capped collection.

If the capped size specified for the capped collection is smaller than the size of the original uncapped collection, then MongoDB will overwrite documents in the capped collection based on insertion order, or first in, first out order.

Internally, to convert the collection, MongoDB uses the following procedure

cloneCollectionAsCapped command creates the capped collection and imports the data.

MongoDB drops the original collection.

renameCollection renames the new capped collection to the name of the original collection.

Note

MongoDB does not support the convertToCapped command in a sharded cluster.

Warning

The convertToCapped will not recreate indexes from the original collection on the new collection, other than the index on the _id field. If you need indexes on this collection you will need to create these indexes after the conversion is complete.

See also

create

Warning

This command obtains a global write lock and will block other operations until it has completed.

filemd5

filemd5

The filemd5 command returns the md5 hashes for a single file stored using the GridFS specification. Client libraries use this command to verify that files are correctly written to MongoDB. The command takes the files_id of the file in question and the name of the GridFS root collection as arguments. For example:

{ filemd5: ObjectId("4f1f10e37671b50e4ecd2776"), root: "fs" }

MongoDB computes the filemd5 using all data in the GridFS file object pulled sequentially from each chunk in the chunks collection.

createIndexes

New in version 2.6.

Definition

createIndexes

Builds one or more indexes on a collection. The createIndexes command takes the following form:

db.runCommand(
  {
    createIndexes: <collection>,
    indexes: [
        {
            key: {
                <key-value_pair>,
                <key-value_pair>,
                ...
            },
            name: <index_name>,
            <option1>,
            <option2>,
            ...
        },
        { ... },
        { ... }
    ]
  }
)

The createIndexes command takes the following fields:

Field | Description
createIndexes | The collection for which to create indexes.
indexes | Specifies the indexes to create. Each document in the array specifies a separate index.

field string createIndexes:
| The collection for which to create indexes.
field array indexes:
| Specifies the indexes to create. Each document in the array specifies a separate index.

Each document in the indexes array can take the following fields:

Field
Description

background
Optional. Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

unique

Optional. Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true to create a unique index. The default value is false.

The option is unavailable for hashed indexes.

dropDups

Optional. Creates a unique index on a field that may have duplicates. MongoDB indexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true to create unique index. The default value is false.

The option is unavailable for hashed indexes.

Deprecated since version 2.6.

Warning

dropDups will delete data from your collection when building the index.

sparse

Optional. If true, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is false. See Sparse Indexes for more information.

Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document.

2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes.

expireAfterSeconds
Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.

v
Optional. The index version number. The default index version depends on the version of mongod running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations.

weights
Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See Control Search Results with Weights to adjust the scores. The default value is 1.

default_language
Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and Specify a Language for Text Index for more information and examples. The default value is english.

language_override
Optional. For text indexes, the name of the field, in the collection’s documents, that contains the override language for the document. The default value is language. See Use any Field to Specify the Language for a Document for an example.

textIndexVersion

Optional. For text indexes, the text index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

2dsphereIndexVersion

Optional. For 2dsphere indexes, the 2dsphere index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

bits

Optional. For 2d indexes, the number of precision of the stored geohash value of the location data.

The bits value ranges from 1 to 32 inclusive. The default value is 26.

min
Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0.

max
Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0.

bucketSize

For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other.

The value must be greater than 0.

key
Specifies the index’s fields. For each field, specify a key-value pair in which the key is the name of the field to index and the value is either the index direction or index type. If specifying direction, specify 1 for ascending or -1 for descending.

name
A name that uniquely identifies the index.

ns
Optional. The namespace (i.e. <database>.<collection>) of the collection for which to create the index. If you omit ns, MongoDB generates the namespace.

field Boolean background:

Optional. Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

field Boolean unique:

Optional. Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true to create a unique index. The default value is false.

The option is unavailable for hashed indexes.

field Boolean dropDups:

Optional. Creates a unique index on a field that may have duplicates. MongoDB indexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true to create unique index. The default value is false.

The option is unavailable for hashed indexes.

Deprecated since version 2.6.

Warning

dropDups will delete data from your collection when building the index.

field Boolean sparse:

Optional. If true, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is false. See Sparse Indexes for more information.

Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document.

2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes.

field integer expireAfterSeconds:

Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.

field index version v:

Optional. The index version number. The default index version depends on the version of mongod running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations.

field document weights:

Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See Control Search Results with Weights to adjust the scores. The default value is 1.

field string default_language:

Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and Specify a Language for Text Index for more information and examples. The default value is english.

field string language_override:

Optional. For text indexes, the name of the field, in the collection’s documents, that contains the override language for the document. The default value is language. See Use any Field to Specify the Language for a Document for an example.

field integer textIndexVersion:

Optional. For text indexes, the text index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

field integer 2dsphereIndexVersion:

Optional. For 2dsphere indexes, the 2dsphere index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

field integer bits:

Optional. For 2d indexes, the number of precision of the stored geohash value of the location data.

The bits value ranges from 1 to 32 inclusive. The default value is 26.

field number min:

Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0.

field number max:

Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0.

field number bucketSize:

For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other.

The value must be greater than 0.

field document key:

Specifies the index’s fields. For each field, specify a key-value pair in which the key is the name of the field to index and the value is either the index direction or index type. If specifying direction, specify 1 for ascending or -1 for descending.

field string name:

A name that uniquely identifies the index.

field string ns:

Optional. The namespace (i.e. <database>.<collection>) of the collection for which to create the index. If you omit ns, MongoDB generates the namespace.

Considerations

An index name, including the namespace, cannot be longer than the Index Name Length limit.

Behavior

Non-background indexing operations block all other operations on a database. If you specify multiple indexes to createIndexes, MongoDB builds the indexes serially.

If you create an index with one set of options and then issue createIndexes with the same index fields but different options, MongoDB will not change the options nor rebuild the index. To change index options, drop the existing index with db.collection.dropIndex() before running the new createIndexes with the new options.

Example

The following command builds two indexes on the inventory collection of the products database:

db.getSiblingDB("products").runCommand(
  {
    createIndexes: "inventory",
    indexes: [
        {
            key: {
                item: 1,
                manufacturer: 1,
                model: 1
            },
            name: "item_manufacturer_model",
            unique: true
        },
        {
            key: {
                item: 1,
                supplier: 1,
                model: 1
            },
            name: "item_supplier_model",
            unique: true
        }
    ]
  }
)

When the indexes successfully finish building, MongoDB returns a results document that includes a status of "ok" : 1.

Output

The createIndexes command returns a document that indicates the success of the operation. The document contains some but not all of the following fields, depending on outcome:

createIndexes.createdCollectionAutomatically

If true, then the collection didn’t exist and was created in the process of creating the index.

createIndexes.numIndexesBefore

The number of indexes at the start of the command.

createIndexes.numIndexesAfter

The number of indexes at the end of the command.

createIndexes.ok

A value of 1 indicates the indexes are in place. A value of 0 indicates an error.

createIndexes.note

This note is returned if an existing index or indexes already exist. This indicates that the index was not created or changed.

createIndexes.errmsg

Returns information about any errors.

createIndexes.code

The error code representing the type of error.

dropIndexes

dropIndexes

The dropIndexes command drops one or all indexes from the current collection. To drop all indexes, issue the command like so:

{ dropIndexes: "collection", index: "*" }

To drop a single, issue the command by specifying the name of the index you want to drop. For example, to drop the index named age_1, use the following command:

{ dropIndexes: "collection", index: "age_1" }

The shell provides a useful command helper. Here’s the equivalent command:

db.collection.dropIndex("age_1");

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed.

fsync

Definition

fsync

Forces the mongod process to flush all pending writes from the storage layer to disk. Optionally, you can use fsync to lock the mongod instance and block write operations for the purpose of capturing backups.

As applications write data, MongoDB records the data in the storage layer and then writes the data to disk within the syncPeriodSecs interval, which is 60 seconds by default. Run fsync when you want to flush writes to disk ahead of that interval.

The fsync command has the following syntax:

{ fsync: 1, async: <Boolean>, lock: <Boolean> }

The fsync command has the following fields:

Field | Description
fsync | Enter “1” to apply fsync.
async | Optional. Runs fsync asynchronously. By default, the fsync operation is synchronous.
lock | Optional. Locks mongod instance and blocks all write operations.

field integer fsync:
| Enter “1” to apply fsync.
field Boolean async:
| Optional. Runs fsync asynchronously. By default, the fsync operation is synchronous.
field Boolean lock:
| Optional. Locks mongod instance and blocks all write operations.

Behavior

An fsync lock is only possible on individual mongod instances of a sharded cluster, not on the entire cluster. To backup an entire sharded cluster, please see Backup and Restore Sharded Clusters for more information.

If your mongod has journaling enabled, consider using another method to create a back up of the data set.

After fsync, with lock, runs on a mongod, all write operations will block until a subsequent unlock. Read operations may also block. As a result, fsync, with lock, is not a reliable mechanism for making a mongod instance operate in a read-only mode.

Important

Blocked read operations prevent verification of authentication. Such reads are necessary to establish new connections to a mongod that enforces authorization checks.

Warning

When calling fsync with lock, ensure that the connection remains open to allow a subsequent call to db.fsyncUnlock().

Closing the connection may make it difficult to release the lock.

Examples

Run Asynchronously

The fsync operation is synchronous by default To run fsync asynchronously, use the async field set to true:

{ fsync: 1, async: true }

The operation returns immediately. To view the status of the fsync operation, check the output of db.currentOp().

Lock mongod Instance

The primary use of fsync is to lock the mongod instance in order to back up the files withing mongod‘s dbPath. The operation flushes all data to the storage layer and blocks all write operations until you unlock the mongod instance.

To lock the database, use the lock field set to true:

{ fsync: 1, lock: true }

You may continue to perform read operations on a mongod instance that has a fsync lock. However, after the first write operation all subsequent read operations wait until you unlock the mongod instance.

Unlock mongod Instance

To unlock the mongod, use db.fsyncUnlock():

db.fsyncUnlock();

Check Lock Status

To check the state of the fsync lock, use db.currentOp(). Use the following JavaScript function in the shell to test if mongod instance is currently locked:

serverIsLocked = function () {
                     var co = db.currentOp();
                     if (co && co.fsyncLock) {
                         return true;
                     }
                     return false;
                 }

After loading this function into your mongo shell session call it, with the following syntax:

serverIsLocked()

This function will return true if the mongod instance is currently locked and false if the mongod is not locked.

clean

clean

clean is an internal command.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed.

connPoolSync

connPoolSync

connPoolSync is an internal command.

connectionStatus

New in version 2.4.0.

Definition

connectionStatus

Returns information about the current connection, specifically the state of authenticated users and their available permissions.

Output

connectionStatus.authInfo

A document with data about the authentication state of the current collection, including users and available permissions.

connectionStatus.authinfo.authenticatedUsers

An array with documents for each authenticated user.

connectionStatus.authInfo.authenticatedUsers[n].user

The user’s name.

connectionStatus.authInfo.authenticatedUsers[n].db

The database associated with the user’s credentials.

connectionStatus.authinfo.authenticatedUserRoles

An array with documents for each role granted to the current connection:

connectionStatus.authinfo.authenticatedUserRoles[n].role

The definition of the current roles associated with the current authenticated users. See Built-In Roles and Privilege Actions for more information.

connectionStatus.authinfo.authenticatedUserRoles[n].db

The database to which role applies.

connectionStatus.ok

The return value for the command. A value of 1 indicates success.

compact

Definition

compact

New in version 2.0.

Rewrites and defragments all data in a collection, as well as all of the indexes on that collection. compact has the following form:

{ compact: <collection name> }

compact has the following fields:

Field | Description
compact | The name of the collection.
force | Optional. If true, compact can run on the primary in a replica set. If false, compact returns an error when run on a primary, because the command blocks all other activity. Beginning with version 2.2, compact blocks activity only for the database it is compacting.
paddingFactor | Optional. Describes the record size allocated for each document as a factor of the document size for all records compacted during the compact operation. The paddingFactor does not affect the padding of subsequent record allocations after compact completes. For more information, see paddingFactor.
paddingBytes | Optional. Sets the padding as an absolute number of bytes for all records compacted during the compact operation. After compact completes, paddingBytes does not affect the padding of subsequent record allocations. For more information, see paddingBytes.

field string compact:
| The name of the collection.
field boolean force:
| Optional. If true, compact can run on the primary in a replica set. If false, compact returns an error when run on a primary, because the command blocks all other activity. Beginning with version 2.2, compact blocks activity only for the database it is compacting.
field number paddingFactor:
| Optional. Describes the record size allocated for each document as a factor of the document size for all records compacted during the compact operation. The paddingFactor does not affect the padding of subsequent record allocations after compact completes. For more information, see paddingFactor.
field integer paddingBytes:
| Optional. Sets the padding as an absolute number of bytes for all records compacted during the compact operation. After compact completes, paddingBytes does not affect the padding of subsequent record allocations. For more information, see paddingBytes.

compact is similar to repairDatabase; however, repairDatabase operates on an entire database.

Warning

Always have an up-to-date backup before performing server maintenance such as the compact operation.

paddingFactor

New in version 2.2.

The paddingFactor field takes the following range of values:

Default: 1.0

Minimum: 1.0 (no padding)

Maximum: 4.0

If your updates increase the size of the documents, padding will increase the amount of space allocated to each document and avoid expensive document relocation operations within the data files.

You can calculate the padding size by subtracting the document size from the record size or, in terms of the paddingFactor, by subtracting 1 from the paddingFactor:

padding size = (paddingFactor - 1) * <document size>.

For example, a paddingFactor of 1.0 specifies a padding size of 0 whereas a paddingFactor of 1.2 specifies a padding size of 0.2 or 20 percent (20%) of the document size.

With the following command, you can use the paddingFactor option of the compact command to set the record size to 1.1 of the document size, or a padding factor of 10 percent (10%):

db.runCommand ( { compact: '<collection>', paddingFactor: 1.1 } )

compact compacts existing documents but does not reset paddingFactor statistics for the collection. After the compact MongoDB will use the existing paddingFactor when allocating new records for documents in this collection.

paddingBytes

New in version 2.2.

Specifying paddingBytes can be useful if your documents start small but then increase in size significantly. For example, if your documents are initially 40 bytes long and you grow them by 1KB, using paddingBytes: 1024 might be reasonable since using paddingFactor: 4.0 would specify a record size of 160 bytes (4.0 times the initial document size), which would only provide a padding of 120 bytes (i.e. record size of 160 bytes minus the document size).

With the following command, you can use the paddingBytes option of the compact command to set the padding size to 100 bytes on the collection named by <collection>:

db.runCommand ( { compact: '<collection>', paddingBytes: 100 } )

Behaviors

Blocking

In MongoDB 2.2, compact blocks activities only for its database. Prior to 2.2, the command blocked all activities.

You may view the intermediate progress either by viewing the mongod log file or by running the db.currentOp() in another shell instance.

Operation Termination

If you terminate the operation with the db.killOp() method or restart the server before the compact operation has finished:

If you have journaling enabled, the data remains valid and usable, regardless of the state of the compact operation. You may have to manually rebuild the indexes.

If you do not have journaling enabled and the mongod or compact terminates during the operation, it is impossible to guarantee that the data is in a valid state.

In either case, much of the existing free space in the collection may become un-reusable. In this scenario, you should rerun the compaction to completion to restore the use of this free space.

Disk Space

compact generally uses less disk space than repairDatabase and is faster. However, the compact command is still slow and blocks other database use. Only use compact during scheduled maintenance periods.

compact requires up to 2 gigabytes of additional disk space while running. Unlike repairDatabase, compact does not free space on the file system.

To see how the storage space changes for the collection, run the collStats command before and after compaction.

Size and Number of Data Files

compact may increase the total size and number of your data files, especially when run for the first time. However, this will not increase the total collection storage space since storage size is the amount of data allocated within the database files, and not the size/number of the files on the file system.

Replica Sets

compact commands do not replicate to secondaries in a replica set:

Compact each member separately.

Ideally run compact on a secondary. See option force:true above for information regarding compacting the primary.

On secondaries, the compact command forces the secondary to enter RECOVERING state. Read operations issued to an instance in the RECOVERING state will fail. This prevents clients from reading during the operation. When the operation completes, the secondary returns to:replstate:SECONDARY state.

See Replica Set Member States for more information about replica set member states.

See Perform Maintenance on Replica Set Members for an example replica set maintenance procedure to maximize availability during maintenance operations.

Sharded Clusters

compact is a command issued to a mongod. In a sharded environment, run compact on each shard separately as a maintenance operation.

You cannot issue compact against a mongos instance.

Capped Collections

It is not possible to compact capped collections because they don’t have padding, and documents cannot grow in these collections. However, the documents of a capped collection are not subject to fragmentation.

Index Building

New in version 2.6.

mongod rebuilds all indexes in parallel following the compact operation.

collMod

Definition

collMod

New in version 2.2.

collMod makes it possible to add flags to a collection to modify the behavior of MongoDB. Flags include usePowerOf2Sizes and index. The command takes the following prototype form:

db.runCommand( {"collMod" : <collection> , "<flag>" : <value> } )

In this command substitute <collection> with the name of a collection in the current database, and <flag> and <value> with the flag and value you want to set.

Use the userFlags field in the db.collection.stats() output to check enabled collection flags.

Flags

Powers of Two Record Allocation

usePowerOf2Sizes

Changed in version 2.6: usePowerOf2Sizes became the default allocation strategy for all new collections. Set newCollectionsUsePowerOf2Sizes to false to select the exact fit allocation strategy for new collections.

The usePowerOf2Sizes flag changes the method that MongoDB uses to allocate space on disk for documents in this collection. By setting usePowerOf2Sizes, you ensure that MongoDB will allocate space for documents in sizes that are powers of 2 (e.g. 32, 64, 128, 256, 512...16777216.) The smallest allocation for a document is 32 bytes.

With usePowerOf2Sizes, MongoDB will be able to more effectively reuse space.

With usePowerOf2Sizes, MongoDB allocates records that have power of 2 sizes until record sizes equal 4 megabytes. For records larger than 4 megabytes with usePowerOf2Sizes set, mongod will allocate records in full megabytes by rounding up to the nearest megabyte.

Use usePowerOf2Sizes for collections where applications insert and delete large numbers of documents to avoid storage fragmentation and ensure that MongoDB will effectively use space on disk.

TTL Collection Expiration Time

index

The index flag changes the expiration time of a TTL Collection.

Specify the key and new expiration time with a document of the form:

{keyPattern: <index_spec>, expireAfterSeconds: <seconds> }

In this example, <index_spec> is an existing index in the collection and seconds is the number of seconds to subtract from the current time.

On success collMod returns a document with fields expireAfterSeconds_old and expireAfterSeconds_new set to their respective values.

On failure, collMod returns a document with no expireAfterSeconds field to update if there is no existing expireAfterSeconds field or cannot find index { **key**: 1.0 } for ns **namespace** if the specified keyPattern does not exist.

Examples

Enable Powers of Two Allocation

To enable usePowerOf2Sizes on the collection named products, use the following operation:

db.runCommand( {collMod: "products", usePowerOf2Sizes : true })

To disable usePowerOf2Sizes on the collection products, use the following operation:

db.runCommand( { collMod: "products", usePowerOf2Sizes: false })

usePowerOf2Sizes only affects subsequent allocations caused by document insertion or record relocation as a result of document growth, and does not affect existing allocations.

Change Expiration Value for Indexes

To update the expiration value for a collection named sessions indexed on a lastAccess field from 30 minutes to 60 minutes, use the following operation:

db.runCommand({collMod: "sessions",
               index: {keyPattern: {lastAccess:1},
                       expireAfterSeconds: 3600}})

Which will return the document:

{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }

reIndex

reIndex

The reIndex command drops all indexes on a collection and recreates them. This operation may be expensive for collections that have a large amount of data and/or a large number of indexes. Use the following syntax:

{ reIndex: "collection" }

Normally, MongoDB compacts indexes during routine updates. For most users, the reIndex command is unnecessary. However, it may be worth running if the collection size has changed significantly or if the indexes are consuming a disproportionate amount of disk space.

Call reIndex using the following form:

db.collection.reIndex();

Note

For replica sets, reIndex will not propagate from the primary to secondaries. reIndex will only affect a single mongod instance.

Important

reIndex will rebuild indexes in the background if the index was originally specified with this option. However, reIndex will rebuild the _id index in the foreground, which takes the database’s write lock.

See

Index Creation for more information on the behavior of indexing operations in MongoDB.

setParameter

setParameter

setParameter is an administrative command for modifying options normally set on the command line. You must issue the setParameter command against the admin database in the form:

{ setParameter: 1, <option>: <value> }

Replace the <option> with one of the supported setParameter options:

journalCommitInterval

logLevel

logUserIds

notablescan

quiet

replApplyBatchSize

replIndexPrefetch

syncdelay

traceExceptions

textSearchEnabled

sslMode

clusterAuthMode

userCacheInvalidationIntervalSecs

getParameter

getParameter

getParameter is an administrative command for retrieving the value of options normally set on the command line. Issue commands against the admin database as follows:

{ getParameter: 1, <option>: 1 }

The values specified for getParameter and <option> do not affect the output. The command works with the following options:

quiet

notablescan

logLevel

syncdelay

See also

setParameter for more about these parameters.

repairDatabase

Definition

repairDatabase

Checks and repairs errors and inconsistencies in data storage. repairDatabase is analogous to a fsck command for file systems. Run the repairDatabase command to ensure data integrity after the system experiences an unexpected system restart or crash, if:

The mongod instance is not running with journaling enabled.

When using journaling, there is almost never any need to run repairDatabase. In the event of an unclean shutdown, the server will be able to restore the data files to a pristine state automatically.

There are no other intact replica set members with a complete data set.

Warning

During normal operations, only use the repairDatabase command and wrappers including db.repairDatabase() in the mongo shell and mongod --repair, to compact database files and/or reclaim disk space. Be aware that these operations remove and do not save any corrupt data during the repair process.

If you are trying to repair a replica set member, and you have access to an intact copy of your data (e.g. a recent backup or an intact member of the replica set), you should restore from that intact copy, and not use repairDatabase.

repairDatabase takes the following form:

{ repairDatabase: 1 }

repairDatabase has the following fields:

Field
Description

preserveClonedFilesOnFailure
When true, repairDatabase will not delete temporary files in the backup directory on error, and all new files are created with the “backup” instead of “_tmp” directory prefix. By default repairDatabase does not delete temporary files, and uses the “_tmp” naming prefix for new files.

backupOriginalFiles
When true, repairDatabase moves old database files to the backup directory instead of deleting them before moving new files into place. New files are created with the “backup” instead of “_tmp” directory prefix. By default, repairDatabase leaves temporary files unchanged, and uses the “_tmp” naming prefix for new files.

field boolean preserveClonedFilesOnFailure:

When true, repairDatabase will not delete temporary files in the backup directory on error, and all new files are created with the “backup” instead of “_tmp” directory prefix. By default repairDatabase does not delete temporary files, and uses the “_tmp” naming prefix for new files.

field boolean backupOriginalFiles:

When true, repairDatabase moves old database files to the backup directory instead of deleting them before moving new files into place. New files are created with the “backup” instead of “_tmp” directory prefix. By default, repairDatabase leaves temporary files unchanged, and uses the “_tmp” naming prefix for new files.

You can explicitly set the options as follows:

{ repairDatabase: 1,
  preserveClonedFilesOnFailure: <boolean>,
  backupOriginalFiles: <boolean> }

Warning

This command obtains a global write lock and will block other operations until it has completed.

Note

repairDatabase requires free disk space equal to the size of your current data set plus 2 gigabytes. If the volume that holds dbpath lacks sufficient space, you can mount a separate volume and use that for the repair. When mounting a separate volume for repairDatabase you must run repairDatabase from the command line and use the --repairpath switch to specify the folder in which to store temporary repair files.

See mongod --repair and mongodump --repair for information on these related options.

Behavior

Changed in version 2.6: The repairDatabase command is now available for secondary as well as primary members of replica sets.

The repairDatabase command compacts all collections in the database. It is identical to running the compact command on each collection individually.

repairDatabase reduces the total size of the data files on disk. It also recreates all indexes in the database.

The time requirement for repairDatabase depends on the size of the data set.

You may invoke repairDatabase from multiple contexts:

Use the mongo shell to run the command, as above.

Use the db.repairDatabase() in the mongo shell.

Run mongod directly from your system’s shell. Make sure that mongod isn’t already running, and that you invoke mongod as a user that has access to MongoDB’s data files. Run as:

mongod --repair

To add a repair path:

mongod --repair --repairpath /opt/vol2/data

See repairPath for more information.

Note

mongod --repair will fail if your database is not a master or primary. In most cases, you should recover a corrupt secondary using the data from an existing intact node. To run repair on a secondary/slave restart the instance in standalone mode without the --replSet or --slave options.

Example

{ repairDatabase: 1 }

Using repairDatabase to Reclaim Disk Space

You should not use repairDatabase for data recovery unless you have no other option.

However, if you trust that there is no corruption and you have enough free space, then repairDatabase is the appropriate and the only way to reclaim disk space.

touch

touch

New in version 2.2.

The touch command loads data from the data storage layer into memory. touch can load the data (i.e. documents) indexes or both documents and indexes. Use this command to ensure that a collection, and/or its indexes, are in memory before another operation. By loading the collection or indexes into memory, mongod will ideally be able to perform subsequent operations more efficiently. The touch command has the following prototypical form:

{ touch: [collection], data: [boolean], index: [boolean] }

By default, data and index are false, and touch will perform no operation. For example, to load both the data and the index for a collection named records, you would use the following command in the mongo shell:

db.runCommand({ touch: "records", data: true, index: true })

touch will not block read and write operations on a mongod, and can run on secondary members of replica sets.

Note

Using touch to control or tweak what a mongod stores in memory may displace other records data in memory and hinder performance. Use with caution in production systems.

Warning

If you run touch on a secondary, the secondary will enter a RECOVERING state to prevent clients from sending read operations during the touch operation. When touch finishes the secondary will automatically return to SECONDARY state. See state for more information on replica set member states.

shutdown

shutdown

The shutdown command cleans up all database resources and then terminates the process. You must issue the shutdown command against the admin database in the form:

{ shutdown: 1 }

Note

Run the shutdown against the admin database. When using shutdown, the connection must originate from localhost or use an authenticated connection.

If the node you’re trying to shut down is a replica set primary, then the command will succeed only if there exists a secondary node whose oplog data is within 10 seconds of the primary. You can override this protection using the force option:

{ shutdown: 1, force: true }

Alternatively, the shutdown command also supports a timeoutSecs argument which allows you to specify a number of seconds to wait for other members of the replica set to catch up:

{ shutdown: 1, timeoutSecs: 60 }

The equivalent mongo shell helper syntax looks like this:

db.shutdownServer({timeoutSecs: 60});

logRotate

logRotate

The logRotate command is an administrative command that allows you to rotate the MongoDB logs to prevent a single logfile from consuming too much disk space. You must issue the logRotate command against the admin database in the form:

{ logRotate: 1 }

Note

Your mongod instance needs to be running with the --logpath [file] option.

You may also rotate the logs by sending a SIGUSR1 signal to the mongod process. If your mongod has a process ID of 2200, here’s how to send the signal on Linux:

kill -SIGUSR1 2200

logRotate renames the existing log file by appending the current timestamp to the filename. The appended timestamp has the following form:

<YYYY>-<mm>-<DD>T<HH>-<MM>-<SS>

Then logRotate creates a new log file with the same name as originally specified by the systemLog.path setting to mongod or mongos.

Note

New in version 2.0.3: The logRotate command is available to mongod instances running on Windows systems with MongoDB release 2.0.3 and higher.

Diagnostic Commands

Name | Description
listDatabases | Returns a document that lists all databases and returns basic database statistics.
dbHash | Internal command to support sharding.
driverOIDTest | Internal command that converts an ObjectId to a string to support tests.
listCommands | Lists all database commands provided by the current mongod instance.
availableQueryOptions | Internal command that reports on the capabilities of the current MongoDB instance.
buildInfo | Displays statistics about the MongoDB build.
collStats | Reports storage utilization statics for a specified collection.
connPoolStats | Reports statistics on the outgoing connections from this MongoDB instance to other MongoDB instances in the deployment.
shardConnPoolStats | Reports statistics on a mongos‘s connection pool for client operations against shards.
dbStats | Reports storage utilization statistics for the specified database.
cursorInfo | Deprecated. Reports statistics on active cursors.
dataSize | Returns the data size for a range of data. For internal use.
diagLogging | Provides a diagnostic logging. For internal use.
getCmdLineOpts | Returns a document with the run-time arguments to the MongoDB instance and their parsed options.
netstat | Internal command that reports on intra-deployment connectivity. Only available for mongos instances.
ping | Internal command that tests intra-deployment connectivity.
profile | Interface for the database profiler.
validate | Internal command that scans for a collection’s data and indexes for correctness.
top | Returns raw usage statistics for each database in the mongod instance.
indexStats | Experimental command that collects and aggregates statistics on all indexes.
whatsmyuri | Internal command that returns information on the current client.
getLog | Returns recent log messages.
hostInfo | Returns data that reflects the underlying host system.
serverStatus | Returns a collection metrics on instance-wide resource utilization and status.
features | Reports on features available in the current MongoDB instance.
isSelf | Internal command to support testing.

listDatabases

dbHash

driverOIDTest

listCommands

availableQueryOptions

buildInfo

collStats

connPoolStats

shardConnPoolStats

dbStats

cursorInfo

dataSize

diagLogging

getCmdLineOpts

netstat

ping

profile

validate

top

indexStats

whatsmyuri

getLog

hostInfo

serverStatus

features

isSelf

listDatabases

listDatabases

The listDatabases command provides a list of existing databases along with basic statistics about them:

{ listDatabases: 1 }

The value (e.g. 1) does not affect the output of the command. listDatabases returns a document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.

Example

The following operation returns a list of all databases:

db.runCommand( { listDatabases: 1 } )

See also

Use Database Commands.

dbHash

dbHash

dbHash is a command that supports config servers and is not part of the stable client facing API.

driverOIDTest

driverOIDTest

driverOIDTest is an internal command.

listCommands

listCommands

The listCommands command generates a list of all database commands implemented for the current mongod instance.

availableQueryOptions

availableQueryOptions

availableQueryOptions is an internal command that is only available on mongos instances.

buildInfo

buildInfo

The buildInfo command is an administrative command which returns a build summary for the current mongod. buildInfo has the following prototype form:

{ buildInfo: 1 }

In the mongo shell, call buildInfo in the following form:

db.runCommand( { buildInfo: 1 } )

Example

The output document of buildInfo has the following form:

{
  "version" : "<string>",
  "gitVersion" : "<string>",
  "sysInfo" : "<string>",
  "loaderFlags" : "<string>",
  "compilerFlags" : "<string>",
  "allocator" : "<string>",
  "versionArray" : [ <num>, <num>, <...> ],
  "javascriptEngine" : "<string>",
  "bits" : <num>,
  "debug" : <boolean>,
  "maxBsonObjectSize" : <num>,
  "ok" : <num>
}

Consider the following documentation of the output of buildInfo:

buildInfo

The document returned by the buildInfo command.

buildInfo.gitVersion

The commit identifier that identifies the state of the code used to build the mongod.

buildInfo.sysInfo

A string that holds information about the operating system, hostname, kernel, date, and Boost version used to compile the mongod.

buildInfo.loaderFlags

The flags passed to the loader that loads the mongod.

buildInfo.compilerFlags

The flags passed to the compiler that builds the mongod binary.

buildInfo.allocator

Changed in version 2.2.

The memory allocator that mongod uses. By default this is tcmalloc after version 2.2, and system before 2.2.

buildInfo.versionArray

An array that conveys version information about the mongod instance. See version for a more readable version of this string.

buildInfo.javascriptEngine

Changed in version 2.4.

A string that reports the JavaScript engine used in the mongod instance. By default, this is V8 after version 2.4, and SpiderMonkey before 2.4.

buildInfo.bits

A number that reflects the target processor architecture of the mongod binary.

buildInfo.debug

A boolean. true when built with debugging options.

buildInfo.maxBsonObjectSize

A number that reports the Maximum BSON Document Size.

collStats

Definition

collStats

The collStats command returns a variety of storage statistics for a given collection. Use the following syntax:

{ collStats: "collection" , scale : 1024 }

Specify the collection you want statistics for, and use the scale argument to scale the output. The above example will display values in kilobytes.

Examine the following example output, which uses the db.collection.stats() helper in the mongo shell.

> db.users.stats()
{
        "ns" : "app.users",             // namespace
        "count" : 9,                    // number of documents
        "size" : 432,                   // collection size in bytes
        "avgObjSize" : 48,              // average object size in bytes
        "storageSize" : 3840,           // (pre)allocated space for the collection in bytes
        "numExtents" : 1,               // number of extents (contiguously allocated chunks of datafile space)
        "nindexes" : 2,                 // number of indexes
        "lastExtentSize" : 3840,        // size of the most recently created extent in bytes
        "paddingFactor" : 1,            // padding can speed up updates if documents grow
        "flags" : 1,
        "totalIndexSize" : 16384,       // total index size in bytes
        "indexSizes" : {                // size of specific indexes in bytes
                "_id_" : 8192,
                "username" : 8192
        },
        "ok" : 1
}

Note

The scale factor rounds values to whole numbers. This can produce unpredictable and unexpected results in some situations.

If collStats operates on a capped collection, then the following fields will also be present:

> db.users.stats()
{
        ...
        "capped" : true,
        "max" : NumberLong("9223372036854775807"),
        "ok" : 1
}

Output

collStats.ns

The namespace of the current collection, which follows the format [database].[collection].

collStats.count

The number of objects or documents in this collection.

collStats.size

The total size of all records in a collection. This value does not include the record header, which is 16 bytes per record, but does include the record’s padding. Additionally size does not include the size of any indexes associated with the collection, which the totalIndexSize field reports.

The scale argument affects this value.

collStats.avgObjSize

The average size of an object in the collection. The scale argument does not affect this value.

collStats.storageSize

The total amount of storage allocated to this collection for document storage. The scale argument affects this value. The storageSize does not decrease as you remove or shrink documents.

collStats.numExtents

The total number of contiguously allocated data file regions.

collStats.nindexes

The number of indexes on the collection. All collections have at least one index on the _id field.

Changed in version 2.2: Before 2.2, capped collections did not necessarily have an index on the _id field, and some capped collections created with pre-2.2 versions of mongod may not have an _id index.

collStats.lastExtentSize

The size of the last extent allocated. The scale argument affects this value.

collStats.paddingFactor

The amount of space added to the end of each document at insert time. The document padding provides a small amount of extra space on disk to allow a document to grow slightly without needing to move the document. mongod automatically calculates this padding factor

collStats.flags

Changed in version 2.2: Removed in version 2.2 and replaced with the userFlags and systemFlags fields.

Indicates the number of flags on the current collection. In version 2.0, the only flag notes the existence of an index on the _id field.

collStats.systemFlags

New in version 2.2.

Reports the flags on this collection that reflect internal server options. Typically this value is 1 and reflects the existence of an index on the _id field.

collStats.userFlags

New in version 2.2.

Reports the flags on this collection set by the user. In version 2.2 the only user flag is usePowerOf2Sizes. If usePowerOf2Sizes is enabled, userFlags will be set to 1, otherwise it will be 0.

See the collMod command for more information on setting user flags and usePowerOf2Sizes.

collStats.totalIndexSize

The total size of all indexes. The scale argument affects this value.

collStats.indexSizes

This field specifies the key and size of every existing index on the collection. The scale argument affects this value.

collStats.capped

This field will be “true” if the collection is capped.

collStats.max

Shows the maximum number of documents that may be present in a capped collection.

connPoolStats

Definition

connPoolStats

The command connPoolStats returns information regarding the number of open connections to the current database instance, including client connections and server-to-server connections for replication and clustering.

Note

connPoolStats only returns meaningful results for mongos instances and for mongod instances in sharded clusters.

The command takes the following form:

{ connPoolStats: 1 }

The value of the argument (i.e. 1 ) does not affect the output of the command.

Output

connPoolStats.hosts

The embedded documents of the hosts document report connections between the mongos or mongod instance and each component mongod of the sharded cluster.

connPoolStats.hosts.[host].available

available reports the total number of connections that the mongos or mongod could use to connect to this mongod.

connPoolStats.hosts.[host].created

created reports the number of connections that this mongos or mongod has ever created for this host.

connPoolStats.replicaSets

replicaSets is a document that contains replica set information for the sharded cluster.

connPoolStats.replicaSets.shard

The shard document reports on each shard within the sharded cluster

connPoolStats.replicaSets.[shard].host

The host field holds an array of document that reports on each host within the shard in the replica set.

These values derive from the replica set status values.

connPoolStats.replicaSets.[shard].host[n].addr

addr reports the address for the host in the sharded cluster in the format of “[hostname]:[port]”.

connPoolStats.replicaSets.[shard].host[n].ok

ok reports false when:

the mongos or mongod cannot connect to instance.

the mongos or mongod received a connection exception or error.

This field is for internal use.

connPoolStats.replicaSets.[shard].host[n].ismaster

ismaster reports true if this host is the primary member of the replica set.

connPoolStats.replicaSets.[shard].host[n].hidden

hidden reports true if this host is a hidden member of the replica set.

connPoolStats.replicaSets.[shard].host[n].secondary

secondary reports true if this host is a secondary member of the replica set.

connPoolStats.replicaSets.[shard].host[n].pingTimeMillis

pingTimeMillis reports the ping time in milliseconds from the mongos or mongod to this host.

connPoolStats.replicaSets.[shard].host[n].tags

New in version 2.2.

tags reports the tags, if this member of the set has tags configured.

connPoolStats.replicaSets.[shard].master

master reports the ordinal identifier of the host in the host array that is the primary of the replica set.

connPoolStats.replicaSets.[shard].nextSlave

Deprecated since version 2.2.

nextSlave reports the secondary member that the mongos will use to service the next request for this replica set.

connPoolStats.createdByType

createdByType document reports the number of each type of connection that mongos or mongod has created in all connection pools.

mongos connect to mongod instances using one of three types of connections. The following embedded document reports the total number of connections by type.

connPoolStats.createdByType.master

master reports the total number of connections to the primary member in each cluster.

connPoolStats.createdByType.set

set reports the total number of connections to a replica set member.

connPoolStats.createdByType.sync

sync reports the total number of config database connections.

connPoolStats.totalAvailable

totalAvailable reports the running total of connections from the mongos or mongod to all mongod instances in the sharded cluster available for use.

connPoolStats.totalCreated

totalCreated reports the total number of connections ever created from the mongos or mongod to all mongod instances in the sharded cluster.

connPoolStats.numDBClientConnection

numDBClientConnection reports the total number of connections from the mongos or mongod to all of the mongod instances in the sharded cluster.

connPoolStats.numAScopedConnection

numAScopedConnection reports the number of exception safe connections created from mongos or mongod to all mongod in the sharded cluster. The mongos or mongod releases these connections after receiving a socket exception from the mongod.

shardConnPoolStats

Definition

shardConnPoolStats

Returns information on the pooled and cached connections in the sharded connection pool. The command also returns information on the per-thread connection cache in the connection pool.

The shardConnPoolStats command uses the following syntax:

{ shardConnPoolStats: 1 }

The sharded connection pool is specific to connections between members in a sharded cluster. The mongos instances in a cluster use the connection pool to execute client reads and writes. The mongod instances in a cluster use the pool when issuing mapReduce to query temporary collections on other shards.

When the cluster requires a connection, MongoDB pulls a connection from the sharded connection pool into the per-thread connection cache. MongoDB returns the connection to the connection pool after every operation.

Output

shardConnPoolStats.hosts

Displays connection status for each config server, replica set, and standalone instance in the cluster.

shardConnPoolStats.hosts.<host>.available

The number of connections available for this host to connect to the mongos.

shardConnPoolStats.hosts.<host>.created

The number of connections the host has ever created to connect to the mongos.

shardConnPoolStats.replicaSets

Displays information specific to replica sets.

shardConnPoolStats.replicaSets.<name>.host

Holds an array of documents that report on each replica set member. These values derive from the replica set status values.

shardConnPoolStats.replicaSets.<name>.host[n].addr

The host address in the format [hostname]:[port].

shardConnPoolStats.replicaSets.<name>.host[n].ok

This field is for internal use. Reports false when the mongos either cannot connect to instance or received a connection exception or error.

shardConnPoolStats.replicaSets.<name>.host[n].ismaster

The host is the replica set’s primary if this is set to true.

shardConnPoolStats.replicaSets.<name>.host[n].hidden

The host is a hidden member of the replica set if this is set to true.

shardConnPoolStats.replicaSets.<name>.host[n].secondary

The host is a hidden member of the replica set if this is set to true.

The host is a secondary member of the replica set if this is set to true.

shardConnPoolStats.replicaSets.<name>.host[n].pingTimeMillis

The latency, in milliseconds, from the mongos to this member.

shardConnPoolStats.replicaSets.<name>.host[n].tags

The member has tags configured.

shardConnPoolStats.createdByType

The number connections in the cluster’s connection pool.

shardConnPoolStats.createdByType.master

The number of connections to a shard.

shardConnPoolStats.createdByType.set

The number of connections to a replica set.

shardConnPoolStats.createdByType.sync

The number of connections to the config database.

shardConnPoolStats.totalAvailable

The number of connections available from the mongos to the config servers, replica sets, and standalone mongod instances in the cluster.

shardConnPoolStats.totalCreated

The number of connections the mongos has ever created to other members of the cluster.

shardConnPoolStats.threads

Displays information on the per-thread connection cache.

shardConnPoolStats.threads.hosts

Displays each incoming client connection. For a mongos, this array field displays one document per incoming client thread. For a mongod, the array displays one entry per incoming sharded mapReduce client thread.

shardConnPoolStats.threads.hosts.host

The host using the connection. The host can be a config server, replica set, or standalone instance.

shardConnPoolStats.threads.hosts.created

The number of times the host pulled a connection from the pool.

shardConnPoolStats.threads.hosts.avail

The thread’s availability.

shardConnPoolStats.threads.seenNS

The namespaces used on this connection thus far.

dbStats

Definition

dbStats

The dbStats command returns storage statistics for a given database. The command takes the following syntax:

{ dbStats: 1, scale: 1 }

The values of the options above do not affect the output of the command. The scale option allows you to specify how to scale byte values. For example, a scale value of 1024 will display the results in kilobytes rather than in bytes:

{ dbStats: 1, scale: 1024 }

Note

Because scaling rounds values to whole numbers, scaling may return unlikely or unexpected results.

The time required to run the command depends on the total size of the database. Because the command must touch all data files, the command may take several seconds to run.

In the mongo shell, the db.stats() function provides a wrapper around dbStats.

Output

dbStats.db

Contains the name of the database.

dbStats.collections

Contains a count of the number of collections in that database.

dbStats.objects

Contains a count of the number of objects (i.e. documents) in the database across all collections.

dbStats.avgObjSize

The average size of each document in bytes. This is the dataSize divided by the number of documents.

dbStats.dataSize

The total size in bytes of the data held in this database including the padding factor. The scale argument affects this value. The dataSize will not decrease when documents shrink, but will decrease when you remove documents.

dbStats.storageSize

The total amount of space in bytes allocated to collections in this database for document storage. The scale argument affects this value. The storageSize does not decrease as you remove or shrink documents.

dbStats.numExtents

Contains a count of the number of extents in the database across all collections.

dbStats.indexes

Contains a count of the total number of indexes across all collections in the database.

dbStats.indexSize

The total size in bytes of all indexes created on this database. The scale arguments affects this value.

dbStats.fileSize

The total size in bytes of the data files that hold the database. This value includes preallocated space and the padding factor. The value of fileSize only reflects the size of the data files for the database and not the namespace file.

The scale argument affects this value.

dbStats.nsSizeMB

The total size of the namespace files (i.e. that end with .ns) for this database. You cannot change the size of the namespace file after creating a database, but you can change the default size for all new namespace files with the nsSize runtime option.

See also

The nsSize option, and Maximum Namespace File Size

dbStats.dataFileVersion

New in version 2.4.

Document that contains information about the on-disk format of the data files for the database.

dbStats.dataFileVersion.major

New in version 2.4.

The major version number for the on-disk format of the data files for the database.

dbStats.dataFileVersion.minor

New in version 2.4.

The minor version number for the on-disk format of the data files for the database.

cursorInfo

Deprecated since version 2.6: Use the serverStatus command to return the serverStatus.metrics.cursor information instead.

cursorInfo

The cursorInfo command returns information about current cursor allotment and use. Use the following form:

{ cursorInfo: 1 }

The value (e.g. 1 above) does not affect the output of the command.

cursorInfo returns the total number of open cursors (totalOpen), the size of client cursors in current use (clientCursors_size), and the number of timed out cursors since the last server restart (timedOut).

dataSize

dataSize

The dataSize command returns the data size for a set of data within a certain range:

{ dataSize: "database.collection", keyPattern: { field: 1 }, min: { field: 10 }, max: { field: 100 } }

This will return a document that contains the size of all matching documents. Replace database.collection value with database and collection from your deployment. The keyPattern, min, and max parameters are options.

The amount of time required to return dataSize depends on the amount of data in the collection.

diagLogging

diagLogging

diagLogging is a command that captures additional data for diagnostic purposes and is not part of the stable client facing API.

diaglogging obtains a write lock on the affected database and will block other operations until it completes.

getCmdLineOpts

getCmdLineOpts

The getCmdLineOpts command returns a document containing command line options used to start the given mongod or mongos:

{ getCmdLineOpts: 1 }

This command returns a document with two fields, argv and parsed. The argv field contains an array with each item from the command string used to invoke mongod or mongos. The document in the parsed field includes all runtime options, including those parsed from the command line and those specified in the configuration file, if specified.

Consider the following example output of getCmdLineOpts:

{
        "argv" : [
               "/usr/bin/mongod",
               "--config",
               "/etc/mongodb.conf",
               "--fork"
        ],
        "parsed" : {
               "bind_ip" : "127.0.0.1",
               "config" : "/etc/mongodb/mongodb.conf",
               "dbpath" : "/srv/mongodb",
               "fork" : true,
               "logappend" : "true",
               "logpath" : "/var/log/mongodb/mongod.log",
               "quiet" : "true"
        },
        "ok" : 1
}

netstat

netstat

netstat is an internal command that is only available on mongos instances.

ping

ping

The ping command is a no-op used to test whether a server is responding to commands. This command will return immediately even if the server is write-locked:

{ ping: 1 }

The value (e.g. 1 above) does not impact the behavior of the command.

profile

profile

Use the profile command to enable, disable, or change the query profiling level. This allows administrators to capture data regarding performance. The database profiling system can impact performance and can allow the server to write the contents of queries to the log. Your deployment should carefully consider the security implications of this. Consider the following prototype syntax:

{ profile: <level> }

The following profiling levels are available:

Level | Setting
-1 | No change. Returns the current profile level.
0 | Off. No profiling.
1 | On. Only includes slow operations.
2 | On. Includes all operations.

You may optionally set a threshold in milliseconds for profiling using the slowms option, as follows:

{ profile: 1, slowms: 200 }

mongod writes the output of the database profiler to the system.profile collection.

mongod records queries that take longer than the slowOpThresholdMs to the server log even when the database profiler is not active.

See also

Additional documentation regarding Database Profiling.

See also

“db.getProfilingStatus()” and “db.setProfilingLevel()” provide wrappers around this functionality in the mongo shell.

Note

This command obtains a write lock on the affected database and will block other operations until it has completed. However, the write lock is only held while enabling or disabling the profiler. This is typically a short operation.

validate

Definition

validate

The validate command checks the structures within a namespace for correctness by scanning the collection’s data and indexes. The command returns information regarding the on-disk representation of the collection.

The validate command can be slow, particularly on larger data sets.

The following example validates the contents of the collection named users.

{ validate: "users" }

You may also specify one of the following options:

full: true provides a more thorough scan of the data.

scandata: false skips the scan of the base collection

without skipping the scan of the index.

The mongo shell also provides a wrapper:

db.collection.validate();

Use one of the following forms to perform the full collection validation:

db.collection.validate(true)
db.runCommand( { validate: "collection", full: true } )

Warning

This command is resource intensive and may have an impact on the performance of your MongoDB instance.

Output

validate.ns

The full namespace name of the collection. Namespaces include the database name and the collection name in the form database.collection.

validate.firstExtent

The disk location of the first extent in the collection. The value of this field also includes the namespace.

validate.lastExtent

The disk location of the last extent in the collection. The value of this field also includes the namespace.

validate.extentCount

The number of extents in the collection.

validate.extents

validate returns one instance of this document for every extent in the collection. This embedded document is only returned when you specify the full option to the command.

validate.extents.loc

The disk location for the beginning of this extent.

validate.extents.xnext

The disk location for the extent following this one. “null” if this is the end of the linked list of extents.

validate.extents.xprev

The disk location for the extent preceding this one. “null” if this is the head of the linked list of extents.

validate.extents.nsdiag

The namespace this extent belongs to (should be the same as the namespace shown at the beginning of the validate listing).

validate.extents.size

The number of bytes in this extent.

validate.extents.firstRecord

The disk location of the first record in this extent.

validate.extents.lastRecord

The disk location of the last record in this extent.

validate.datasize

The number of bytes in all data records. This value does not include deleted records, nor does it include extent headers, nor record headers, nor space in a file unallocated to any extent. datasize includes record padding.

validate.nrecords

The number of documents in the collection.

validate.lastExtentSize

The size of the last new extent created in this collection. This value determines the size of the next extent created.

validate.padding

A floating point value between 1 and 2.

When MongoDB creates a new record it uses the padding factor to determine how much additional space to add to the record. The padding factor is automatically adjusted by mongo when it notices that update operations are triggering record moves.

validate.firstExtentDetails

The size of the first extent created in this collection. This data is similar to the data provided by the extents embedded document; however, the data reflects only the first extent in the collection and is always returned.

validate.firstExtentDetails.loc

The disk location for the beginning of this extent.

validate.firstExtentDetails.xnext

The disk location for the extent following this one. “null” if this is the end of the linked list of extents, which should only be the case if there is only one extent.

validate.firstExtentDetails.xprev

The disk location for the extent preceding this one. This should always be “null.”

validate.firstExtentDetails.nsdiag

The namespace this extent belongs to (should be the same as the namespace shown at the beginning of the validate listing).

validate.firstExtentDetails.size

The number of bytes in this extent.

validate.firstExtentDetails.firstRecord

The disk location of the first record in this extent.

validate.firstExtentDetails.lastRecord

The disk location of the last record in this extent.

validate.objectsFound

The number of records actually encountered in a scan of the collection. This field should have the same value as the nrecords field.

validate.invalidObjects

The number of records containing BSON documents that do not pass a validation check.

Note

This field is only included in the validation output when you specify the full option.

validate.bytesWithHeaders

This is similar to datasize, except that bytesWithHeaders includes the record headers. In version 2.0, record headers are 16 bytes per document.

Note

This field is only included in the validation output when you specify the full option.

validate.bytesWithoutHeaders

bytesWithoutHeaders returns data collected from a scan of all records. The value should be the same as datasize.

Note

This field is only included in the validation output when you specify the full option.

validate.deletedCount

The number of deleted or “free” records in the collection.

validate.deletedSize

The size of all deleted or “free” records in the collection.

validate.nIndexes

The number of indexes on the data in the collection.

validate.keysPerIndex

A document containing a field for each index, named after the index’s name, that contains the number of keys, or documents referenced, included in the index.

validate.valid

Boolean. true, unless validate determines that an aspect of the collection is not valid. When false, see the errors field for more information.

validate.errors

Typically empty; however, if the collection is not valid (i.e valid is false), this field will contain a message describing the validation error.

validate.ok

Set to 1 when the command succeeds. If the command fails the ok field has a value of 0.

top

top

top is an administrative command that returns usage statistics for each collection. top provides amount of time, in microseconds, used and a count of operations for the following event types:

total

readLock

writeLock

queries

getmore

insert

update

remove

commands

Issue the top command against the admin database in the form:

{ top: 1 }

Example

At the mongo shell prompt, use top with the following evocation:

db.adminCommand("top")

Alternately you can use top as follows:

use admin
db.runCommand( { top: 1 } )

The output of the top command would resemble the following output:

{
  "totals" : {
     "records.users" : {
                  "total" : {
                          "time" : 305277,
                          "count" : 2825
                  },
                  "readLock" : {
                          "time" : 305264,
                          "count" : 2824
                  },
                  "writeLock" : {
                          "time" : 13,
                          "count" : 1
                  },
                  "queries" : {
                          "time" : 305264,
                          "count" : 2824
                  },
                  "getmore" : {
                          "time" : 0,
                          "count" : 0
                  },
                  "insert" : {
                          "time" : 0,
                          "count" : 0
                  },
                  "update" : {
                          "time" : 0,
                          "count" : 0
                  },
                  "remove" : {
                          "time" : 0,
                          "count" : 0
                  },
                  "commands" : {
                          "time" : 0,
                          "count" : 0
                  }
          }
}

indexStats

Definition

indexStats

The indexStats command aggregates statistics for the B-tree data structure that stores data for a MongoDB index.

Warning

This command is not intended for production deployments.

The command can be run only on a mongod instance that uses the --enableExperimentalIndexStatsCmd option.

To aggregate statistics, issue the command like so:

db.runCommand( { indexStats: "<collection>", index: "<index name>" } )

Output

The db.collection.indexStats() method and equivalent indexStats command aggregate statistics for the B-tree data structure that stores data for a MongoDB index. The commands aggregate statistics firstly for the entire B-tree and secondly for each individual level of the B-tree. The output displays the following values.

indexStats.index

The index name.

indexStats.version

The index version. For more information on index version numbers, see the v option in db.collection.ensureIndex().

indexStats.isIdIndex

If true, the index is the default _id index for the collection.

indexStats.keyPattern

The indexed keys.

indexStats.storageNs

The namespace of the index’s underlying storage.

indexStats.bucketBodyBytes

The fixed size, in bytes, of a B-tree bucket in the index, not including the record header. All indexes for a given version have the same value for this field. MongoDB allocates fixed size buckets on disk.

indexStats.depth

The number of levels in the B-tree, not including the root level.

indexStats.overall

This section of the output displays statistics for the entire B-tree.

indexStats.overall.numBuckets

The number of buckets in the entire B-tree, including all levels.

indexStats.overall.keyCount

Statistics about the number of keys in a bucket, evaluated on a per-bucket level.

indexStats.overall.usedKeyCount

Statistics about the number of used keys in a bucket, evaluated on a per-bucket level. Used keys are keys not marked as deleted.

indexStats.overall.bsonRatio

Statistics about the percentage of the bucket body that is occupied by the key objects themselves, excluding associated metadata.

For example, if you have the document { name: "Bob Smith" } and an index on { name: 1 }, the key object is the string Bob Smith.

indexStats.overall.keyNodeRatio

Statistics about the percentage of the bucket body that is occupied by the key node objects (the metadata and links pertaining to the keys). This does not include the key itself. In the current implementation, a key node’s objects consist of: the pointer to the key data (in the same bucket), the pointer to the record the key is for, and the pointer to a child bucket.

indexStats.overall.fillRatio

The sum of the bsonRatio and the keyNodeRatio. This shows how full the buckets are. This will be much higher for indexes with sequential inserts.

indexStats.perLevel

This section of the output displays statistics for each level of the B-tree separately, starting with the root level. This section displays a different document for each B-tree level.

indexStats.perLevel.numBuckets

The number of buckets at this level of the B-tree.

indexStats.perLevel.keyCount

Statistics about the number of keys in a bucket, evaluated on a per-bucket level.

indexStats.perLevel.usedKeyCount

Statistics about the number of used keys in a bucket, evaluated on a per-bucket level. Used keys are keys not marked as deleted.

indexStats.perLevel.bsonRatio

Statistics about the percentage of the bucket body that is occupied by the key objects themselves, excluding associated metadata.

indexStats.perLevel.keyNodeRatio

Statistics about the percentage of the bucket body that is occupied by the key node objects (the metadata and links pertaining to the keys).

indexStats.perLevel.fillRatio

The sum of the bsonRatio and the keyNodeRatio. This shows how full the buckets are. This will be much higher in the following cases:

For indexes with sequential inserts, such as the _id index when using ObjectId keys.

For indexes that were recently built in the foreground with existing data.

If you recently ran compact or --repair.

Example

The following is an example of db.collection.indexStats() and indexStats output.

{
    "index" : "type_1_traits_1",
    "version" : 1,
    "isIdIndex" : false,
    "keyPattern" : {
        "type" : 1,
        "traits" : 1
    },
    "storageNs" : "test.animals.$type_1_traits_1",
    "bucketBodyBytes" : 8154,
    "depth" : 2,
    "overall" : {
        "numBuckets" : 45513,
        "keyCount" : {
            "count" : NumberLong(45513),
            "mean" : 253.89602970579836,
            "stddev" : 21.784799875240708,
            "min" : 52,
            "max" : 290,
            "quantiles" : {
                "0.01" : 201.99785091648775,
                // ...
                "0.99" : 289.9999655156967
            }
        },
        "usedKeyCount" : {
            "count" : NumberLong(45513),
            // ...
            "quantiles" : {
                "0.01" : 201.99785091648775,
                // ...
                "0.99" : 289.9999655156967
            }
        },
        "bsonRatio" : {
            "count" : NumberLong(45513),
            // ...
            "quantiles" : {
                "0.01" : 0.4267797891997124,
                // ...
                "0.99" : 0.5945548174629648
            }
        },
        "keyNodeRatio" : {
            "count" : NumberLong(45513),
            // ...
            "quantiles" : {
                "0.01" : 0.3963656628236211,
                // ...
                "0.99" : 0.5690457993930765
            }
        },
        "fillRatio" : {
            "count" : NumberLong(45513),
            // ...
            "quantiles" : {
                "0.01" : 0.9909134214926929,
                // ...
                "0.99" : 0.9960755457453732
            }
        }
    },
    "perLevel" : [
        {
            "numBuckets" : 1,
            "keyCount" : {
                "count" : NumberLong(1),
                "mean" : 180,
                "stddev" : 0,
                "min" : 180,
                "max" : 180
            },
            "usedKeyCount" : {
                "count" : NumberLong(1),
                // ...
                "max" : 180
            },
            "bsonRatio" : {
                "count" : NumberLong(1),
                // ...
                "max" : 0.3619082658817758
            },
            "keyNodeRatio" : {
                "count" : NumberLong(1),
                // ...
                "max" : 0.35320088300220753
            },
            "fillRatio" : {
                "count" : NumberLong(1),
                // ...
                "max" : 0.7151091488839834
            }
        },
        {
            "numBuckets" : 180,
            "keyCount" : {
                "count" : NumberLong(180),
                "mean" : 250.84444444444443,
                "stddev" : 26.30057503009355,
                "min" : 52,
                "max" : 290
            },
            "usedKeyCount" : {
                "count" : NumberLong(180),
                // ...
                "max" : 290
            },
            "bsonRatio" : {
                "count" : NumberLong(180),
                // ...
                "max" : 0.5945548197203826
            },
            "keyNodeRatio" : {
                "count" : NumberLong(180),
                // ...
                "max" : 0.5690458670591121
            },
            "fillRatio" : {
                "count" : NumberLong(180),
                // ...
                "max" : 0.9963208241353937
            }
        },
        {
            "numBuckets" : 45332,
            "keyCount" : {
                "count" : NumberLong(45332),
                "mean" : 253.90977675813994,
                "stddev" : 21.761620836279018,
                "min" : 167,
                "max" : 290,
                "quantiles" : {
                    "0.01" : 202.0000012563603,
                    // ...
                    "0.99" : 289.99996486571894
                }
            },
            "usedKeyCount" : {
                "count" : NumberLong(45332),
                // ...
                "quantiles" : {
                    "0.01" : 202.0000012563603,
                    // ...
                    "0.99" : 289.99996486571894
                }
            },
            "bsonRatio" : {
                "count" : NumberLong(45332),
                // ...
                "quantiles" : {
                    "0.01" : 0.42678446958950583,
                    // ...
                    "0.99" : 0.5945548175411283
                }
            },
            "keyNodeRatio" : {
                "count" : NumberLong(45332),
                // ...
                "quantiles" : {
                    "0.01" : 0.39636988227885306,
                    // ...
                    "0.99" : 0.5690457981176729
                }
            },
            "fillRatio" : {
                "count" : NumberLong(45332),
                // ...
                "quantiles" : {
                    "0.01" : 0.9909246995605362,
                    // ...
                    "0.99" : 0.996075546919481
                }
            }
        }
    ],
    "ok" : 1
}

Additional Resources

For more information on the command’s limits and output, see the following:

The equivalent db.collection.indexStats() method,

indexStats, and

https://github.com/10gen-labs/storage-viz#readme.

whatsmyuri

whatsmyuri

whatsmyuri is an internal command.

getLog

getLog

The getLog command returns a document with a log array that contains recent messages from the mongod process log. The getLog command has the following syntax:

{ getLog: <log> }

Replace <log> with one of the following values:

global - returns the combined output of all recent log entries.

rs - if the mongod is part of a replica set, getLog will return recent notices related to replica set activity.

startupWarnings - will return logs that may contain errors or warnings from MongoDB’s log from when the current process started. If mongod started without warnings, this filter may return an empty array.

You may also specify an asterisk (e.g. *) as the <log> value to return a list of available log filters. The following interaction from the mongo shell connected to a replica set:

db.adminCommand({getLog: "*" })
{ "names" : [ "global", "rs", "startupWarnings" ], "ok" : 1 }

getLog returns events from a RAM cache of the mongod events and does not read log data from the log file.

hostInfo

hostInfo

New in version 2.2.

Returns:
A document with information about the underlying system that the mongod or mongos runs on. Some of the returned fields are only included on some platforms.

You must run the hostInfo command, which takes no arguments, against the admin database. Consider the following invocations of hostInfo:

db.hostInfo()
db.adminCommand( { "hostInfo" : 1 } )

In the mongo shell you can use db.hostInfo() as a helper to access hostInfo. The output of hostInfo on a Linux system will resemble the following:

{
   "system" : {
          "currentTime" : ISODate("<timestamp>"),
          "hostname" : "<hostname>",
          "cpuAddrSize" : <number>,
          "memSizeMB" : <number>,
          "numCores" : <number>,
          "cpuArch" : "<identifier>",
          "numaEnabled" : <boolean>
   },
   "os" : {
          "type" : "<string>",
          "name" : "<string>",
          "version" : "<string>"
   },
   "extra" : {
          "versionString" : "<string>",
          "libcVersion" : "<string>",
          "kernelVersion" : "<string>",
          "cpuFrequencyMHz" : "<string>",
          "cpuFeatures" : "<string>",
          "pageSize" : <number>,
          "numPages" : <number>,
          "maxOpenFiles" : <number>
   },
   "ok" : <return>
}

Consider the following documentation of these fields:

hostInfo

The document returned by the hostInfo.

hostInfo.system

An embedded document providing information about the underlying environment of the system running the mongod or mongos

hostInfo.system.currentTime

A time stamp of the current system time.

hostInfo.system.hostname

The system name, which should correspond to the output of hostname -f on Linux systems.

hostInfo.system.cpuAddrSize

A number reflecting the architecture of the system. Either 32 or 64.

hostInfo.system.memSizeMB

The total amount of system memory (RAM) in megabytes.

hostInfo.system.numCores

The total number of available logical processor cores.

hostInfo.system.cpuArch

A string that represents the system architecture. Either x86 or x86_64.

hostInfo.system.numaEnabled

A boolean value. false if NUMA is interleaved (i.e. disabled), otherwise true.

hostInfo.os

An embedded document that contains information about the operating system running the mongod and mongos.

hostInfo.os.type

A string representing the type of operating system, such as Linux or Windows.

hostInfo.os.name

If available, returns a display name for the operating system.

hostInfo.os.version

If available, returns the name of the distribution or operating system.

hostInfo.extra

An embedded document with extra information about the operating system and the underlying hardware. The content of the extra embedded document depends on the operating system.

hostInfo.extra.versionString

A complete string of the operating system version and identification. On Linux and OS X systems, this contains output similar to uname -a.

hostInfo.extra.libcVersion

The release of the system libc.

libcVersion only appears on Linux systems.

hostInfo.extra.kernelVersion

The release of the Linux kernel in current use.

kernelVersion only appears on Linux systems.

hostInfo.extra.alwaysFullSync

alwaysFullSync only appears on OS X systems.

hostInfo.extra.nfsAsync

nfsAsync only appears on OS X systems.

hostInfo.extra.cpuFrequencyMHz

Reports the clock speed of the system’s processor in megahertz.

hostInfo.extra.cpuFeatures

Reports the processor feature flags. On Linux systems this the same information that /proc/cpuinfo includes in the flags fields.

hostInfo.extra.pageSize

Reports the default system page size in bytes.

hostInfo.extra.numPages

numPages only appears on Linux systems.

hostInfo.extra.maxOpenFiles

Reports the current system limits on open file handles. See UNIX ulimit Settings for more information.

maxOpenFiles only appears on Linux systems.

hostInfo.extra.scheduler

Reports the active I/O scheduler. scheduler only appears on OS X systems.

serverStatus

Definition

serverStatus

The serverStatus command returns a document that provides an overview of the database process’s state. Most monitoring applications run this command at a regular interval to collection statistics about the instance:

{ serverStatus: 1 }

The value (i.e. 1 above), does not affect the operation of the command.

Changed in version 2.4: In 2.4 you can dynamically suppress portions of the serverStatus output, or include suppressed sections by adding fields to the command document as in the following examples:

db.runCommand( { serverStatus: 1, repl: 0, indexCounters: 0 } )
db.runCommand( { serverStatus: 1, workingSet: 1, metrics: 0, locks: 0 } )

serverStatus includes all fields by default, except workingSet.

Note

You may only dynamically include top-level fields from the serverStatus document that are not included by default. You can exclude any field that serverStatus includes by default.

See also

db.serverStatus()

Output

The serverStatus command returns a collection of information that reflects the database’s status. These data are useful for diagnosing and assessing the performance of your MongoDB instance. This reference catalogs each datum included in the output of this command and provides context for using this data to more effectively administer your database.

See also

Much of the output of serverStatus is also displayed dynamically by mongostat. See the mongostat command for more information.

For examples of the serverStatus output, see Server Status Output.

Instance Information

For an example of the instance information, see the Instance Information section of the Server Status Output page.

serverStatus.host

The host field contains the system’s hostname. In Unix/Linux systems, this should be the same as the output of the hostname command.

serverStatus.version

The version field contains the version of MongoDB running on the current mongod or mongos instance.

serverStatus.process

The process field identifies which kind of MongoDB instance is running. Possible values are:

mongos

mongod

serverStatus.uptime

The value of the uptime field corresponds to the number of seconds that the mongos or mongod process has been active.

serverStatus.uptimeEstimate

uptimeEstimate provides the uptime as calculated from MongoDB’s internal course-grained time keeping system.

serverStatus.localTime

The localTime value is the current time, according to the server, in UTC specified in an ISODate format.

locks

New in version 2.1.2: All locks statuses first appeared in the 2.1.2 development release for the 2.2 series.

For an example of the locks output, see the locks section of the Server Status Output page.

serverStatus.locks

The locks document contains sub-documents that provides a granular report on MongoDB database-level lock use. All values are of the NumberLong() type.

Generally, fields named:

R refer to the global read lock,

W refer to the global write lock,

r refer to the database specific read lock, and

w refer to the database specific write lock.

If a document does not have any fields, it means that no locks have existed with this context since the last time the mongod started.

serverStatus.locks..

A field named . holds the first document in locks that contains information about the global lock.

serverStatus.locks...timeLockedMicros

The timeLockedMicros document reports the amount of time in microseconds that a lock has existed in all databases in this mongod instance.

serverStatus.locks...timeLockedMicros.R

The R field reports the amount of time in microseconds that any database has held the global read lock.

serverStatus.locks...timeLockedMicros.W

The W field reports the amount of time in microseconds that any database has held the global write lock.

serverStatus.locks...timeLockedMicros.r

The r field reports the amount of time in microseconds that any database has held the local read lock.

serverStatus.locks...timeLockedMicros.w

The w field reports the amount of time in microseconds that any database has held the local write lock.

serverStatus.locks...timeAcquiringMicros

The timeAcquiringMicros document reports the amount of time in microseconds that operations have spent waiting to acquire a lock in all databases in this mongod instance.

serverStatus.locks...timeAcquiringMicros.R

The R field reports the amount of time in microseconds that any database has spent waiting for the global read lock.

serverStatus.locks...timeAcquiringMicros.W

The W field reports the amount of time in microseconds that any database has spent waiting for the global write lock.

serverStatus.locks.admin

The admin document contains two sub-documents that report data regarding lock use in the admin database.

serverStatus.locks.admin.timeLockedMicros

The timeLockedMicros document reports the amount of time in microseconds that locks have existed in the context of the admin database.

serverStatus.locks.admin.timeLockedMicros.r

The r field reports the amount of time in microseconds that the admin database has held the read lock.

serverStatus.locks.admin.timeLockedMicros.w

The w field reports the amount of time in microseconds that the admin database has held the write lock.

serverStatus.locks.admin.timeAcquiringMicros

The timeAcquiringMicros document reports on the amount of field time in microseconds that operations have spent waiting to acquire a lock for the admin database.

serverStatus.locks.admin.timeAcquiringMicros.r

The r field reports the amount of time in microseconds that operations have spent waiting to acquire a read lock on the admin database.

serverStatus.locks.admin.timeAcquiringMicros.w

The w field reports the amount of time in microseconds that operations have spent waiting to acquire a write lock on the admin database.

serverStatus.locks.local

The local document contains two sub-documents that report data regarding lock use in the local database. The local database contains a number of instance specific data, including the oplog for replication.

serverStatus.locks.local.timeLockedMicros

The timeLockedMicros document reports on the amount of time in microseconds that locks have existed in the context of the local database.

serverStatus.locks.local.timeLockedMicros.r

The r field reports the amount of time in microseconds that the local database has held the read lock.

serverStatus.locks.local.timeLockedMicros.w

The w field reports the amount of time in microseconds that the local database has held the write lock.

serverStatus.locks.local.timeAcquiringMicros

The timeAcquiringMicros document reports on the amount of time in microseconds that operations have spent waiting to acquire a lock for the local database.

serverStatus.locks.local.timeAcquiringMicros.r

The r field reports the amount of time in microseconds that operations have spent waiting to acquire a read lock on the local database.

serverStatus.locks.local.timeAcquiringMicros.w

The w field reports the amount of time in microseconds that operations have spent waiting to acquire a write lock on the local database.

serverStatus.locks.<database>

For each additional database locks includes a document that reports on the lock use for this database. The names of these documents reflect the database name itself.

serverStatus.locks.<database>.timeLockedMicros

The timeLockedMicros document reports on the amount of time in microseconds that locks have existed in the context of the <database> database.

serverStatus.locks.<database>.timeLockedMicros.r

The r field reports the amount of time in microseconds that the <database> database has held the read lock.

serverStatus.locks.<database>.timeLockedMicros.w

The w field reports the amount of time in microseconds that the <database> database has held the write lock.

serverStatus.locks.<database>.timeAcquiringMicros

The timeAcquiringMicros document reports on the amount of time in microseconds that operations have spent waiting to acquire a lock for the <database> database.

serverStatus.locks.<database>.timeAcquiringMicros.r

The r field reports the amount of time in microseconds that operations have spent waiting to acquire a read lock on the <database> database.

serverStatus.locks.<database>.timeAcquiringMicros.w

The w field reports the amount of time in microseconds that operations have spent waiting to acquire a write lock on the <database> database.

globalLock

For an example of the globalLock output, see the globalLock section of the Server Status Output page.

serverStatus.globalLock

The globalLock data structure contains information regarding the database’s current lock state, historical lock status, current operation queue, and the number of active clients.

serverStatus.globalLock.totalTime

The value of totalTime represents the time, in microseconds, since the database last started and creation of the globalLock. This is roughly equivalent to total server uptime.

serverStatus.globalLock.lockTime

The value of lockTime represents the time, in microseconds, since the database last started, that the globalLock has been held.

Consider this value in combination with the value of totalTime. MongoDB aggregates these values in the ratio value. If the ratio value is small but totalTime is high the globalLock has typically been held frequently for shorter periods of time, which may be indicative of a more normal use pattern. If the lockTime is higher and the totalTime is smaller (relatively) then fewer operations are responsible for a greater portion of server’s use (relatively).

serverStatus.globalLock.ratio

Changed in version 2.2: ratio was removed. See locks.

The value of ratio displays the relationship between lockTime and totalTime.

Low values indicate that operations have held the globalLock frequently for shorter periods of time. High values indicate that operations have held globalLock infrequently for longer periods of time.

serverStatus.globalLock.currentQueue

The currentQueue data structure value provides more granular information concerning the number of operations queued because of a lock.

serverStatus.globalLock.currentQueue.total

The value of total provides a combined total of operations queued waiting for the lock.

A consistently small queue, particularly of shorter operations should cause no concern. Also, consider this value in light of the size of queue waiting for the read lock (e.g. readers) and write lock (e.g. writers) individually.

serverStatus.globalLock.currentQueue.readers

The value of readers is the number of operations that are currently queued and waiting for the read lock. A consistently small read-queue, particularly of shorter operations should cause no concern.

serverStatus.globalLock.currentQueue.writers

The value of writers is the number of operations that are currently queued and waiting for the write lock. A consistently small write-queue, particularly of shorter operations is no cause for concern.

globalLock.activeClients

serverStatus.globalLock.activeClients

The activeClients data structure provides more granular information about the number of connected clients and the operation types (e.g. read or write) performed by these clients.

Use this data to provide context for the currentQueue data.

serverStatus.globalLock.activeClients.total

The value of total is the total number of active client connections to the database. This combines clients that are performing read operations (e.g. readers) and clients that are performing write operations (e.g. writers).

serverStatus.globalLock.activeClients.readers

The value of readers contains a count of the active client connections performing read operations.

serverStatus.globalLock.activeClients.writers

The value of writers contains a count of active client connections performing write operations.

mem

For an example of the mem output, see the mem section of the Server Status Output page.

serverStatus.mem

The mem data structure holds information regarding the target system architecture of mongod and current memory use.

serverStatus.mem.bits

The value of bits is either 64 or 32, depending on which target architecture specified during the mongod compilation process. In most instances this is 64, and this value does not change over time.

serverStatus.mem.resident

The value of resident is roughly equivalent to the amount of RAM, in megabytes (MB), currently used by the database process. In normal use this value tends to grow. In dedicated database servers this number tends to approach the total amount of system memory.

serverStatus.mem.virtual

virtual displays the quantity, in megabytes (MB), of virtual memory used by the mongod process. With journaling enabled, the value of virtual is at least twice the value of mapped.

If virtual value is significantly larger than mapped (e.g. 3 or more times), this may indicate a memory leak.

serverStatus.mem.supported

supported is true when the underlying system supports extended memory information. If this value is false and the system does not support extended memory information, then other mem values may not be accessible to the database server.

serverStatus.mem.mapped

The value of mapped provides the amount of mapped memory, in megabytes (MB), by the database. Because MongoDB uses memory-mapped files, this value is likely to be to be roughly equivalent to the total size of your database or databases.

serverStatus.mem.mappedWithJournal

mappedWithJournal provides the amount of mapped memory, in megabytes (MB), including the memory used for journaling. This value will always be twice the value of mapped. This field is only included if journaling is enabled.

connections

For an example of the connections output, see the connections section of the Server Status Output page.

serverStatus.connections

The connections sub document data regarding the current status of incoming connections and availability of the database server. Use these values to assess the current load and capacity requirements of the server.

serverStatus.connections.current

The value of current corresponds to the number of connections to the database server from clients. This number includes the current shell session. Consider the value of available to add more context to this datum.

This figure will include all incoming connections including any shell connections or connections from other servers, such as replica set members or mongos instances.

serverStatus.connections.available

available provides a count of the number of unused available incoming connections the database can provide. Consider this value in combination with the value of current to understand the connection load on the database, and the UNIX ulimit Settings document for more information about system thresholds on available connections.

serverStatus.connections.totalCreated

totalCreated provides a count of all incoming connections created to the server. This number includes connections that have since closed.

extra_info

For an example of the extra_info output, see the extra_info section of the Server Status Output page.

serverStatus.extra_info

The extra_info data structure holds data collected by the mongod instance about the underlying system. Your system may only report a subset of these fields.

serverStatus.extra_info.note

The field note reports that the data in this structure depend on the underlying platform, and has the text: “fields vary by platform.”

serverStatus.extra_info.heap_usage_bytes

The heap_usage_bytes field is only available on Unix/Linux systems, and reports the total size in bytes of heap space used by the database process.

serverStatus.extra_info.page_faults

The page_faults Reports the total number of page faults that require disk operations. Page faults refer to operations that require the database server to access data which isn’t available in active memory. The page_faults counter may increase dramatically during moments of poor performance and may correlate with limited memory environments and larger data sets. Limited and sporadic page faults do not necessarily indicate an issue.

indexCounters

For an example of the indexCounters output, see the indexCounters section of the Server Status Output page.

serverStatus.indexCounters

Changed in version 2.2: Previously, data in the indexCounters document reported sampled data, and were only useful in relative comparison to each other, because they could not reflect absolute index use. In 2.2 and later, these data reflect actual index use.

Changed in version 2.4: Fields previously in the btree embedded document of indexCounters are now fields in the indexCounters document.

The indexCounters data structure reports information regarding the state and use of indexes in MongoDB.

serverStatus.indexCounters.accesses

accesses reports the number of times that operations have accessed indexes. This value is the combination of the hits and misses. Higher values indicate that your database has indexes and that queries are taking advantage of these indexes. If this number does not grow over time, this might indicate that your indexes do not effectively support your use.

serverStatus.indexCounters.hits

The hits value reflects the number of times that an index has been accessed and mongod is able to return the index from memory.

A higher value indicates effective index use. hits values that represent a greater proportion of the accesses value, tend to indicate more effective index configuration.

serverStatus.indexCounters.misses

The misses value represents the number of times that an operation attempted to access an index that was not in memory. These “misses,” do not indicate a failed query or operation, but rather an inefficient use of the index. Lower values in this field indicate better index use and likely overall performance as well.

serverStatus.indexCounters.resets

The resets value reflects the number of times that the index counters have been reset since the database last restarted. Typically this value is 0, but use this value to provide context for the data specified by other indexCounters values.

serverStatus.indexCounters.missRatio

The missRatio value is the ratio of hits to misses. This value is typically 0 or approaching 0.

backgroundFlushing

For an example of the backgroundFlushing output, see the backgroundFlushing section of the Server Status Output page.

serverStatus.backgroundFlushing

mongod periodically flushes writes to disk. In the default configuration, this happens every 60 seconds. The backgroundFlushing data structure contains data regarding these operations. Consider these values if you have concerns about write performance and journaling.

serverStatus.backgroundFlushing.flushes

flushes is a counter that collects the number of times the database has flushed all writes to disk. This value will grow as database runs for longer periods of time.

serverStatus.backgroundFlushing.total_ms

The total_ms value provides the total number of milliseconds (ms) that the mongod processes have spent writing (i.e. flushing) data to disk. Because this is an absolute value, consider the value of flushes and average_ms to provide better context for this datum.

serverStatus.backgroundFlushing.average_ms

The average_ms value describes the relationship between the number of flushes and the total amount of time that the database has spent writing data to disk. The larger flushes is, the more likely this value is likely to represent a “normal,” time; however, abnormal data can skew this value.

Use the last_ms to ensure that a high average is not skewed by transient historical issue or a random write distribution.

serverStatus.backgroundFlushing.last_ms

The value of the last_ms field is the amount of time, in milliseconds, that the last flush operation took to complete. Use this value to verify that the current performance of the server and is in line with the historical data provided by average_ms and total_ms.

serverStatus.backgroundFlushing.last_finished

The last_finished field provides a timestamp of the last completed flush operation in the ISODate format. If this value is more than a few minutes old relative to your server’s current time and accounting for differences in time zone, restarting the database may result in some data loss.

Also consider ongoing operations that might skew this value by routinely block write operations.

cursors

Deprecated since version 2.6: See the serverStatus.metrics.cursor field instead.

For an example of the cursors output, see the cursors section of the Server Status Output page.

serverStatus.cursors

The cursors data structure contains data regarding cursor state and use.

serverStatus.cursors.note

A note specifying to use the serverStatus.metrics.cursor field instead of serverStatus.cursors.

serverStatus.cursors.totalOpen

totalOpen provides the number of cursors that MongoDB is maintaining for clients. Because MongoDB exhausts unused cursors, typically this value small or zero. However, if there is a queue, stale tailable cursor, or a large number of operations, this value may rise.

serverStatus.cursors.clientCursors_size

Deprecated since version 1.x: See totalOpen for this datum.

serverStatus.cursors.timedOut

timedOut provides a counter of the total number of cursors that have timed out since the server process started. If this number is large or growing at a regular rate, this may indicate an application error.

serverStatus.cursors.totalNoTimeout

totalNoTimeout provides the number of open cursors with the option DBQuery.Option.noTimeout set to prevent timeout after a period of inactivity.

serverStatus.cursors.pinned

serverStatus.cursors.pinned provides the number of “pinned” open cursors.

network

For an example of the network output, see the network section of the Server Status Output page.

serverStatus.network

The network data structure contains data regarding MongoDB’s network use.

serverStatus.network.bytesIn

The value of the bytesIn field reflects the amount of network traffic, in bytes, received by this database. Use this value to ensure that network traffic sent to the mongod process is consistent with expectations and overall inter-application traffic.

serverStatus.network.bytesOut

The value of the bytesOut field reflects the amount of network traffic, in bytes, sent from this database. Use this value to ensure that network traffic sent by the mongod process is consistent with expectations and overall inter-application traffic.

serverStatus.network.numRequests

The numRequests field is a counter of the total number of distinct requests that the server has received. Use this value to provide context for the bytesIn and bytesOut values to ensure that MongoDB’s network utilization is consistent with expectations and application use.

repl

For an example of the repl output, see the repl section of the Server Status Output page.

serverStatus.repl

The repl data structure contains status information for MongoDB’s replication (i.e. “replica set”) configuration. These values only appear when the current host has replication enabled.

See Replication for more information on replication.

serverStatus.repl.setName

The setName field contains a string with the name of the current replica set. This value reflects the --replSet command line argument, or replSetName value in the configuration file.

See Replication for more information on replication.

serverStatus.repl.ismaster

The value of the ismaster field is either true or false and reflects whether the current node is the master or primary node in the replica set.

See Replication for more information on replication.

serverStatus.repl.secondary

The value of the secondary field is either true or false and reflects whether the current node is a secondary node in the replica set.

See Replication for more information on replication.

serverStatus.repl.hosts

hosts is an array that lists the other nodes in the current replica set. Each member of the replica set appears in the form of hostname:port.

See Replication for more information on replication.

opcountersRepl

For an example of the opcountersRepl output, see the opcountersRepl section of the Server Status Output page.

serverStatus.opcountersRepl

The opcountersRepl data structure, similar to the opcounters data structure, provides an overview of database replication operations by type and makes it possible to analyze the load on the replica in more granular manner. These values only appear when the current host has replication enabled.

These values will differ from the opcounters values because of how MongoDB serializes operations during replication. See Replication for more information on replication.

These numbers will grow over time in response to database use. Analyze these values over time to track database utilization.

serverStatus.opcountersRepl.insert

insert provides a counter of the total number of replicated insert operations since the mongod instance last started.

serverStatus.opcountersRepl.query

query provides a counter of the total number of replicated queries since the mongod instance last started.

serverStatus.opcountersRepl.update

update provides a counter of the total number of replicated update operations since the mongod instance last started.

serverStatus.opcountersRepl.delete

delete provides a counter of the total number of replicated delete operations since the mongod instance last started.

serverStatus.opcountersRepl.getmore

getmore provides a counter of the total number of “getmore” operations since the mongod instance last started. This counter can be high even if the query count is low. Secondary nodes send getMore operations as part of the replication process.

serverStatus.opcountersRepl.command

command provides a counter of the total number of replicated commands issued to the database since the mongod instance last started.

opcounters

For an example of the opcounters output, see the opcounters section of the Server Status Output page.

serverStatus.opcounters

The opcounters data structure provides an overview of database operations by type and makes it possible to analyze the load on the database in more granular manner.

These numbers will grow over time and in response to database use. Analyze these values over time to track database utilization.

Note

The data in opcounters treats operations that affect multiple documents, such as bulk insert or multi-update operations, as a single operation. See document for more granular document-level operation tracking.

Additionally, these values reflect received operations, and increment even when operations are not successful.

serverStatus.opcounters.insert

insert provides a counter of the total number of insert operations received since the mongod instance last started.

serverStatus.opcounters.query

query provides a counter of the total number of queries received since the mongod instance last started.

serverStatus.opcounters.update

update provides a counter of the total number of update operations recieved since the mongod instance last started.

serverStatus.opcounters.delete

delete provides a counter of the total number of delete operations since the mongod instance last started.

serverStatus.opcounters.getmore

getmore provides a counter of the total number of “getmore” operations since the mongod instance last started. This counter can be high even if the query count is low. Secondary nodes send getMore operations as part of the replication process.

serverStatus.opcounters.command

command provides a counter of the total number of commands issued to the database since the mongod instance last started.

asserts

For an example of the asserts output, see the asserts section of the Server Status Output page.

serverStatus.asserts

The asserts document reports the number of asserts on the database. While assert errors are typically uncommon, if there are non-zero values for the asserts, you should check the log file for the mongod process for more information. In many cases these errors are trivial, but are worth investigating.

serverStatus.asserts.regular

The regular counter tracks the number of regular assertions raised since the server process started. Check the log file for more information about these messages.

serverStatus.asserts.warning

The warning counter tracks the number of warnings raised since the server process started. Check the log file for more information about these warnings.

serverStatus.asserts.msg

The msg counter tracks the number of message assertions raised since the server process started. Check the log file for more information about these messages.

serverStatus.asserts.user

The user counter reports the number of “user asserts” that have occurred since the last time the server process started. These are errors that user may generate, such as out of disk space or duplicate key. You can prevent these assertions by fixing a problem with your application or deployment. Check the MongoDB log for more information.

serverStatus.asserts.rollovers

The rollovers counter displays the number of times that the rollover counters have rolled over since the last time the server process started. The counters will rollover to zero after 2³⁰ assertions. Use this value to provide context to the other values in the asserts data structure.

writeBacksQueued

For an example of the writeBacksQueued output, see the writeBacksQueued section of the Server Status Output page.

serverStatus.writeBacksQueued

The value of writeBacksQueued is true when there are operations from a mongos instance queued for retrying. Typically this option is false.

See also

writeBacks

Journaling (dur)

New in version 1.8.

For an example of the Journaling (dur) output, see the journaling section of the Server Status Output page.

serverStatus.dur

The dur (for “durability”) document contains data regarding the mongod‘s journaling-related operations and performance. mongod must be running with journaling for these data to appear in the output of “serverStatus”.

MongoDB reports the data in dur based on 3 second intervals of data, collected between 3 and 6 seconds in the past.

See also

Journaling Mechanics for more information about journaling operations.

serverStatus.dur.commits

The commits provides the number of transactions written to the journal during the last journal group commit interval.

serverStatus.dur.journaledMB

The journaledMB provides the amount of data in megabytes (MB) written to journal during the last journal group commit interval.

serverStatus.dur.writeToDataFilesMB

The writeToDataFilesMB provides the amount of data in megabytes (MB) written from journal to the data files during the last journal group commit interval.

serverStatus.dur.compression

New in version 2.0.

The compression represents the compression ratio of the data written to the journal:

( journaled_size_of_data / uncompressed_size_of_data )

serverStatus.dur.commitsInWriteLock

The commitsInWriteLock provides a count of the commits that occurred while a write lock was held. Commits in a write lock indicate a MongoDB node under a heavy write load and call for further diagnosis.

serverStatus.dur.earlyCommits

The earlyCommits value reflects the number of times MongoDB requested a commit before the scheduled journal group commit interval. Use this value to ensure that your journal group commit interval is not too long for your deployment.

serverStatus.dur.timeMS

The timeMS document provides information about the performance of the mongod instance during the various phases of journaling in the last journal group commit interval.

serverStatus.dur.timeMS.dt

The dt value provides, in milliseconds, the amount of time over which MongoDB collected the timeMS data. Use this field to provide context to the other timeMS field values.

serverStatus.dur.timeMS.prepLogBuffer

The prepLogBuffer value provides, in milliseconds, the amount of time spent preparing to write to the journal. Smaller values indicate better journal performance.

serverStatus.dur.timeMS.writeToJournal

The writeToJournal value provides, in milliseconds, the amount of time spent actually writing to the journal. File system speeds and device interfaces can affect performance.

serverStatus.dur.timeMS.writeToDataFiles

The writeToDataFiles value provides, in milliseconds, the amount of time spent writing to data files after journaling. File system speeds and device interfaces can affect performance.

serverStatus.dur.timeMS.remapPrivateView

The remapPrivateView value provides, in milliseconds, the amount of time spent remapping copy-on-write memory mapped views. Smaller values indicate better journal performance.

recordStats

For an example of the recordStats output, see the recordStats section of the Server Status Output page.

serverStatus.recordStats

The recordStats document provides fine grained reporting on page faults on a per database level.

MongoDB uses a read lock on each database to return recordStats. To minimize this overhead, you can disable this section, as in the following operation:

db.serverStatus( { recordStats: 0 } )

serverStatus.recordStats.accessesNotInMemory

accessesNotInMemory reflects the number of times mongod needed to access a memory page that was not resident in memory for all databases managed by this mongod instance.

serverStatus.recordStats.pageFaultExceptionsThrown

pageFaultExceptionsThrown reflects the number of page fault exceptions thrown by mongod when accessing data for all databases managed by this mongod instance.

serverStatus.recordStats.local.accessesNotInMemory

accessesNotInMemory reflects the number of times mongod needed to access a memory page that was not resident in memory for the local database.

serverStatus.recordStats.local.pageFaultExceptionsThrown

pageFaultExceptionsThrown reflects the number of page fault exceptions thrown by mongod when accessing data for the local database.

serverStatus.recordStats.admin.accessesNotInMemory

accessesNotInMemory reflects the number of times mongod needed to access a memory page that was not resident in memory for the admin database.

serverStatus.recordStats.admin.pageFaultExceptionsThrown

pageFaultExceptionsThrown reflects the number of page fault exceptions thrown by mongod when accessing data for the admin database.

serverStatus.recordStats.<database>.accessesNotInMemory

accessesNotInMemory reflects the number of times mongod needed to access a memory page that was not resident in memory for the <database> database.

serverStatus.recordStats.<database>.pageFaultExceptionsThrown

pageFaultExceptionsThrown reflects the number of page fault exceptions thrown by mongod when accessing data for the <database> database.

workingSet

New in version 2.4.

Note

The workingSet data is only included in the output of serverStatus if explicitly enabled. To return the workingSet, use one of the following commands:

db.serverStatus( { workingSet: 1 } )
db.runCommand( { serverStatus: 1, workingSet: 1 } )

For an example of the workingSet output, see the workingSet section of the Server Status Output page.

serverStatus.workingSet

workingSet is a document that contains values useful for estimating the size of the working set, which is the amount of data that MongoDB uses actively. workingSet uses an internal data structure that tracks pages accessed by mongod.

serverStatus.workingSet.note

note is a field that holds a string warning that the workingSet document is an estimate.

serverStatus.workingSet.pagesInMemory

pagesInMemory contains a count of the total number of pages accessed by mongod over the period displayed in overSeconds. The default page size is 4 kilobytes: to convert this value to the amount of data in memory multiply this value by 4 kilobytes.

If your total working set is less than the size of physical memory, over time the value of pagesInMemory will reflect your data size.

Use pagesInMemory in conjunction with overSeconds to help estimate the actual size of the working set.

serverStatus.workingSet.computationTimeMicros

computationTimeMicros reports the amount of time the mongod instance used to compute the other fields in the workingSet section.

Reporting on workingSet may impact the performance of other operations on the mongod instance because MongoDB must collect some data within the context of a lock. Ensure that automated monitoring tools consider this metric when determining the frequency of collection for workingSet.

serverStatus.workingSet.overSeconds

overSeconds returns the amount of time elapsed between the newest and oldest pages tracked in the pagesInMemory data point.

If overSeconds is decreasing, or if pagesInMemory equals physical RAM and overSeconds is very small, the working set may be much larger than physical RAM.

When overSeconds is large, MongoDB’s data set is equal to or smaller than physical RAM.

metrics

For an example of the metrics output, see the metrics section of the Server Status Output page.

New in version 2.4.

serverStatus.metrics

The metrics document holds a number of statistics that reflect the current use and state of a running mongod instance.

serverStatus.metrics.document

The document holds a document of that reflect document access and modification patterns and data use. Compare these values to the data in the opcounters document, which track total number of operations.

serverStatus.metrics.document.deleted

deleted reports the total number of documents deleted.

serverStatus.metrics.document.inserted

inserted reports the total number of documents inserted.

serverStatus.metrics.document.returned

returned reports the total number of documents returned by queries.

serverStatus.metrics.document.updated

updated reports the total number of documents updated.

serverStatus.metrics.getLastError

getLastError is a document that reports on getLastError use.

serverStatus.metrics.getLastError.wtime

wtime is an embedded document that reports getLastError operation counts with a w argument greater than 1.

serverStatus.metrics.getLastError.wtime.num

num reports the total number of getLastError operations with a specified write concern (i.e. w) that wait for one or more members of a replica set to acknowledge the write operation (i.e. a w value greater than 1.)

serverStatus.metrics.getLastError.wtime.totalMillis

totalMillis reports the total amount of time in milliseconds that the mongod has spent performing getLastError operations with write concern (i.e. w) that wait for one or more members of a replica set to acknowledge the write operation (i.e. a w value greater than 1.)

serverStatus.metrics.getLastError.wtimeouts

wtimeouts reports the number of times that write concern operations have timed out as a result of the wtimeout threshold to getLastError.

serverStatus.metrics.operation

operation is an embedded document that holds counters for several types of update and query operations that MongoDB handles using special operation types.

serverStatus.metrics.operation.fastmod

fastmod reports the number of update operations that neither cause documents to grow nor require updates to the index. For example, this counter would record an update operation that use the $inc operator to increment the value of a field that is not indexed.

serverStatus.metrics.operation.idhack

idhack reports the number of queries that contain the _id field. For these queries, MongoDB will use default index on the _id field and skip all query plan analysis.

serverStatus.metrics.operation.scanAndOrder

scanAndOrder reports the total number of queries that return sorted numbers that cannot perform the sort operation using an index.

serverStatus.metrics.queryExecutor

queryExecutor is a document that reports data from the query execution system.

serverStatus.metrics.queryExecutor.scanned

scanned reports the total number of index items scanned during queries and query-plan evaluation. This counter is the same as nscanned in the output of explain().

serverStatus.metrics.record

record is a document that reports data related to record allocation in the on-disk memory files.

serverStatus.metrics.record.moves

moves reports the total number of times documents move within the on-disk representation of the MongoDB data set. Documents move as a result of operations that increase the size of the document beyond their allocated record size.

serverStatus.metrics.repl

repl holds an embedded document that reports metrics related to the replication process. repl document appears on all mongod instances, even those that aren’t members of replica sets.

serverStatus.metrics.repl.apply

apply holds an embedded document that reports on the application of operations from the replication oplog.

serverStatus.metrics.repl.apply.batches

batches reports on the oplog application process on secondaries members of replica sets. See Multithreaded Replication for more information on the oplog application processes

serverStatus.metrics.repl.apply.batches.num

num reports the total number of batches applied across all databases.

serverStatus.metrics.repl.apply.batches.totalMillis

totalMillis reports the total amount of time the mongod has spent applying operations from the oplog.

serverStatus.metrics.repl.apply.ops

ops reports the total number of oplog operations applied.

serverStatus.metrics.repl.buffer

MongoDB buffers oplog operations from the replication sync source buffer before applying oplog entries in a batch. buffer provides a way to track the oplog buffer. See Multithreaded Replication for more information on the oplog application process.

serverStatus.metrics.repl.buffer.count

count reports the current number of operations in the oplog buffer.

serverStatus.metrics.repl.buffer.maxSizeBytes

maxSizeBytes reports the maximum size of the buffer. This value is a constant setting in the mongod, and is not configurable.

serverStatus.metrics.repl.buffer.sizeBytes

sizeBytes reports the current size of the contents of the oplog buffer.

serverStatus.metrics.repl.network

network reports network use by the replication process.

serverStatus.metrics.repl.network.bytes

bytes reports the total amount of data read from the replication sync source.

serverStatus.metrics.repl.network.getmores

getmores reports on the getmore operations, which are requests for additional results from the oplog cursor as part of the oplog replication process.

serverStatus.metrics.repl.network.getmores.num

num reports the total number of getmore operations, which are operations that request an additional set of operations from the replication sync source.

serverStatus.metrics.repl.network.getmores.totalMillis

totalMillis reports the total amount of time required to collect data from getmore operations.

Note

This number can be quite large, as MongoDB will wait for more data even if the getmore operation does not initial return data.

serverStatus.metrics.repl.network.ops

ops reports the total number of operations read from the replication source.

serverStatus.metrics.repl.network.readersCreated

readersCreated reports the total number of oplog query processes created. MongoDB will create a new oplog query any time an error occurs in the connection, including a timeout, or a network operation. Furthermore, readersCreated will increment every time MongoDB selects a new source fore replication.

serverStatus.metrics.repl.oplog

oplog is a document that reports on the size and use of the oplog by this mongod instance.

serverStatus.metrics.repl.oplog.insert

insert is a document that reports insert operations into the oplog.

serverStatus.metrics.repl.oplog.insert.num

num reports the total number of items inserted into the oplog.

serverStatus.metrics.repl.oplog.insert.totalMillis

totalMillis reports the total amount of time spent for the mongod to insert data into the oplog.

serverStatus.metrics.repl.oplog.insertBytes

insertBytes the total size of documents inserted into the oplog.

serverStatus.metrics.repl.preload

preload reports on the “pre-fetch” stage, where MongoDB loads documents and indexes into RAM to improve replication throughput.

See Multithreaded Replication for more information about the pre-fetch stage of the replication process.

serverStatus.metrics.repl.preload.docs

docs is an embedded document that reports on the documents loaded into memory during the pre-fetch stage.

serverStatus.metrics.repl.preload.docs.num

num reports the total number of documents loaded during the pre-fetch stage of replication.

serverStatus.metrics.repl.preload.docs.totalMillis

totalMillis reports the total amount of time spent loading documents as part of the pre-fetch stage of replication.

serverStatus.metrics.repl.preload.indexes

indexes is an embedded document that reports on the index items loaded into memory during the pre-fetch stage of replication.

See Multithreaded Replication for more information about the pre-fetch stage of replication.

serverStatus.metrics.repl.preload.indexes.num

num reports the total number of index entries loaded by members before updating documents as part of the pre-fetch stage of replication.

serverStatus.metrics.repl.preload.indexes.totalMillis

totalMillis reports the total amount of time spent loading index entries as part of the pre-fetch stage of replication.

serverStatus.storage.freelist.search.bucketExhausted

bucketExhausted reports the number of times that mongod has checked the free list without finding a suitably large record allocation.

serverStatus.storage.freelist.search.requests

requests reports the number of times mongod has searched for available record allocations.

serverStatus.storage.freelist.search.scanned

scanned reports the number of available record allocations mongod has searched.

serverStatus.metrics.ttl

ttl is an embedded document that reports on the operation of the resource use of the ttl index process.

serverStatus.metrics.ttl.deletedDocuments

deletedDocuments reports the total number of documents deleted from collections with a ttl index.

serverStatus.metrics.ttl.passes

passes reports the number of times the background process removes documents from collections with a ttl index.

serverStatus.metrics.cursor

New in version 2.6.

The cursor is a document that contains data regarding cursor state and use.

serverStatus.metrics.cursor.timedOut

New in version 2.6.

timedOut provides the total number of cursors that have timed out since the server process started. If this number is large or growing at a regular rate, this may indicate an application error.

serverStatus.metrics.cursor.open

New in version 2.6.

The open is an embedded document that contains data regarding open cursors.

serverStatus.metrics.cursor.open.noTimeout

New in version 2.6.

noTimeout provides the number of open cursors with the option DBQuery.Option.noTimeout set to prevent timeout after a period of inactivity.

serverStatus.metrics.cursor.open.pinned

New in version 2.6.

serverStatus.metrics.cursor.open.pinned provides the number of “pinned” open cursors.

serverStatus.metrics.cursor.open.total

New in version 2.6.

total provides the number of cursors that MongoDB is maintaining for clients. Because MongoDB exhausts unused cursors, typically this value small or zero. However, if there is a queue, stale tailable cursors, or a large number of operations this value may rise.

features

features

features is an internal command that returns the build-level feature settings.

isSelf

_isSelf

_isSelf is an internal command.

Internal Commands

Name | Description
handshake | Internal command.
_recvChunkAbort | Internal command that supports chunk migrations in sharded clusters. Do not call directly.
_recvChunkCommit | Internal command that supports chunk migrations in sharded clusters. Do not call directly.
_recvChunkStart | Internal command that facilitates chunk migrations in sharded clusters.. Do not call directly.
_recvChunkStatus | Internal command that returns data to support chunk migrations in sharded clusters. Do not call directly.
_replSetFresh | Internal command that supports replica set election operations.
mapreduce.shardedfinish | Internal command that supports map-reduce in sharded cluster environments.
_transferMods | Internal command that supports chunk migrations. Do not call directly.
replSetHeartbeat | Internal command that supports replica set operations.
replSetGetRBID | Internal command that supports replica set operations.
_migrateClone | Internal command that supports chunk migration. Do not call directly.
replSetElect | Internal command that supports replica set functionality.
writeBacksQueued | Internal command that supports chunk migrations in sharded clusters.
writebacklisten | Internal command that supports chunk migrations in sharded clusters.

handshake

recvChunkAbort

recvChunkCommit

recvChunkStart

recvChunkStatus

replSetFresh

mapreduce.shardedfinish

transferMods

replSetHeartbeat

replSetGetRBID

migrateClone

replSetElect

writeBacksQueued

writebacklisten

handshake

handshake

handshake is an internal command.

recvChunkAbort

_recvChunkAbort

_recvChunkAbort is an internal command. Do not call directly.

recvChunkCommit

_recvChunkCommit

_recvChunkCommit is an internal command. Do not call directly.

recvChunkStart

_recvChunkStart

_recvChunkStart is an internal command. Do not call directly.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed.

recvChunkStatus

_recvChunkStatus

_recvChunkStatus is an internal command. Do not call directly.

replSetFresh

replSetFresh

replSetFresh is an internal command that supports replica set functionality.

mapreduce.shardedfinish

mapreduce.shardedfinish

Provides internal functionality to support map-reduce in sharded environments.

See also

“mapReduce“

transferMods

_transferMods

_transferMods is an internal command. Do not call directly.

replSetHeartbeat

replSetHeartbeat

replSetHeartbeat is an internal command that supports replica set functionality.

replSetGetRBID

replSetGetRBID

replSetGetRBID is an internal command that supports replica set functionality.

migrateClone

_migrateClone

_migrateClone is an internal command. Do not call directly.

replSetElect

replSetElect

replSetElect is an internal command that support replica set functionality.

writeBacksQueued

writeBacksQueued

writeBacksQueued is an internal command that returns a document reporting there are operations in the write back queue for the given mongos and information about the queues.

writeBacksQueued.hasOpsQueued

Boolean.

hasOpsQueued is true if there are write Back operations queued.

writeBacksQueued.totalOpsQueued

Integer.

totalOpsQueued reflects the number of operations queued.

writeBacksQueued.queues

Document.

queues holds an embedded document where the fields are all write back queues. These field hold a document with two fields that reports on the state of the queue. The fields in these documents are:

writeBacksQueued.queues.n

n reflects the size, by number of items, in the queues.

writeBacksQueued.queues.minutesSinceLastCall

The number of minutes since the last time the mongos touched this queue.

The command document has the following prototype form:

{writeBacksQueued: 1}

To call writeBacksQueued from the mongo shell, use the following db.runCommand() form:

db.runCommand({writeBacksQueued: 1})

Consider the following example output:

{
  "hasOpsQueued" : true,
  "totalOpsQueued" : 7,
  "queues" : {
          "50b4f09f6671b11ff1944089" : { "n" : 0, "minutesSinceLastCall" : 1 },
          "50b4f09fc332bf1c5aeaaf59" : { "n" : 0, "minutesSinceLastCall" : 0 },
          "50b4f09f6671b1d51df98cb6" : { "n" : 0, "minutesSinceLastCall" : 0 },
          "50b4f0c67ccf1e5c6effb72e" : { "n" : 0, "minutesSinceLastCall" : 0 },
          "50b4faf12319f193cfdec0d1" : { "n" : 0, "minutesSinceLastCall" : 4 },
          "50b4f013d2c1f8d62453017e" : { "n" : 0, "minutesSinceLastCall" : 0 },
          "50b4f0f12319f193cfdec0d1" : { "n" : 0, "minutesSinceLastCall" : 1 }
  },
  "ok" : 1
}

writebacklisten

writebacklisten

writebacklisten is an internal command.

Testing Commands

Name | Description
testDistLockWithSkew | Internal command. Do not call this directly.
testDistLockWithSyncCluster | Internal command. Do not call this directly.
captrunc | Internal command. Truncates capped collections.
emptycapped | Internal command. Removes all documents from a capped collection.
godinsert | Internal command for testing.
_hashBSONElement | Internal command. Computes the MD5 hash of a BSON element.
_journalLatencyTest | Tests the time required to write and perform a file system sync for a file in the journal directory.
sleep | Internal command for testing. Forces MongoDB to block all operations.
replSetTest | Internal command for testing replica set functionality.
forceerror | Internal command for testing. Forces a user assertion exception.
skewClockCommand | Internal command. Do not call this command directly.
configureFailPoint | Internal command for testing. Configures failure points.

testDistLockWithSkew

testDistLockWithSyncCluster

captrunc

emptycapped

godinsert

_hashBSONElement

journalLatencyTest

sleep

replSetTest

forceerror

skewClockCommand

configureFailPoint

testDistLockWithSkew

_testDistLockWithSkew

_testDistLockWithSkew is an internal command. Do not call directly.

Note

_testDistLockWithSkew is an internal command that is not enabled by default. _testDistLockWithSkew must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. _testDistLockWithSkew cannot be enabled during run-time.

testDistLockWithSyncCluster

_testDistLockWithSyncCluster

_testDistLockWithSyncCluster is an internal command. Do not call directly.

Note

_testDistLockWithSyncCluster is an internal command that is not enabled by default. _testDistLockWithSyncCluster must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. _testDistLockWithSyncCluster cannot be enabled during run-time.

captrunc

Definition

captrunc

captrunc is a command that truncates capped collections for diagnostic and testing purposes and is not part of the stable client facing API. The command takes the following form:

{ captrunc: "<collection>", n: <integer>, inc: <true|false> }.

captrunc has the following fields:

Field | Description
captrunc | The name of the collection to truncate.
n | The number of documents to remove from the collection.
inc | Specifies whether to truncate the nth document.

field string captrunc:
| The name of the collection to truncate.
field integer n:
| The number of documents to remove from the collection.
field boolean inc:
| Specifies whether to truncate the nth document.

Note

captrunc is an internal command that is not enabled by default. captrunc must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. captrunc cannot be enabled during run-time.

Examples

The following command truncates 10 older documents from the collection records:

db.runCommand({captrunc: "records" , n: 10})

The following command truncates 100 documents and the 101st document:

db.runCommand({captrunc: "records", n: 100, inc: true})

emptycapped

emptycapped

The emptycapped command removes all documents from a capped collection. Use the following syntax:

{ emptycapped: "events" }

This command removes all records from the capped collection named events.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed.

Note

emptycapped is an internal command that is not enabled by default. emptycapped must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. emptycapped cannot be enabled during run-time.

godinsert

godinsert

godinsert is an internal command for testing purposes only.

Note

This command obtains a write lock on the affected database and will block other operations until it has completed.

Note

godinsert is an internal command that is not enabled by default. godinsert must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. godinsert cannot be enabled during run-time.

_hashBSONElement

Description

_hashBSONElement

New in version 2.4.

An internal command that computes the MD5 hash of a BSON element. The _hashBSONElement command returns 8 bytes from the 16 byte MD5 hash.

The _hashBSONElement command has the following form:

db.runCommand({ _hashBSONElement: <key> , seed: <seed> })

The _hashBSONElement command has the following fields:

Field | Description
key | The BSON element to hash.
seed | A seed used when computing the hash.

field BSONElement key:
| The BSON element to hash.
field integer seed:
| A seed used when computing the hash.

Note

_hashBSONElement is an internal command that is not enabled by default. _hashBSONElement must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. _hashBSONElement cannot be enabled during run-time.

Output

The _hashBSONElement command returns a document that holds the following fields:

_hashBSONElement.key

The original BSON element.

_hashBSONElement.seed

The seed used for the hash, defaults to 0.

_hashBSONElement.out

The decimal result of the hash.

_hashBSONElement.ok

Holds the 1 if the function returns successfully, and 0 if the operation encountered an error.

Example

Invoke a mongod instance with test commands enabled:

mongod --setParameter enableTestCommands=1

Run the following to compute the hash of an ISODate string:

db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z")})

The command returns the following document:

{
  "key" : ISODate("2013-02-12T22:12:57.211Z"),
  "seed" : 0,
  "out" : NumberLong("-4185544074338741873"),
  "ok" : 1
}

Run the following to hash the same ISODate string but this time to specify a seed value:

db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z"), seed:2013})

The command returns the following document:

{
  "key" : ISODate("2013-02-12T22:12:57.211Z"),
  "seed" : 2013,
  "out" : NumberLong("7845924651247493302"),
  "ok" : 1
}

journalLatencyTest

journalLatencyTest

journalLatencyTest is an administrative command that tests the length of time required to write and perform a file system sync (e.g. fsync) for a file in the journal directory. You must issue the journalLatencyTest command against the admin database in the form:

{ journalLatencyTest: 1 }

The value (i.e. 1 above), does not affect the operation of the command.

Note

journalLatencyTest is an internal command that is not enabled by default. journalLatencyTest must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. journalLatencyTest cannot be enabled during run-time.

sleep

Definition

sleep

Forces the database to block all operations. This is an internal command for testing purposes.

The sleep command takes the following prototype form:

{ sleep: 1, w: <true|false>, secs: <seconds> }

The sleep command has the following fields:

Field | Description
w | If true, obtains a global write lock. Otherwise obtains a read lock.
secs | The number of seconds to sleep.

field boolean w:
| If true, obtains a global write lock. Otherwise obtains a read lock.
field integer secs:
| The number of seconds to sleep.

Behavior

The command places the mongod instance in a write lock state for 100 seconds. Without arguments, sleep causes a “read lock” for 100 seconds.

Warning

sleep claims the lock specified in the w argument and blocks all operations on the mongod instance for the specified amount of time.

Note

sleep is an internal command that is not enabled by default. sleep must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. sleep cannot be enabled during run-time.

replSetTest

replSetTest

replSetTest is internal diagnostic command used for regression tests that supports replica set functionality.

Note

replSetTest is an internal command that is not enabled by default. replSetTest must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. replSetTest cannot be enabled during run-time.

forceerror

forceerror

The forceerror command is for testing purposes only. Use forceerror to force a user assertion exception. This command always returns an ok value of 0.

skewClockCommand

_skewClockCommand

_skewClockCommand is an internal command. Do not call directly.

Note

_skewClockCommand is an internal command that is not enabled by default. _skewClockCommand must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. _skewClockCommand cannot be enabled during run-time.

configureFailPoint

Definition

configureFailPoint

Configures a failure point that you can turn on and off while MongoDB runs. configureFailPoint is an internal command for testing purposes that takes the following form:

{configureFailPoint: "<failure_point>", mode: <behavior> }

You must issue configureFailPoint against the admin database. configureFailPoint has the following fields:

Field | Description
configureFailPoint | The name of the failure point.
mode | Controls the behavior of a failure point. The possible values are alwaysOn, off, or a document in the form of {times: n} that specifies the number of times the failure point remains on before it deactivates. The maximum value for the number is a 32-bit signed integer.
data | Optional. Passes in additional data for use in configuring the fail point. For example, to imitate a slow connection pass in a document that contains a delay time.

field string configureFailPoint:
| The name of the failure point.
field document, string mode:
| Controls the behavior of a failure point. The possible values are alwaysOn, off, or a document in the form of {times: n} that specifies the number of times the failure point remains on before it deactivates. The maximum value for the number is a 32-bit signed integer.
field document data:
| Optional. Passes in additional data for use in configuring the fail point. For example, to imitate a slow connection pass in a document that contains a delay time.

Note

configureFailPoint is an internal command that is not enabled by default. configureFailPoint must be enabled by using --setParameter enableTestCommands=1 on the mongod command line. configureFailPoint cannot be enabled during run-time.

Example

db.adminCommand( { configureFailPoint: "blocking_thread", mode: {times: 21} } )

System Events Auditing Commands

Name | Description
logApplicationMessage | Posts a custom message to the audit log.

logApplicationMessage

logApplicationMessage

logApplicationMessage

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

The logApplicationMessage command allows users to post a custom message to the audit log. If running with authorization, users must have clusterAdmin role, or roles that inherit from clusterAdmin, to run the command.

The logApplicationMessage has the following syntax:

{ logApplicationMessage: <string> }

MongoDB associates these custom messages with the audit operation applicationMessage, and the messages are subject to any filtering.

mongo Shell Methods

JavaScript in MongoDB

Although these methods use JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

Collection

Collection Methods

db.collection.aggregate()

db.collection.count()

db.collection.copyTo()

db.collection.createIndex()

db.collection.getIndexStats()

db.collection.indexStats()

db.collection.dataSize()

db.collection.distinct()

db.collection.drop()

db.collection.dropIndex()

db.collection.dropIndexes()

db.collection.ensureIndex()

db.collection.find()

db.collection.findAndModify()

db.collection.findOne()

db.collection.getIndexes()

db.collection.getShardDistribution()

db.collection.getShardVersion()

db.collection.group()

db.collection.insert()

db.collection.isCapped()

db.collection.mapReduce()

db.collection.reIndex()

db.collection.remove()

db.collection.renameCollection()

db.collection.save()

db.collection.stats()

db.collection.storageSize()

db.collection.totalSize()

db.collection.totalIndexSize()

db.collection.update()

db.collection.validate()

Cursor

Cursor Methods

cursor.addOption()

cursor.batchSize()

cursor.count()

cursor.explain()

cursor.forEach()

cursor.hasNext()

cursor.hint()

cursor.limit()

cursor.map()

cursor.maxTimeMS()

cursor.max()

cursor.min()

cursor.next()

cursor.objsLeftInBatch()

cursor.readPref()

cursor.showDiskLoc()

cursor.size()

cursor.skip()

cursor.snapshot()

cursor.sort()

cursor.toArray()

Database

Database Methods

db.addUser()

db.auth()

db.changeUserPassword()

db.cloneCollection()

db.cloneDatabase()

db.commandHelp()

db.copyDatabase()

db.createCollection()

db.currentOp()

db.dropDatabase()

db.eval()

db.fsyncLock()

db.fsyncUnlock()

db.getCollection()

db.getCollectionNames()

db.getLastError()

db.getLastErrorObj()

db.getMongo()

db.getName()

db.getPrevError()

db.getProfilingLevel()

db.getProfilingStatus()

db.getReplicationInfo()

db.getSiblingDB()

db.help()

db.hostInfo()

db.isMaster()

db.killOp()

db.listCommands()

db.loadServerScripts()

db.logout()

db.printCollectionStats()

db.printReplicationInfo()

db.printShardingStatus()

db.printSlaveReplicationInfo()

db.removeUser()

db.repairDatabase()

db.resetError()

db.runCommand()

db.serverBuildInfo()

db.serverCmdLineOpts()

db.serverStatus()

db.setProfilingLevel()

db.shutdownServer()

db.stats()

db.version()

db.upgradeCheck()

db.upgradeCheckAllDBs()

Query Plan Cache

Query Plan Cache Methods

db.collection.getPlanCache()

PlanCache.help()

PlanCache.listQueryShapes()

PlanCache.getPlansByQuery()

PlanCache.clearPlansByQuery()

PlanCache.clear()

Bulk Write Operation

Bulk Operation Methods

Bulk()

db.collection.initializeOrderedBulkOp()

db.collection.initializeUnorderedBulkOp()

Bulk.insert()

Bulk.find()

Bulk.find.removeOne()

Bulk.find.remove()

Bulk.find.replaceOne()

Bulk.find.updateOne()

Bulk.find.update()

Bulk.find.upsert()

Bulk.execute()

Bulk.getOperations()

Bulk.tojson()

Bulk.toString()

User Management

User Management Methods

db.createUser()

db.addUser()

db.updateUser()

db.changeUserPassword()

db.removeUser()

db.dropAllUsers()

db.dropUser()

db.grantRolesToUser()

db.revokeRolesFromUser()

db.getUser()

db.getUsers()

Role Management

Role Management Methods

db.createRole()

db.updateRole()

db.dropRole()

db.dropAllRoles()

db.grantPrivilegesToRole()

db.revokePrivilegesFromRole()

db.grantRolesToRole()

db.revokeRolesFromRole()

db.getRole()

db.getRoles()

Replication

Replication Methods

rs.add()

rs.addArb()

rs.conf()

rs.freeze()

rs.help()

rs.initiate()

rs.printReplicationInfo()

rs.printSlaveReplicationInfo()

rs.reconfig()

rs.remove()

rs.slaveOk()

rs.status()

rs.stepDown()

rs.syncFrom()

Sharding

Sharding Methods

sh._adminCommand()

sh._checkFullName()

sh._checkMongos()

sh._lastMigration()

sh.addShard()

sh.addShardTag()

sh.addTagRange()

sh.disableBalancing()

sh.enableBalancing()

sh.enableSharding()

sh.getBalancerHost()

sh.getBalancerState()

sh.help()

sh.isBalancerRunning()

sh.moveChunk()

sh.removeShardTag()

sh.setBalancerState()

sh.shardCollection()

sh.splitAt()

sh.splitFind()

sh.startBalancer()

sh.status()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.waitForDLock()

sh.waitForPingChange()

Subprocess

Subprocess Methods

clearRawMongoProgramOutput()

rawMongoProgramOutput()

run()

runMongoProgram()

runProgram()

startMongoProgram()

stopMongoProgram()

stopMongoProgramByPid()

stopMongod()

waitMongoProgramOnPort()

waitProgram()

Constructors

Object Constructors and Methods

Date()

UUID()

ObjectId.getTimestamp()

ObjectId.toString()

ObjectId.valueOf()

WriteResult()

WriteResult.hasWriteError()

WriteResult.hasWriteConcernError()

BulkWriteResult()

Connection

Connection Methods

Mongo.getDB()

Mongo.getReadPrefMode()

Mongo.getReadPrefTagSet()

Mongo.setReadPref()

mongo.setSlaveOk()

Mongo()

connect()

Native

Native Methods

cat()

version()

cd()

copyDbpath()

resetDbpath()

fuzzFile()

getHostName()

getMemInfo()

hostname()

_isWindows()

listFiles()

load()

ls()

md5sumFile()

mkdir()

pwd()

quit()

rand()

removeFile()

_srand()

Collection Methods

Name | Description
db.collection.aggregate() | Provides access to the aggregation pipeline.
db.collection.count() | Wraps count to return a count of the number of documents in a collection or matching a query.
db.collection.copyTo() | Wraps eval to copy data between collections in a single MongoDB instance.
db.collection.createIndex() | Builds an index on a collection. Use db.collection.ensureIndex().
db.collection.getIndexStats() | Renders a human-readable view of the data collected by indexStats which reflects B-tree utilization.
db.collection.indexStats() | Renders a human-readable view of the data collected by indexStats which reflects B-tree utilization.
db.collection.dataSize() | Returns the size of the collection. Wraps the size field in the output of the collStats.
db.collection.distinct() | Returns an array of documents that have distinct values for the specified field.
db.collection.drop() | Removes the specified collection from the database.
db.collection.dropIndex() | Removes a specified index on a collection.
db.collection.dropIndexes() | Removes all indexes on a collection.
db.collection.ensureIndex() | Creates an index if it does not currently exist. If the index exists ensureIndex() does nothing.
db.collection.find() | Performs a query on a collection and returns a cursor object.
db.collection.findAndModify() | Atomically modifies and returns a single document.
db.collection.findOne() | Performs a query and returns a single document.
db.collection.getIndexes() | Returns an array of documents that describe the existing indexes on a collection.
db.collection.getShardDistribution() | For collections in sharded clusters, db.collection.getShardDistribution() reports data of chunk distribution.
db.collection.getShardVersion() | Internal diagnostic method for shard cluster.
db.collection.group() | Provides simple data aggregation function. Groups documents in a collection by a key, and processes the results. Use aggregate() for more complex data aggregation.
db.collection.insert() | Creates a new document in a collection.
db.collection.isCapped() | Reports if a collection is a capped collection.
db.collection.mapReduce() | Performs map-reduce style data aggregation.
db.collection.reIndex() | Rebuilds all existing indexes on a collection.
db.collection.remove() | Deletes documents from a collection.
db.collection.renameCollection() | Changes the name of a collection.
db.collection.save() | Provides a wrapper around an insert() and update() to insert new documents.
db.collection.stats() | Reports on the state of a collection. Provides a wrapper around the collStats.
db.collection.storageSize() | Reports the total size used by the collection in bytes. Provides a wrapper around the storageSize field of the collStats output.
db.collection.totalSize() | Reports the total size of a collection, including the size of all documents and all indexes on a collection.
db.collection.totalIndexSize() | Reports the total size used by the indexes on a collection. Provides a wrapper around the totalIndexSize field of the collStats output.
db.collection.update() | Modifies a document in a collection.
db.collection.validate() | Performs diagnostic operations on a collection.

db.collection.aggregate()

db.collection.count()

db.collection.copyTo()

db.collection.createIndex()

db.collection.getIndexStats()

db.collection.indexStats()

db.collection.dataSize()

db.collection.distinct()

db.collection.drop()

db.collection.dropIndex()

db.collection.dropIndexes()

db.collection.ensureIndex()

db.collection.find()

db.collection.findAndModify()

db.collection.findOne()

db.collection.getIndexes()

db.collection.getShardDistribution()

db.collection.getShardVersion()

db.collection.group()

db.collection.insert()

db.collection.isCapped()

db.collection.mapReduce()

db.collection.reIndex()

db.collection.remove()

db.collection.renameCollection()

db.collection.save()

db.collection.stats()

db.collection.storageSize()

db.collection.totalSize()

db.collection.totalIndexSize()

db.collection.update()

db.collection.validate()

db.collection.aggregate()

New in version 2.2.

Definition

db.collection.aggregate(pipeline, options)

Calculates aggregate values for the data in a collection.

Parameter
Description

pipeline

A sequence of data aggregation operations or stages. See the aggregation pipeline operators for details.

Changed in version 2.6: The method can still accept the pipeline stages as separate arguments instead of as elements in an array; however, if you do not specify the pipeline as an array, you cannot specify the options parameter.

options

Optional. Additional options that aggregate() passes to the aggregate command.

New in version 2.6: Available only if you specify the pipeline as an array.

param array pipeline:

A sequence of data aggregation operations or stages. See the aggregation pipeline operators for details.

Changed in version 2.6: The method can still accept the pipeline stages as separate arguments instead of as elements in an array; however, if you do not specify the pipeline as an array, you cannot specify the options parameter.

param document options:

Optional. Additional options that aggregate() passes to the aggregate command.

New in version 2.6: Available only if you specify the pipeline as an array.

The options document can contain the following fields and values:

Field
Description

explain

Optional. Specifies to return the information on the processing of the pipeline. See Return Information on Aggregation Pipeline Operation for an example.

New in version 2.6.

allowDiskUse

Optional. Enables writing to temporary files. When set to true, aggregation operations can write data to the _tmp subdirectory in the dbPath directory. See Perform Large Sort Operation with External Sort for an example.

New in version 2.6.

cursor

Optional. Specifies the initial batch size for the cursor. The value of the cursor field is a document with the field batchSize. See Specify an Initial Batch Size for syntax and example.

New in version 2.6.

field boolean explain:

Optional. Specifies to return the information on the processing of the pipeline. See Return Information on Aggregation Pipeline Operation for an example.

New in version 2.6.

field boolean allowDiskUse:

Optional. Enables writing to temporary files. When set to true, aggregation operations can write data to the _tmp subdirectory in the dbPath directory. See Perform Large Sort Operation with External Sort for an example.

New in version 2.6.

field document cursor:

Optional. Specifies the initial batch size for the cursor. The value of the cursor field is a document with the field batchSize. See Specify an Initial Batch Size for syntax and example.

New in version 2.6.

Returns:
A cursor to the documents produced by the final stage of the aggregation pipeline operation, or if you include the explain option, the document that provides details on the processing of the aggregation operation.

If the pipeline includes the $out operator, aggregate() returns an empty cursor. See $out for more information.

Changed in version 2.6: The db.collection.aggregate() method returns a cursor and can return result sets of any size. Previous versions returned all results in a single document, and the result set was subject to a size limit of 16 megabytes.

Changed in version 2.4: If an error occurs, the aggregate() helper throws an exception. In previous versions, the helper returned a document with the error message and code, and ok status field not equal to 1, same as the aggregate command.

See also

For more information, see Aggregation Pipeline, Aggregation Reference, Aggregation Pipeline Limits, and aggregate.

Cursor Behavior

In the mongo shell, if the cursor returned from the db.collection.aggregate() is not assigned to a variable using the var keyword, then the mongo shell automatically iterates the cursor up to 20 times. See Cursors for cursor behavior in the mongo shell and Iterate a Cursor in the mongo Shell for handling cursors in the mongo shell.

Cursors returned from aggregation only supports cursor methods that operate on evaluated cursors (i.e. cursors whose first batch has been retrieved), such as the following methods:

cursor.hasNext()

cursor.next()

cursor.toArray()

cursor.forEach()

cursor.map()

cursor.objsLeftInBatch()

cursor.itcount()

cursor.pretty()

Examples

The examples in this section use the db.collection.aggregate() helper provided in the 2.6 version of the mongo shell.

The following examples use the collection orders that contains the following documents:

{ _id: 1, cust_id: "abc1", ord_date: ISODate("2012-11-02T17:04:11.102Z"), status: "A", amount: 50 }
{ _id: 2, cust_id: "xyz1", ord_date: ISODate("2013-10-01T17:04:11.102Z"), status: "A", amount: 100 }
{ _id: 3, cust_id: "xyz1", ord_date: ISODate("2013-10-12T17:04:11.102Z"), status: "D", amount: 25 }
{ _id: 4, cust_id: "xyz1", ord_date: ISODate("2013-10-11T17:04:11.102Z"), status: "D", amount: 125 }
{ _id: 5, cust_id: "abc1", ord_date: ISODate("2013-11-12T17:04:11.102Z"), status: "A", amount: 25 }

Group by and Calculate a Sum

The following aggregation operation selects documents with status equal to "A", groups the matching documents by the cust_id field and calculates the total for each cust_id field from the sum of the amount field, and sorts the results by the total field in descending order:

db.orders.aggregate([
                     { $match: { status: "A" } },
                     { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                     { $sort: { total: -1 } }
                   ])

The operation returns a cursor with the following documents:

{ "_id" : "xyz1", "total" : 100 }
{ "_id" : "abc1", "total" : 75 }

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

Return Information on Aggregation Pipeline Operation

The following aggregation operation sets the option explain to true to return information about the aggregation operation.

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } }
                     ],
                     {
                       explain: true
                     }
                   )

The operation returns a cursor with the document that contains detailed information regarding the processing of the aggregation pipeline. For example, the document may show, among other details, which index, if any, the operation used. [1] If the orders collection is a sharded collection, the document would also show the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards.

Note

The intended readers of the explain output document are humans, and not machines, and the output format is subject to change between releases.

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

Perform Large Sort Operation with External Sort

Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set allowDiskUse option to true to enable writing data to temporary files, as in the following example:

var results = db.stocks.aggregate(
                                   [
                                     { $project : { cusip: 1, date: 1, price: 1, _id: 0 } },
                                     { $sort : { cusip : 1, date: 1 } }
                                   ],
                                   {
                                     allowDiskUse: true
                                   }
                                 )

Specify an Initial Batch Size

To specify an initial batch size for the cursor, use the following syntax for the cursor option:

cursor: { batchSize: <int> }

For example, the following aggregation operation specifies the initial batch size of 0 for the cursor:

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } },
                       { $limit: 2 }
                     ],
                     {
                       cursor: { batchSize: 0 }
                     }
                   )

A batchSize of 0 means an empty first batch and is useful for quickly returning a cursor or failure message without doing significant server-side work. Specify subsequent batch sizes to OP_GET_MORE [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/#wire-op-get-more] operations as with other MongoDB cursors.

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

[1]
Index Filters can affect the choice of index used. See Index Filters for details.

db.collection.count()

Definition

db.collection.count(<query>)

Returns the count of documents that would match a find() query. The db.collection.count() method does not perform the find() operation but instead counts and returns the number of results that match a query.

The db.collection.count() method has the following parameter:

Parameter | Description
query | The query selection criteria.

param document query:

The query selection criteria.

The db.collection.count() method is equivalent to the db.collection.find(<query>).count() construct.

See also

cursor.count()

Behavior

Sharded Clusters

On a sharded cluster, db.collection.count() can result in an inaccurate count if orphaned documents exist or if a chunk migration is in progress.

To avoid these situations, on a sharded cluster, use the $group stage of the db.collection.aggregate() method to $sum the documents. For example, the following operation counts the documents in a collection:

db.collection.aggregate(
   [
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

To get a count of documents that match a query condition, include the $match stage as well:

db.collection.aggregate(
   [
      { $match: <query condition> },
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

See Perform a Count for an example.

Index Use

Consider a collection with the following index:

{ a: 1, b: 1 }

When performing a count, MongoDB can return the count using only the index if:

the query can use an index,

the query only contains conditions on the keys of the index, and

the query predicates access a single contiguous range of index keys.

For example, the following operations can return the count using only the index:

db.collection.find( { a: 5, b: 5 } ).count()
db.collection.find( { a: { $gt: 5 } } ).count()
db.collection.find( { a: 5, b: { $gt: 10 } } ).count()

If, however, the query can use an index but the query predicates do not access a single contiguous range of index keys or the query also contains conditions on fields outside the index, then in addition to using the index, MongoDB must also read the documents to return the count.

db.collection.find( { a: 5, b: { $in: [ 1, 2, 3 ] } } ).count()
db.collection.find( { a: { $gt: 5 }, b: 5 } ).count()
db.collection.find( { a: 5, b: 5, c: 5 } ).count()

In such cases, during the initial read of the documents, MongoDB pages the documents into memory such that subsequent calls of the same count operation will have better performance.

Examples

Count all Documents in a Collection

To count the number of all documents in the orders collection, use the following operation:

db.orders.count()

This operation is equivalent to the following:

db.orders.find().count()

Count all Documents that Match a Query

Count the number of the documents in the orders collection with the field ord_dt greater than new Date('01/01/2012'):

db.orders.count( { ord_dt: { $gt: new Date('01/01/2012') } } )

The query is equivalent to the following:

db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).count()

db.collection.copyTo()

Definition

db.collection.copyTo(newCollection)

Copies all documents from collection into newCollection using server-side JavaScript. If newCollection does not exist, MongoDB creates it.

If authorization is enabled, you must have access to all actions on all resources in order to run db.collection.copyTo(). Providing such access is not recommended, but if your organization requires a user to run db.collection.copyTo(), create a role that grants anyAction on anyResource. Do not assign this role to any other user.

Parameter | Description
newCollection | The name of the collection to write data to.

param string newCollection:

The name of the collection to write data to.

Warning

When using db.collection.copyTo() check field types to ensure that the operation does not remove type information from documents during the translation from BSON to JSON.

The db.collection.copyTo() method uses the eval command internally. As a result, the db.collection.copyTo() operation takes a global lock that blocks all other read and write operations until the db.collection.copyTo() completes.

copyTo() returns the number of documents copied. If the copy fails, it throws an exception.

Behavior

Because copyTo() uses eval internally, the copy operations will block all other operations on the mongod instance.

Example

The following operation copies all documents from the source collection into the target collection.

db.source.copyTo(target)

db.collection.createIndex()

Definition

db.collection.createIndex(keys, options)

Creates indexes on collections.

Parameter | Description
keys | For each field to index, a key-value pair with the field and the index order: 1 for ascending or -1 for descending.
options | Optional. One or more key-value pairs that specify index options. For a list of options, see db.collection.ensureIndex().

param document keys:
| For each field to index, a key-value pair with the field and the index order: 1 for ascending or -1 for descending.
param document options:
| Optional. One or more key-value pairs that specify index options. For a list of options, see db.collection.ensureIndex().

See also

Indexes, db.collection.createIndex(), db.collection.dropIndex(), db.collection.dropIndexes(), db.collection.getIndexes(), db.collection.reIndex(), and db.collection.totalIndexSize()

db.collection.getIndexStats()

Definition

db.collection.getIndexStats(index)

Displays a human-readable summary of aggregated statistics about an index’s B-tree data structure. The information summarizes the output returned by the indexStats command and indexStats() method. The getIndexStats() method displays the information on the screen and does not return an object.

The getIndexStats() method has the following form:

db.<collection>.getIndexStats( { index : "<index name>" } )

Parameter | Description
index | The index name.

param document index:

The index name.

The getIndexStats() method is available only when connected to a mongod instance that uses the --enableExperimentalIndexStatsCmd option.

To view index names for a collection, use the getIndexes() method.

Warning

Do not use getIndexStats() or indexStats with production deployments.

Example

The following command returns information for an index named type_1_traits_1:

db.animals.getIndexStats({index:"type_1_traits_1"})

The command returns the following summary. For more information on the B-tree statistics, see indexStats.

-- index "undefined" --
  version 1 | key pattern {  "type" : 1,  "traits" : 1 } | storage namespace "test.animals.$type_1_traits_1"
  2 deep, bucket body is 8154 bytes

  bucket count       45513   on average 99.401 % (±0.463 %) full     49.581 % (±4.135 %) bson keys, 49.820 % (±4.275 %) key nodes

  -- depth 0 --
    bucket count     1       on average 71.511 % (±0.000 %) full     36.191 % (±0.000 %) bson keys, 35.320 % (±0.000 %) key nodes

  -- depth 1 --
    bucket count     180     on average 98.954 % (±5.874 %) full     49.732 % (±5.072 %) bson keys, 49.221 % (±5.161 %) key nodes

  -- depth 2 --
    bucket count     45332   on average 99.403 % (±0.245 %) full     49.580 % (±4.130 %) bson keys, 49.823 % (±4.270 %) key nodes

db.collection.indexStats()

Definition

db.collection.indexStats(index)

Aggregates statistics for the B-tree data structure that stores data for a MongoDB index. The indexStats() method is a thin wrapper around the indexStats command. The indexStats() method is available only on mongod instances running with the --enableExperimentalIndexStatsCmd option.

Important

The indexStats() method is not intended for production deployments.

The indexStats() method has the following form:

db.<collection>.indexStats( { index: "<index name>" } )

The indexStats() method has the following parameter:

Parameter | Description
index | The index name.

param document index:

The index name.

The method takes a read lock and pages into memory all the extents, or B-tree buckets, encountered. The method might be slow for large indexes if the underlying extents are not already in physical memory. Do not run indexStats() on a replica set primary. When run on a secondary, the command causes the secondary to fall behind on replication.

The method aggregates statistics for the entire B-tree and for each individual level of the B-tree. For a description of the command’s output, see indexStats.

For more information about running indexStats(), see https://github.com/10gen-labs/storage-viz#readme.

db.collection.dataSize()

db.collection.dataSize()

Returns:
The size of the collection. This method provides a wrapper around the size output of the collStats (i.e. db.collection.stats()) command.

db.collection.distinct()

Definition

db.collection.distinct(field, query)

Finds the distinct values for a specified field across a single collection and returns the results in an array.

Parameter | Description
field | The field for which to return distinct values.
query | A query that specifies the documents from which to retrieve the distinct values.

param string field:
| The field for which to return distinct values.
param document query:
| A query that specifies the documents from which to retrieve the distinct values.

The db.collection.distinct() method provides a wrapper around the distinct command. Results must not be larger than the maximum BSON size.

Behavior

Array Fields

If the value of the specified field is an array, db.collection.distinct() considers each element of the array as a separate value.

For instance, if a field has as its value [ 1, [1], 1 ], then db.collection.distinct() considers 1, [1], and 1 as separate values.

For an example, see Return Distinct Values for an Array Field.

Index Use

When possible, db.collection.distinct() operations can use indexes.

Indexes can also cover db.collection.distinct() operations. See Covering a Query for more information on queries covered by indexes.

Examples

The examples use the inventory collection that contains the following documents:

{ "_id": 1, "dept": "A", "item": { "sku": "111", "color": "red" }, "sizes": [ "S", "M" ] }
{ "_id": 2, "dept": "A", "item": { "sku": "111", "color": "blue" }, "sizes": [ "M", "L" ] }
{ "_id": 3, "dept": "B", "item": { "sku": "222", "color": "blue" }, "sizes": "S" }
{ "_id": 4, "dept": "A", "item": { "sku": "333", "color": "black" }, "sizes": [ "S" ] }

Return Distinct Values for a Field

The following example returns the distinct values for the field dept from all documents in the inventory collection:

db.inventory.distinct( "dept" )

The method returns the following array of distinct dept values:

[ "A", "B" ]

Return Distinct Values for an Embedded Field

The following example returns the distinct values for the field sku, embedded in the item field, from all documents in the inventory collection:

db.inventory.distinct( "item.sku" )

The method returns the following array of distinct sku values:

[ "111", "222", "333" ]

See also

Dot Notation for information on accessing fields within embedded documents

Return Distinct Values for an Array Field

The following example returns the distinct values for the field sizes from all documents in the inventory collection:

db.inventory.distinct( "sizes" )

The method returns the following array of distinct sizes values:

[ "M", "S", "L" ]

For information on distinct() and array fields, see the Behavior section.

Specify Query with distinct

The following example returns the distinct values for the field sku, embedded in the item field, from the documents whose dept is equal to "A":

db.inventory.distinct( "item.sku", { dept: "A" } )

The method returns the following array of distinct sku values:

[ "111", "333" ]

db.collection.drop()

Definition

db.collection.drop()

Removes a collection from the database. The method also removes any indexes associated with the dropped collection. The method provides a wrapper around the drop command.

db.collection.drop() has the form:

db.collection.drop()

db.collection.drop() takes no arguments and will produce an error if called with any arguments.

Returns:

true when successfully drops a collection.

false when collection to drop does not exist.

Behavior

This method obtains a write lock on the affected database and will block other operations until it has completed.

Example

The following operation drops the students collection in the current database.

db.students.drop()

db.collection.dropIndex()

Definition

db.collection.dropIndex(index)

Drops or removes the specified index from a collection. The db.collection.dropIndex() method provides a wrapper around the dropIndexes command.

Note

You cannot drop the default index on the _id field.

The db.collection.dropIndex() method takes the following parameter:

Parameter
Description

index

Specifies the index to drop. You can specify the index either by the index name or by the index specification document. [1]

To drop a text index, specify the index name.

param string, document index:

Specifies the index to drop. You can specify the index either by the index name or by the index specification document. [1]

To drop a text index, specify the index name.

To get the index name or the index specification document for the db.collection.dropIndex() method, use the db.collection.getIndexes() method.

Example

Consider a pets collection. Calling the getIndexes() method on the pets collection returns the following indexes:

[
   {  "v" : 1,
      "key" : { "_id" : 1 },
      "ns" : "test.pets",
      "name" : "_id_"
   },
   {
      "v" : 1,
      "key" : { "cat" : -1 },
      "ns" : "test.pets",
      "name" : "catIdx"
   },
   {
      "v" : 1,
      "key" : { "cat" : 1, "dog" : -1 },
      "ns" : "test.pets",
      "name" : "cat_1_dog_-1"
   }
]

The single field index on the field cat has the user-specified name of catIdx [2] and the index specification document of { "cat" : -1 }.

To drop the index catIdx, you can use either the index name:

db.pets.dropIndex( "catIdx" )

Or you can use the index specification document { "cat" : -1 }:

db.pets.dropIndex( { "cat" : -1 } )

[1]
(1, 2) When using a mongo shell version earlier than 2.2.2, if you specified a name during the index creation, you must use the name to drop the index.

[2]
During index creation, if the user does not specify an index name, the system generates the name by concatenating the index key field and value with an underscore, e.g. cat_1.

db.collection.dropIndexes()

db.collection.dropIndexes()

Drops all indexes other than the required index on the _id field. Only call dropIndexes() as a method on a collection object.

db.collection.ensureIndex()

Definition

db.collection.ensureIndex(keys, options)

Creates an index on the specified field if the index does not already exist.

The ensureIndex() method has the following fields:

Parameter
Description

keys

A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.

MongoDB supports several different index types including text, geospatial, and hashed indexes. See Index Type Documentation for more information.

options
Optional. A document that contains a set of options that controls the creation of the index. See Options for details.

param document keys:

A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.

MongoDB supports several different index types including text, geospatial, and hashed indexes. See Index Type Documentation for more information.

param document options:

Optional. A document that contains a set of options that controls the creation of the index. See Options for details.

Options

The options document contains a set of options that controls the creation of the index. Different index types can have additional options specific for that type.

Options for All Index Types

The following options are available for all index types unless otherwise specified:

Parameter
Description

background
Optional. Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

unique

Optional. Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true to create a unique index. The default value is false.

The option is unavailable for hashed indexes.

name

Optional. The name of the index. If unspecified, MongoDB generates an index name by concatenating the names of the indexed fields and the sort order.

Whether user specified or MongoDB generated, index names including their full namespace (i.e. database.collection) cannot be longer than the Index Name Limit.

dropDups

Optional. Creates a unique index on a field that may have duplicates. MongoDB indexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true to create unique index. The default value is false.

The option is unavailable for hashed indexes.

Deprecated since version 2.6.

Warning

dropDups will delete data from your collection when building the index.

sparse

Optional. If true, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is false. See Sparse Indexes for more information.

Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document.

2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes.

expireAfterSeconds
Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.

v
Optional. The index version number. The default index version depends on the version of mongod running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations.

param Boolean background:

Optional. Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

param Boolean unique:

Optional. Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true to create a unique index. The default value is false.

The option is unavailable for hashed indexes.

param string name:

Optional. The name of the index. If unspecified, MongoDB generates an index name by concatenating the names of the indexed fields and the sort order.

Whether user specified or MongoDB generated, index names including their full namespace (i.e. database.collection) cannot be longer than the Index Name Limit.

param Boolean dropDups:

Optional. Creates a unique index on a field that may have duplicates. MongoDB indexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true to create unique index. The default value is false.

The option is unavailable for hashed indexes.

Deprecated since version 2.6.

Warning

dropDups will delete data from your collection when building the index.

param Boolean sparse:

Optional. If true, the index only references documents with the specified field. These indexes use less space but behave differently in some situations (particularly sorts). The default value is false. See Sparse Indexes for more information.

Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document.

2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes.

param integer expireAfterSeconds:

Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.

param index version v:

Optional. The index version number. The default index version depends on the version of mongod running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations.

Options for text Indexes

The following options are available for text indexes only:

Parameter
Description

weights
Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See Control Search Results with Weights to adjust the scores. The default value is 1.

default_language
Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and Specify a Language for Text Index for more information and examples. The default value is english.

language_override
Optional. For text indexes, the name of the field, in the collection’s documents, that contains the override language for the document. The default value is language. See Use any Field to Specify the Language for a Document for an example.

textIndexVersion

Optional. For text indexes, the text index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

param document weights:

Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See Control Search Results with Weights to adjust the scores. The default value is 1.

param string default_language:

Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and Specify a Language for Text Index for more information and examples. The default value is english.

param string language_override:

Optional. For text indexes, the name of the field, in the collection’s documents, that contains the override language for the document. The default value is language. See Use any Field to Specify the Language for a Document for an example.

param integer textIndexVersion:

Optional. For text indexes, the text index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

Options for 2dsphere Indexes

The following option is available for 2dsphere indexes only:

Parameter
Description

2dsphereIndexVersion

Optional. For 2dsphere indexes, the 2dsphere index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

param integer 2dsphereIndexVersion:

Optional. For 2dsphere indexes, the 2dsphere index version number. Version can be either 1 or 2.

In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1.

New in version 2.6.

Options for 2d Indexes

The following options are available for 2d indexes only:

Parameter
Description

bits

Optional. For 2d indexes, the number of precision of the stored geohash value of the location data.

The bits value ranges from 1 to 32 inclusive. The default value is 26.

min
Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0.

max
Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0.

param integer bits:

Optional. For 2d indexes, the number of precision of the stored geohash value of the location data.

The bits value ranges from 1 to 32 inclusive. The default value is 26.

param number min:

Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0.

param number max:

Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0.

Options for geoHaystack Indexes

The following option is available for geoHaystack indexes only:

Parameter
Description

bucketSize

For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other.

The value must be greater than 0.

param number bucketSize:

For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other.

The value must be greater than 0.

Behaviors

The ensureIndex() method has the behaviors described here.

To add or change index options you must drop the index using the dropIndex() method and issue another ensureIndex() operation with the new options.

If you create an index with one set of options, and then issue the ensureIndex() method with the same index fields and different options without first dropping the index, ensureIndex() will not rebuild the existing index with the new options.

If you call multiple ensureIndex() methods with the same index specification at the same time, only the first operation will succeed, all other operations will have no effect.

Non-background indexing operations will block all other operations on a database.

MongoDB will not create an index on a collection if the index entry for an existing document exceeds the Maximum Index Key Length. Previous versions of MongoDB would create the index but not index such documents.

Changed in version 2.6.

Examples

Create an Ascending Index on a Single Field

The following example creates an ascending index on the field orderDate.

db.collection.ensureIndex( { orderDate: 1 } )

If the keys document specifies more than one field, then ensureIndex() creates a compound index.

Create an Index on a Multiple Fields

The following example creates a compound index on the orderDate field (in ascending order) and the zipcode field (in descending order.)

db.collection.ensureIndex( { orderDate: 1, zipcode: -1 } )

A compound index cannot include a hashed index component.

Note

The order of an index is important for supporting sort() operations using the index.

See also

The Indexes section of this manual for full documentation of indexes and indexing in MongoDB.

Text Indexes for details on creating text indexes.

Geospatial Indexes and geoHaystack Indexes for geospatial queries.

TTL Indexes for expiration of data.

db.collection.getIndexes() to view the specifications of existing indexes for a collection.

db.collection.find()

Definition

db.collection.find(<criteria>, <projection>)

Selects documents in a collection and returns a cursor to the selected documents. [1]

Parameter | Description
criteria | Optional. Specifies selection criteria using query operators. To return all documents in a collection, omit this parameter or pass an empty document ({}).
projection | Optional. Specifies the fields to return using projection operators. To return all fields in the matching document, omit this parameter.

param document criteria:
| Optional. Specifies selection criteria using query operators. To return all documents in a collection, omit this parameter or pass an empty document ({}).
param document projection:
| Optional. Specifies the fields to return using projection operators. To return all fields in the matching document, omit this parameter.

Returns:
A cursor to the documents that match the query criteria. When the find() method “returns documents,” the method is actually returning a cursor to the documents.

If the projection argument is specified, the matching documents contain only the projection fields and the _id field. You can optionally exclude the _id field.

Executing find() directly in the mongo shell automatically iterates the cursor to display up to the first 20 documents. Type it to continue iteration.

To access the returned documents with a driver, use the appropriate cursor handling mechanism for the driver language.

The projection parameter takes a document of the following form:

{ field1: <boolean>, field2: <boolean> ... }

The <boolean> value can be any of the following:

1 or true to include the field. The find() method always includes the _id field even if the field is not explicitly stated to return in the projection parameter.

0 or false to exclude the field.

A projection cannot contain both include and exclude specifications, except for the exclusion of the _id field. In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.

[1]
db.collection.find() is a wrapper for the more formal query structure that uses the $query operator.

Examples

Find All Documents in a Collection

The find() method with no parameters returns all documents from a collection and returns all fields for the documents. For example, the following operation returns all documents in the bios collection:

db.bios.find()

Find Documents that Match Query Criteria

To find documents that match a set of selection criteria, call find() with the <criteria> parameter. The following operation returns all the documents from the collection products where qty is greater than 25:

db.products.find( { qty: { $gt: 25 } } )

Query for Equality

The following operation returns documents in the bios collection where _id equals 5:

db.bios.find( { _id: 5 } )

Query Using Operators

The following operation returns documents in the bios collection where _id equals either 5 or ObjectId("507c35dd8fada716c89d0013"):

db.bios.find(
   {
      _id: { $in: [ 5,  ObjectId("507c35dd8fada716c89d0013") ] }
   }
)

Query for Ranges

Combine comparison operators to specify ranges. The following operation returns documents with field between value1 and value2:

db.collection.find( { field: { $gt: value1, $lt: value2 } } );

Query a Field that Contains an Array

If a field contains an array and your query has multiple conditional operators, the field as a whole will match if either a single array element meets the conditions or a combination of array elements meet the conditions.

Given a collection students that contains the following documents:

{ "_id" : 1, "score" : [ -1, 3 ] }
{ "_id" : 2, "score" : [ 1, 5 ] }
{ "_id" : 3, "score" : [ 5, 5 ] }

The following query:

db.students.find( { score: { $gt: 0, $lt: 2 } } )

Matches the following documents:

{ "_id" : 1, "score" : [ -1, 3 ] }
{ "_id" : 2, "score" : [ 1, 5 ] }

In the document with _id equal to 1, the score: [ -1, 3 ] meets the conditions because the element -1 meets the $lt: 2 condition and the element 3 meets the $gt: 0 condition.

In the document with _id equal to 2, the score: [ 1, 5 ] meets the conditions because the element 1 meets both the $lt: 2 condition and the $gt: 0 condition.

Query Arrays

Query for an Array Element

The following operation returns documents in the bios collection where the array field contribs contains the element "UNIX":

db.bios.find( { contribs: "UNIX" } )

Query an Array of Documents

The following operation returns documents in the bios collection where awards array contains an embedded document element that contains the award field equal to "Turing Award" and the year field greater than 1980:

db.bios.find(
   {
      awards: {
                $elemMatch: {
                     award: "Turing Award",
                     year: { $gt: 1980 }
                }
      }
   }
)

Query Embedded Documents

Query Exact Matches on Embedded Documents

The following operation returns documents in the bios collection where the embedded document name is exactly { first: "Yukihiro", last: "Matsumoto" }, including the order:

db.bios.find(
    {
      name: {
              first: "Yukihiro",
              last: "Matsumoto"
            }
    }
)

The name field must match the embedded document exactly. The query does not match documents with the following name fields:

{
   first: "Yukihiro",
   aka: "Matz",
   last: "Matsumoto"
}

{
   last: "Matsumoto",
   first: "Yukihiro"
}

Query Fields of an Embedded Document

The following operation returns documents in the bios collection where the embedded document name contains a field first with the value "Yukihiro" and a field last with the value "Matsumoto". The query uses dot notation to access fields in an embedded document:

db.bios.find(
   {
     "name.first": "Yukihiro",
     "name.last": "Matsumoto"
   }
)

The query matches the document where the name field contains an embedded document with the field first with the value "Yukihiro" and a field last with the value "Matsumoto". For instance, the query would match documents with name fields that held either of the following values:

{
  first: "Yukihiro",
  aka: "Matz",
  last: "Matsumoto"
}

{
  last: "Matsumoto",
  first: "Yukihiro"
}

Projections

The projection parameter specifies which fields to return. The parameter contains either include or exclude specifications, not both, unless the exclude is for the _id field.

Specify the Fields to Return

The following operation returns all the documents from the products collection where qty is greater than 25 and returns only the _id, item and qty fields:

db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } )

The operation returns the following:

{ "_id" : 11, "item" : "pencil", "qty" : 50 }
{ "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 }
{ "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 }

The following operation finds all documents in the bios collection and returns only the name field, contribs field and _id field:

db.bios.find( { }, { name: 1, contribs: 1 } )

Explicitly Excluded Fields

The following operation queries the bios collection and returns all fields except the first field in the name embedded document and the birth field:

db.bios.find(
   { contribs: 'OOP' },
   { 'name.first': 0, birth: 0 }
)

Explicitly Exclude the _id Field

The following operation excludes the _id and qty fields from the result set:

db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } )

The documents in the result set contain all fields except the _id and qty fields:

{ "item" : "pencil", "type" : "no.2" }
{ "item" : "bottle", "type" : "blue" }
{ "item" : "paper" }

The following operation finds documents in the bios collection and returns only the name field and the contribs field:

db.bios.find(
   { },
   { name: 1, contribs: 1, _id: 0 }
)

On Arrays and Embedded Documents

The following operation queries the bios collection and returns the last field in the name embedded document and the first two elements in the contribs array:

db.bios.find(
   { },
   {
     _id: 0,
     'name.last': 1,
     contribs: { $slice: 2 }
   }
)

Iterate the Returned Cursor

The find() method returns a cursor to the results. In the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, the cursor is automatically iterated up to 20 times to access up to the first 20 documents that match the query. You can use the DBQuery.shellBatchSize to change the number of iterations. See Flags and Cursor Behaviors. To iterate manually, assign the returned cursor to a variable using the var keyword.

With Variable Name

The following example uses the variable myCursor to iterate over the cursor and print the matching documents:

var myCursor = db.bios.find( );

myCursor

With next() Method

The following example uses the cursor method next() to access the documents:

var myCursor = db.bios.find( );

var myDocument = myCursor.hasNext() ? myCursor.next() : null;

if (myDocument) {
    var myName = myDocument.name;
    print (tojson(myName));
}

To print, you can also use the printjson() method instead of print(tojson()):

if (myDocument) {
   var myName = myDocument.name;
   printjson(myName);
}

With forEach() Method

The following example uses the cursor method forEach() to iterate the cursor and access the documents:

var myCursor = db.bios.find( );

myCursor.forEach(printjson);

Modify the Cursor Behavior

The mongo shell and the drivers provide several cursor methods that call on the cursor returned by the find() method to modify its behavior.

Order Documents in the Result Set

The sort() method orders the documents in the result set. The following operation returns documents in the bios collection sorted in ascending order by the name field:

db.bios.find().sort( { name: 1 } )

sort() corresponds to the ORDER BY statement in SQL.

Limit the Number of Documents to Return

The limit() method limits the number of documents in the result set. The following operation returns at most 5 documents in the bios collection:

db.bios.find().limit( 5 )

limit() corresponds to the LIMIT statement in SQL.

Set the Starting Point of the Result Set

The skip() method controls the starting point of the results set. The following operation skips the first 5 documents in the bios collection and returns all remaining documents:

db.bios.find().skip( 5 )

Combine Cursor Methods

The following example chains cursor methods:

db.bios.find().sort( { name: 1 } ).limit( 5 )
db.bios.find().limit( 5 ).sort( { name: 1 } )

Regardless of the order you chain the limit() and the sort(), the request to the server has the structure that treats the query and the sort() modifier as a single object. Therefore, the limit() operation method is always applied after the sort() regardless of the specified order of the operations in the chain. See the meta query operators.

db.collection.findAndModify()

Definition

db.collection.findAndModify(<document>)

Modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the new option. The findAndModify() method is a shell helper around the findAndModify command.

The findAndModify() method has the following form:

db.collection.findAndModify({
    query: <document>,
    sort: <document>,
    remove: <boolean>,
    update: <document>,
    new: <boolean>,
    fields: <document>,
    upsert: <boolean>
});

The db.collection.findAndModify() method takes a document parameter with the following embedded document fields:

Parameter
Description

query
Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify() will only select one document to modify.

sort
Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify() modifies the first document in the sort order specified by this argument.

remove
Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.

update
Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.

new
Optional. When true, returns the modified document rather than the original. The findAndModify() method ignores the new option for remove operations. The default is false.

fields
Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { <field1>: 1, <field2>: 1, ... }. See projection.

upsert

Optional. Used in conjunction with the update field.

When true, findAndModify() creates a new document if no document matches the query, or if documents match the query, findAndModify() performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed.

The default is false.

param document query:

Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify() will only select one document to modify.

param document sort:

Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify() modifies the first document in the sort order specified by this argument.

param Boolean remove:

Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.

param document update:

Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.

param Boolean new:

Optional. When true, returns the modified document rather than the original. The findAndModify() method ignores the new option for remove operations. The default is false.

param document fields:

Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { <field1>: 1, <field2>: 1, ... }. See projection.

param Boolean upsert:

Optional. Used in conjunction with the update field.

When true, findAndModify() creates a new document if no document matches the query, or if documents match the query, findAndModify() performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed.

The default is false.

Return Data

The findAndModify() method returns either: the pre-modification document or, if new: true is set, the modified document.

Note

If the query finds no document for update or remove operations, findAndModify() returns null.

If the query finds no document for an update with an upsert operation, findAndModify() creates a new document. If new is false, and the sort option is NOT specified, the method returns null.

If the query finds no document for an update with an upsert operation, findAndModify() creates a new document. If new is false, and a sort option, the method returns an empty document {}.

Behavior

Upsert and Unique Index

When findAndModify() includes the upsert: true option and the query field(s) is not uniquely indexed, the method could insert a document multiple times in certain circumstances.

In the following example, no document with the name Andy exists, and multiple clients issue the following command:

db.people.findAndModify({
    query: { name: "Andy" },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

Then, if these clients’ findAndModify() methods finish the query phase before any command starts the modify phase, and there is no unique index on the name field, the commands may all perform an upsert, creating multiple duplicate documents.

To prevent the creation of multiple duplicate documents, create a unique index on the name field. With the unique index in place, the multiple methods will exhibit one of the following behaviors:

Exactly one findAndModify() successfully inserts a new document.

Zero or more findAndModify() methods update the newly inserted document.

Zero or more findAndModify() methods fail when they attempt to insert a duplicate. If the method fails due to a unique index constraint violation, you can retry the method. Absent a delete of the document, the retry should not fail.

Sharded Collections

When using findAndModify in a sharded environment, the query must contain the shard key for all operations against the shard cluster for the sharded collections.

findAndModify operations issued against mongos instances for non-sharded collections function normally.

Comparisons with the update Method

When updating a document, findAndModify() and the update() method operate differently:

By default, both operations modify a single document. However, the update() method with its multi option can modify more than one document.

If multiple documents match the update criteria, for findAndModify(), you can specify a sort to provide some measure of control on which document to update.

With the default behavior of the update() method, you cannot specify which single document to update when multiple documents match.

By default, findAndModify() method returns the pre-modified version of the document. To obtain the updated document, use the new option.

The update() method returns a WriteResult object that contains the status of the operation. To return the updated document, use the find() method. However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.

You cannot specify a write concern to findAndModify() to override the default write concern whereas, starting in MongoDB 2.6, you can specify a write concern to the update() method.

When modifying a single document, both findAndModify() and the update() method atomically update the document. See Atomicity and Transactions for more details about interactions and order of operations of these methods.

Examples

Update and Return

The following method updates and returns an existing document in the people collection where the document matches the query criteria:

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

This method performs the following actions:

The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.

The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the method will select for modification the first document as ordered by this sort.

The update increments the value of the score field by 1.

The method returns the original (i.e. pre-modification) document selected for this update:

{
  "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
  "name" : "Tom",
  "state" : "active",
  "rating" : 100,
  "score" : 5
}

To return the modified document, add the new:true option to the method.

If no document matched the query condition, the method returns null:

null

Upsert

The following method includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

If the method finds a matching document, the method performs an update.

If the method does not find a matching document, the method creates a new document. Because the method included the sort option, it returns an empty document { } as the original (pre-modification) document:

{ }

If the method did not include a sort option, the method returns null.

null

Return New Document

The following method includes both the upsert: true option and the new:true option. The method either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.

In the following example, no document in the people collection matches the query condition:

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

The method returns the newly inserted document:

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Sort and Remove

By including a sort specification on the rating field, the following example removes from the people collection a single document with the state value of active and the lowest rating among the matching documents:

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

The method returns the deleted document:

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

db.collection.findOne()

Definition

db.collection.findOne(<criteria>, <projection>)

Returns one document that satisfies the specified query criteria. If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk. In capped collections, natural order is the same as insertion order.

Parameter | Description
criteria | Optional. Specifies query selection criteria using query operators.
projection | Optional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.

param document criteria:
| Optional. Specifies query selection criteria using query operators.
param document projection:
| Optional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.

The projection parameter takes a document of the following form:

{ field1: <boolean>, field2: <boolean> ... }

The <boolean> can be one of the following include or exclude values:

1 or true to include. The findOne() method always includes the _id field even if the field is not explicitly specified in the projection parameter.

0 or false to exclude.

The projection argument cannot mix include and exclude specifications, with the exception of excluding the _id field.

returns:

One document that satisfies the criteria specified as the first argument to this method. If you specify a projection parameter, findOne() returns a document that only contains the projection fields. The _id field is always included unless you explicitly exclude it.

Although similar to the find() method, the findOne() method returns a document rather than a cursor.

Examples

With Empty Query Specification

The following operation returns a single document from the bios collection:

db.bios.findOne()

With a Query Specification

The following operation returns the first matching document from the bios collection where either the field first in the embedded document name starts with the letter G or where the field birth is less than new Date('01/01/1945'):

db.bios.findOne(
   {
     $or: [
            { 'name.first' : /^G/ },
            { birth: { $lt: new Date('01/01/1945') } }
          ]
   }
)

With a Projection

The projection parameter specifies which fields to return. The parameter contains either include or exclude specifications, not both, unless the exclude is for the _id field.

Specify the Fields to Return

The following operation finds a document in the bios collection and returns only the name, contribs and _id fields:

db.bios.findOne(
    { },
    { name: 1, contribs: 1 }
)

Return All but the Excluded Fields

The following operation returns a document in the bios collection where the contribs field contains the element OOP and returns all fields except the _id field, the first field in the name embedded document, and the birth field:

db.bios.findOne(
   { contribs: 'OOP' },
   { _id: 0, 'name.first': 0, birth: 0 }
)

The findOne Result Document

You cannot apply cursor methods to the result of findOne() because a single document is returned. You have access to the document directly:

var myDocument = db.bios.findOne();

if (myDocument) {
   var myName = myDocument.name;

   print (tojson(myName));
}

db.collection.getIndexes()

db.collection.getIndexes()

Returns an array that holds a list of documents that identify and describe the existing indexes on the collection. You must call the db.collection.getIndexes() on a collection. For example:

db.collection.getIndexes()

Change collection to the name of the collection whose indexes you want to learn.

The db.collection.getIndexes() items consist of the following fields:

system.indexes.v

Holds the version of the index.

The index version depends on the version of mongod that created the index. Before version 2.0 of MongoDB, the this value was 0; versions 2.0 and later use version 1.

system.indexes.key

Contains a document holding the keys held in the index, and the order of the index. Indexes may be either descending or ascending order. A value of negative one (e.g. -1) indicates an index sorted in descending order while a positive value (e.g. 1) indicates an index sorted in an ascending order.

system.indexes.ns

The namespace context for the index.

system.indexes.name

A unique name for the index comprised of the field names and orders of all keys.

db.collection.getShardDistribution()

Definition

db.collection.getShardDistribution()

Returns:
Prints the data distribution statistics for a sharded collection. You must call the getShardDistribution() method on a sharded collection, as in the following example:

db.myShardedCollection.getShardDistribution()

In the following example, the collection has two shards. The output displays both the individual shard distribution information as well the total shard distribution:

Shard <shard-a> at <host-a>
 data : <size-a> docs : <count-a> chunks : <number of chunks-a>
 estimated data per chunk : <size-a>/<number of chunks-a>
 estimated docs per chunk : <count-a>/<number of chunks-a>

Shard <shard-b> at <host-b>
 data : <size-b> docs : <count-b> chunks : <number of chunks-b>
 estimated data per chunk : <size-b>/<number of chunks-b>
 estimated docs per chunk : <count-b>/<number of chunks-b>

Totals
 data : <stats.size> docs : <stats.count> chunks : <calc total chunks>
 Shard <shard-a> contains  <estDataPercent-a>% data, <estDocPercent-a>% docs in cluster, avg obj size on shard : stats.shards[ <shard-a> ].avgObjSize
 Shard <shard-b> contains  <estDataPercent-b>% data, <estDocPercent-b>% docs in cluster, avg obj size on shard : stats.shards[ <shard-b> ].avgObjSize

See also

Sharding

Output

The output information displays:

<shard-x> is a string that holds the shard name.

<host-x> is a string that holds the host name(s).

<size-x> is a number that includes the size of the data, including the unit of measure (e.g. b, Mb).

<count-x> is a number that reports the number of documents in the shard.

<number of chunks-x> is a number that reports the number of chunks in the shard.

<size-x>/<number of chunks-x> is a calculated value that reflects the estimated data size per chunk for the shard, including the unit of measure (e.g. b, Mb).

<count-x>/<number of chunks-x> is a calculated value that reflects the estimated number of documents per chunk for the shard.

<stats.size> is a value that reports the total size of the data in the sharded collection, including the unit of measure.

<stats.count> is a value that reports the total number of documents in the sharded collection.

<calc total chunks> is a calculated number that reports the number of chunks from all shards, for example:

<calc total chunks> = <number of chunks-a> + <number of chunks-b>

<estDataPercent-x> is a calculated value that reflects, for each shard, the data size as the percentage of the collection’s total data size, for example:

<estDataPercent-x> = <size-x>/<stats.size>

<estDocPercent-x> is a calculated value that reflects, for each shard, the number of documents as the percentage of the total number of documents for the collection, for example:

<estDocPercent-x> = <count-x>/<stats.count>

stats.shards[ <shard-x> ].avgObjSize is a number that reflects the average object size, including the unit of measure, for the shard.

Example Output

For example, the following is a sample output for the distribution of a sharded collection:

Shard shard-a at shard-a/MyMachine.local:30000,MyMachine.local:30001,MyMachine.local:30002
data : 38.14Mb docs : 1000003 chunks : 2
estimated data per chunk : 19.07Mb
estimated docs per chunk : 500001

Shard shard-b at shard-b/MyMachine.local:30100,MyMachine.local:30101,MyMachine.local:30102
data : 38.14Mb docs : 999999 chunks : 3
estimated data per chunk : 12.71Mb
estimated docs per chunk : 333333

Totals
data : 76.29Mb docs : 2000002 chunks : 5
Shard shard-a contains 50% data, 50% docs in cluster, avg obj size on shard : 40b
Shard shard-b contains 49.99% data, 49.99% docs in cluster, avg obj size on shard : 40b

db.collection.getShardVersion()

db.collection.getShardVersion()

This method returns information regarding the state of data in a sharded cluster that is useful when diagnosing underlying issues with a sharded cluster.

For internal and diagnostic use only.

db.collection.group()

Recommended Alternatives

Because db.collection.group() uses JavaScript, it is subject to a number of performance limitations. For most cases the $group operator in the aggregation pipeline provides a suitable alternative with fewer restrictions.

Definition

db.collection.group({ key, reduce, initial [, keyf] [, cond] [, finalize] })

Groups documents in a collection by the specified keys and performs simple aggregation functions such as computing counts and sums. The method is analogous to a SELECT <...> GROUP BY statement in SQL. The group() method returns an array.

The db.collection.group() accepts a single document that contains the following:

Field | Description
key |
reduce | An aggregation function that operates on the documents during the grouping operation. These functions may return a sum or a count. The function takes two arguments: the current document and an aggregation result document for that group.
initial |
keyf | Optional. Alternative to the key field. Specifies a function that creates a “key object” for use as the grouping key. Use keyf instead of key to group by calculated fields rather than existing document fields.
cond |
finalize | Optional. A function that runs each item in the result set before db.collection.group() returns the final value. This function can either modify the result document or replace the result document as a whole.

field key: |
field function reduce:
| An aggregation function that operates on the documents during the grouping operation. These functions may return a sum or a count. The function takes two arguments: the current document and an aggregation result document for that group.
field initial: |
field function keyf:
| Optional. Alternative to the key field. Specifies a function that creates a “key object” for use as the grouping key. Use keyf instead of key to group by calculated fields rather than existing document fields.
field cond: |
field function finalize:
| Optional. A function that runs each item in the result set before db.collection.group() returns the final value. This function can either modify the result document or replace the result document as a whole.

The db.collection.group() method is a shell wrapper for the group command. However, the db.collection.group() method takes the keyf field and the reduce field whereas the group command takes the $keyf field and the $reduce field.

Behavior

Limits and Restrictions

The db.collection.group() method does not work with sharded clusters. Use the aggregation framework or map-reduce in sharded environments.

The result set must fit within the maximum BSON document size.

In version 2.2, the returned array can contain at most 20,000 elements; i.e. at most 20,000 unique groupings. For group by operations that results in more than 20,000 unique groupings, use mapReduce. Previous versions had a limit of 10,000 elements.

Prior to 2.4, the db.collection.group() method took the mongod instance’s JavaScript lock, which blocked all other JavaScript execution.

mongo Shell JavaScript Functions/Properties

Changed in version 2.4: In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties
Available Functions

args

MaxKey

MinKey

assert()

BinData()

DBPointer()

DBRef()

doassert()

emit()

gc()

HexData()

hex_md5()

isNumber()

isObject()

ISODate()

isString()

Map()

MD5()

NumberInt()

NumberLong()

ObjectId()

print()

printjson()

printjsononeline()

sleep()

Timestamp()

tojson()

tojsononeline()

tojsonObject()

UUID()

version()

Examples

The following examples assume an orders collection with documents of the following prototype:

{
  _id: ObjectId("5085a95c8fada716c89d0021"),
  ord_dt: ISODate("2012-07-01T04:00:00Z"),
  ship_dt: ISODate("2012-07-02T04:00:00Z"),
  item: { sku: "abc123",
          price: 1.99,
          uom: "pcs",
          qty: 25 }
}

Group by Two Fields

The following example groups by the ord_dt and item.sku fields those documents that have ord_dt greater than 01/01/2011:

db.orders.group(
   {
     key: { ord_dt: 1, 'item.sku': 1 },
     cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
     reduce: function ( curr, result ) { },
     initial: { }
   }
)

The result is an array of documents that contain the group by fields:

[
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc123"},
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc456"},
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "bcd123"},
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "efg456"},
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "abc123"},
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "efg456"},
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "ijk123"},
  { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc123"},
  { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc456"},
  { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc123"},
  { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc456"}
]

The method call is analogous to the SQL statement:

SELECT ord_dt, item_sku
FROM orders
WHERE ord_dt > '01/01/2012'
GROUP BY ord_dt, item_sku

Calculate the Sum

The following example groups by the ord_dt and item.sku fields, those documents that have ord_dt greater than 01/01/2011 and calculates the sum of the qty field for each grouping:

db.orders.group(
   {
     key: { ord_dt: 1, 'item.sku': 1 },
     cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
     reduce: function( curr, result ) {
                 result.total += curr.item.qty;
             },
     initial: { total : 0 }
   }
)

The result is an array of documents that contain the group by fields and the calculated aggregation field:

[ { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc456", "total" : 25 },
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "bcd123", "total" : 10 },
  { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "efg456", "total" : 10 },
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "efg456", "total" : 15 },
  { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "ijk123", "total" : 20 },
  { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc123", "total" : 45 },
  { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc456", "total" : 25 },
  { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc123", "total" : 25 },
  { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc456", "total" : 25 } ]

The method call is analogous to the SQL statement:

SELECT ord_dt, item_sku, SUM(item_qty) as total
FROM orders
WHERE ord_dt > '01/01/2012'
GROUP BY ord_dt, item_sku

Calculate Sum, Count, and Average

The following example groups by the calculated day_of_week field, those documents that have ord_dt greater than 01/01/2011 and calculates the sum, count, and average of the qty field for each grouping:

db.orders.group(
   {
     keyf: function(doc) {
               return { day_of_week: doc.ord_dt.getDay() };
           },
     cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
    reduce: function( curr, result ) {
                result.total += curr.item.qty;
                result.count++;
            },
    initial: { total : 0, count: 0 },
    finalize: function(result) {
                  var weekdays = [
                       "Sunday", "Monday", "Tuesday",
                       "Wednesday", "Thursday",
                       "Friday", "Saturday"
                      ];
                  result.day_of_week = weekdays[result.day_of_week];
                  result.avg = Math.round(result.total / result.count);
              }
   }
)

The result is an array of documents that contain the group by fields and the calculated aggregation field:

[
  { "day_of_week" : "Sunday", "total" : 70, "count" : 4, "avg" : 18 },
  { "day_of_week" : "Friday", "total" : 110, "count" : 6, "avg" : 18 },
  { "day_of_week" : "Tuesday", "total" : 70, "count" : 3, "avg" : 23 }
]

See also

Aggregation Concepts

db.collection.insert()

Definition

db.collection.insert()

Inserts a document or documents into a collection.

The insert() method has the following syntax:

Changed in version 2.6.

db.collection.insert(
   <document or array of documents>,
   {
     writeConcern: <document>,
     ordered: <boolean>
   }
)

Parameter
Description

document
A document or array of documents to insert into the collection.

writeConcern

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

ordered

Optional. If true, perform an ordered insert of the documents in the array, and if an error occurs with one of documents, MongoDB will return without processing the remaining documents in the array.

If false, perform an unordered insert, and if an error occurs with one of documents, continue processing the remaining documents in the array.

Defaults to true.

New in version 2.6.

param document, array document:

A document or array of documents to insert into the collection.

param document writeConcern:

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

param boolean ordered:

Optional. If true, perform an ordered insert of the documents in the array, and if an error occurs with one of documents, MongoDB will return without processing the remaining documents in the array.

If false, perform an unordered insert, and if an error occurs with one of documents, continue processing the remaining documents in the array.

Defaults to true.

New in version 2.6.

Changed in version 2.6: The insert() returns an object that contains the status of the operation.

Returns:

A WriteResult object for single inserts.

A BulkWriteResult object for bulk inserts.

Behaviors

Safe Writes

Changed in version 2.6.

The insert() method uses the insert command, which uses the default write concern. To specify a different write concern, include the write concern in the options parameter.

Create Collection

If the collection does not exist, then the insert() method will create the collection.

_id Field

If the document does not specify an _id field, then MongoDB will add the _id field and assign a unique ObjectId for the document before inserting. Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.

If the document contains an _id field, the _id value must be unique within the collection to avoid duplicate key error.

Examples

The following examples insert documents into the products collection. If the collection does not exist, the insert() method creates the collection.

Insert a Document without Specifying an _id Field

In the following example, the document passed to the insert() method does not contain the _id field:

db.products.insert( { item: "card", qty: 15 } )

During the insert, mongod will create the _id field and assign it a unique ObjectId value, as verified by the inserted document:

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

The ObjectId values are specific to the machine and time when the operation is run. As such, your values may differ from those in the example.

Insert a Document Specifying an _id Field

In the following example, the document passed to the insert() method includes the _id field. The value of _id must be unique within the collection to avoid duplicate key error.

db.products.insert( { _id: 10, item: "box", qty: 20 } )

The operation inserts the following document in the products collection:

{ "_id" : 10, "item" : "box", "qty" : 20 }

Insert Multiple Documents

The following example performs a bulk insert of three documents by passing an array of documents to the insert() method. By default, MongoDB performs an ordered insert. With ordered inserts, if an error occurs during an insert of one of the documents, MongoDB returns on error without processing the remaining documents in the array.

The documents in the array do not need to have the same fields. For instance, the first document in the array has an _id field and a type field. Because the second and third documents do not contain an _id field, mongod will create the _id field for the second and third documents during the insert:

db.products.insert(
   [
     { _id: 11, item: "pencil", qty: 50, type: "no.2" },
     { item: "pen", qty: 20 },
     { item: "eraser", qty: 25 }
   ]
)

The operation inserted the following three documents:

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }

Perform an Unordered Insert

The following example performs an unordered insert of three documents. With unordered inserts, if an error occurs during an insert of one of the documents, MongoDB continues to insert the remaining documents in the array.

db.products.insert(
   [
     { _id: 20, item: "lamp", qty: 50, type: "desk" },
     { _id: 21, item: "lamp", qty: 20, type: "floor" },
     { _id: 22, item: "bulk", qty: 100 }
   ],
   { ordered: false }
)

Override Default Write Concern

The following operation to a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the write propagates to a majority of the replica set members or the method times out after 5 seconds.

db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

WriteResult

Changed in version 2.6.

When passed a single document, insert() returns a WriteResult object.

Successful Results

The insert() returns a WriteResult object that contains the status of the operation. Upon success, the WriteResult object contains information on the number of documents inserted:

WriteResult({ "nInserted" : 1 })

Write Concern Errors

If the insert() method encounters write concern errors, the results include the WriteResult.writeConcernError field:

WriteResult({
   "nInserted" : 1,
   "writeConcernError" : {
      "code" : 64,
      "errmsg" : "waiting for replication timed out at shard-a"
   }
})

Errors Unrelated to Write Concern

If the insert() method encounters a non-write concern error, the results include the WriteResult.writeError field:

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 11000,
      "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_  dup key: { : 1.0 }"
   }
})

BulkWriteResult

Changed in version 2.6.

When passed an array of documents, insert() returns a BulkWriteResult() object. See BulkWriteResult() for details.

db.collection.isCapped()

db.collection.isCapped()

Returns:
Returns true if the collection is a capped collection, otherwise returns false.

See also

Capped Collections

db.collection.mapReduce()

db.collection.mapReduce(map, reduce, {<out>, <query>, <sort>, <limit>, <finalize>, <scope>, <jsMode>, <verbose>})

The db.collection.mapReduce() method provides a wrapper around the mapReduce command.

db.collection.mapReduce(
                         <map>,
                         <reduce>,
                         {
                           out: <collection>,
                           query: <document>,
                           sort: <document>,
                           limit: <number>,
                           finalize: <function>,
                           scope: <document>,
                           jsMode: <boolean>,
                           verbose: <boolean>
                         }
                       )

db.collection.mapReduce() takes the following parameters:

Field
Description

map

A JavaScript function that associates or “maps” a value with a key and emits the key and value pair.

See Requirements for the map Function for more information.

reduce

A JavaScript function that “reduces” to a single object all the values associated with a particular key.

See Requirements for the reduce Function for more information.

options
A document that specifies additional parameters to db.collection.mapReduce().

field Javascript function map:

A JavaScript function that associates or “maps” a value with a key and emits the key and value pair.

See Requirements for the map Function for more information.

field JavaScript function reduce:

A JavaScript function that “reduces” to a single object all the values associated with a particular key.

See Requirements for the reduce Function for more information.

field document options:

A document that specifies additional parameters to db.collection.mapReduce().

The following table describes additional arguments that db.collection.mapReduce() can accept.

Field
Description

out

Specifies the location of the result of the map-reduce operation. You can output to a collection, output to a collection with an action, or output inline. You may output to a collection when performing map reduce operations on the primary members of the set; on secondary members you may only use the inline output.

See out Options for more information.

query

sort

limit

finalize

Optional. Follows the reduce method and modifies the output.

See Requirements for the finalize Function for more information.

scope

jsMode

verbose

field string or document out:

Specifies the location of the result of the map-reduce operation. You can output to a collection, output to a collection with an action, or output inline. You may output to a collection when performing map reduce operations on the primary members of the set; on secondary members you may only use the inline output.

See out Options for more information.

param query:

param sort:

param limit:

field Javascript function finalize:

Optional. Follows the reduce method and modifies the output.

See Requirements for the finalize Function for more information.

param scope:

param jsMode:

param verbose:

Note

Changed in version 2.4.

In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties
Available Functions

args

MaxKey

MinKey

assert()

BinData()

DBPointer()

DBRef()

doassert()

emit()

gc()

HexData()

hex_md5()

isNumber()

isObject()

ISODate()

isString()

Map()

MD5()

NumberInt()

NumberLong()

ObjectId()

print()

printjson()

printjsononeline()

sleep()

Timestamp()

tojson()

tojsononeline()

tojsonObject()

UUID()

version()

Requirements for the map Function

The map function is responsible for transforming each input document into zero or more documents. It can access the variables defined in the scope parameter, and has the following prototype:

function() {
   ...
   emit(key, value);
}

The map function has the following requirements:

In the map function, reference the current document as this within the function.

The map function should not access the database for any reason.

The map function should be pure, or have no impact outside of the function (i.e. side effects.)

A single emit can only hold half of MongoDB’s maximum BSON document size.

The map function may optionally call emit(key,value) any number of times to create an output document associating key with value.

The following map function will call emit(key,value) either 0 or 1 times depending on the value of the input document’s status field:

function() {
    if (this.status == 'A')
        emit(this.cust_id, 1);
}

The following map function may call emit(key,value) multiple times depending on the number of elements in the input document’s items field:

function() {
    this.items.forEach(function(item){ emit(item.sku, 1); });
}

Requirements for the reduce Function

The reduce function has the following prototype:

function(key, values) {
   ...
   return result;
}

The reduce function exhibits the following behaviors:

The reduce function should not access the database, even to perform read operations.

The reduce function should not affect the outside system.

MongoDB will not call the reduce function for a key that has only a single value. The values argument is an array whose elements are the value objects that are “mapped” to the key.

MongoDB can invoke the reduce function more than once for the same key. In this case, the previous output from the reduce function for that key will become one of the input values to the next reduce function invocation for that key.

The reduce function can access the variables defined in the scope parameter.

The inputs to reduce must not be larger than half of MongoDB’s maximum BSON document size. This requirement may be violated when large documents are returned and then joined together in subsequent reduce steps.

Because it is possible to invoke the reduce function more than once for the same key, the following properties need to be true:

the type of the return object must be identical to the type of the value emitted by the map function.

the reduce function must be associative. The following statement must be true:

reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce( key, [ C, A, B ] )

the reduce function must be idempotent. Ensure that the following statement is true:

reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray )

the reduce function should be commutative: that is, the order of the elements in the valuesArray should not affect the output of the reduce function, so that the following statement is true:

reduce( key, [ A, B ] ) == reduce( key, [ B, A ] )

out Options

You can specify the following options for the out parameter:

Output to a Collection

This option outputs to a new collection, and is not available on secondary members of replica sets.

out: <collectionName>

Output to a Collection with an Action

This option is only available when passing a collection that already exists to out. It is not available on secondary members of replica sets.

out: { <action>: <collectionName>
        [, db: <dbName>]
        [, sharded: <boolean> ]
        [, nonAtomic: <boolean> ] }

When you output to a collection with an action, the out has the following parameters:

<action>: Specify one of the following actions:

replace

Replace the contents of the <collectionName> if the collection with the <collectionName> exists.

merge

Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, overwrite that existing document.

reduce

Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, apply the reduce function to both the new and the existing documents and overwrite the existing document with the result.

db:

Optional. The name of the database that you want the map-reduce operation to write its output. By default this will be the same database as the input collection.

sharded:

Optional. If true and you have enabled sharding on output database, the map-reduce operation will shard the output collection using the _id field as the shard key.

nonAtomic:

New in version 2.2.

Optional. Specify output operation as non-atomic. This applies only to the merge and reduce output modes, which may take minutes to execute.

By default nonAtomic is false, and the map-reduce operation locks the database during post-processing.

If nonAtomic is true, the post-processing step prevents MongoDB from locking the database: during this time, other clients will be able to read intermediate states of the output collection.

Output Inline

Perform the map-reduce operation in memory and return the result. This option is the only available option for out on secondary members of replica sets.

out: { inline: 1 }

The result must fit within the maximum size of a BSON document.

Requirements for the finalize Function

The finalize function has the following prototype:

function(key, reducedValue) {
   ...
   return modifiedObject;
}

The finalize function receives as its arguments a key value and the reducedValue from the reduce function. Be aware that:

The finalize function should not access the database for any reason.

The finalize function should be pure, or have no impact outside of the function (i.e. side effects.)

The finalize function can access the variables defined in the scope parameter.

Map-Reduce Examples

Consider the following map-reduce operations on a collection orders that contains documents of the following prototype:

{
     _id: ObjectId("50a8240b927d5d8b5891743c"),
     cust_id: "abc123",
     ord_date: new Date("Oct 04, 2012"),
     status: 'A',
     price: 25,
     items: [ { sku: "mmm", qty: 5, price: 2.5 },
              { sku: "nnn", qty: 5, price: 2.5 } ]
}

Return the Total Price Per Customer

Perform the map-reduce operation on the orders collection to group by the cust_id, and calculate the sum of the price for each cust_id:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

The function maps the price to the cust_id for each document and emits the cust_id and price pair.

var mapFunction1 = function() {
                       emit(this.cust_id, this.price);
                   };

Define the corresponding reduce function with two arguments keyCustId and valuesPrices:

The valuesPrices is an array whose elements are the price values emitted by the map function and grouped by keyCustId.

The function reduces the valuesPrice array to the sum of its elements.

var reduceFunction1 = function(keyCustId, valuesPrices) {
                          return Array.sum(valuesPrices);
                      };

Perform the map-reduce on all documents in the orders collection using the mapFunction1 map function and the reduceFunction1 reduce function.

db.orders.mapReduce(
                     mapFunction1,
                     reduceFunction1,
                     { out: "map_reduce_example" }
                   )

This operation outputs the results to a collection named map_reduce_example. If the map_reduce_example collection already exists, the operation will replace the contents with the results of this map-reduce operation:

Calculate Order and Total Quantity with Average Quantity Per Item

In this example, you will perform a map-reduce operation on the orders collection for all documents that have an ord_date value greater than 01/01/2012. The operation groups by the item.sku field, and calculates the number of orders and the total quantity ordered for each sku. The operation concludes by calculating the average quantity per order for each sku value:

Define the map function to process each input document:

In the function, this refers to the document that the map-reduce operation is processing.

For each item, the function associates the sku with a new object value that contains the count of 1 and the item qty for the order and emits the sku and value pair.

var mapFunction2 = function() {
                       for (var idx = 0; idx < this.items.length; idx++) {
                           var key = this.items[idx].sku;
                           var value = {
                                         count: 1,
                                         qty: this.items[idx].qty
                                       };
                           emit(key, value);
                       }
                    };

Define the corresponding reduce function with two arguments keySKU and countObjVals:

countObjVals is an array whose elements are the objects mapped to the grouped keySKU values passed by map function to the reducer function.

The function reduces the countObjVals array to a single object reducedValue that contains the count and the qty fields.

In reducedVal, the count field contains the sum of the count fields from the individual array elements, and the qty field contains the sum of the qty fields from the individual array elements.

var reduceFunction2 = function(keySKU, countObjVals) {
                     reducedVal = { count: 0, qty: 0 };

                     for (var idx = 0; idx < countObjVals.length; idx++) {
                         reducedVal.count += countObjVals[idx].count;
                         reducedVal.qty += countObjVals[idx].qty;
                     }

                     return reducedVal;
                  };

Define a finalize function with two arguments key and reducedVal. The function modifies the reducedVal object to add a computed field named avg and returns the modified object:

var finalizeFunction2 = function (key, reducedVal) {

                       reducedVal.avg = reducedVal.qty/reducedVal.count;

                       return reducedVal;

                    };

Perform the map-reduce operation on the orders collection using the mapFunction2, reduceFunction2, and finalizeFunction2 functions.

db.orders.mapReduce( mapFunction2,
                     reduceFunction2,
                     {
                       out: { merge: "map_reduce_example" },
                       query: { ord_date:
                                  { $gt: new Date('01/01/2012') }
                              },
                       finalize: finalizeFunction2
                     }
                   )

This operation uses the query field to select only those documents with ord_date greater than new Date(01/01/2012). Then it output the results to a collection map_reduce_example. If the map_reduce_example collection already exists, the operation will merge the existing contents with the results of this map-reduce operation.

Output

The output of the db.collection.mapReduce() method is identical to that of the mapReduce command. See the Output section of the mapReduce command for information on the db.collection.mapReduce() output.

Additional Information

Troubleshoot the Map Function

Troubleshoot the Reduce Function

mapReduce command

Aggregation Concepts

Map-Reduce

Perform Incremental Map-Reduce

db.collection.reIndex()

db.collection.reIndex()

The db.collection.reIndex() drops all indexes on a collection and recreates them. This operation may be expensive for collections that have a large amount of data and/or a large number of indexes.

Call this method, which takes no arguments, on a collection object. For example:

db.collection.reIndex()

Normally, MongoDB compacts indexes during routine updates. For most users, the db.collection.reIndex() is unnecessary. However, it may be worth running if the collection size has changed significantly or if the indexes are consuming a disproportionate amount of disk space.

Behavior

Note

For replica sets, db.collection.reIndex() will not propagate from the primary to secondaries. db.collection.reIndex() will only affect a single mongod instance.

Important

db.collection.reIndex() will rebuild indexes in the background if the index was originally specified with this option. However, db.collection.reIndex() will rebuild the _id index in the foreground, which takes the database’s write lock.

Changed in version 2.6: Reindexing operations will error if the index entry for an indexed field exceeds the Maximum Index Key Length. Reindexing operations occur as part of compact and repairDatabase commands as well as the db.collection.reIndex() method.

Because these operations drop all the indexes from a collection and then recreate them sequentially, the error from the Maximum Index Key Length prevents these operations from rebuilding any remaining indexes for the collection and, in the case of the repairDatabase command, from continuing with the remainder of the process.

See

Index Creation for more information on the behavior of indexing operations in MongoDB.

db.collection.remove()

Definition

db.collection.remove()

Removes documents from a collection.

The db.collection.remove() method can have one of two syntaxes. The remove() method can take a query document and an optional justOne boolean:

db.collection.remove(
   <query>,
   <justOne>
)

Or the method can take a query document and an optional remove options document:

New in version 2.6.

db.collection.remove(
   <query>,
   {
     justOne: <boolean>,
     writeConcern: <document>
   }
)

Parameter
Description

query

Specifies deletion criteria using query operators. To delete all documents in a collection, pass an empty document ({}).

Changed in version 2.6: In previous versions, the method invoked with no query parameter deleted all documents in a collection.

justOne
Optional. To limit the deletion to just one document, set to true. Omit to use the default value of false and delete all documents matching the deletion criteria.

writeConcern

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

param document query:

Specifies deletion criteria using query operators. To delete all documents in a collection, pass an empty document ({}).

Changed in version 2.6: In previous versions, the method invoked with no query parameter deleted all documents in a collection.

param boolean justOne:

Optional. To limit the deletion to just one document, set to true. Omit to use the default value of false and delete all documents matching the deletion criteria.

param document writeConcern:

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

Changed in version 2.6: The remove() returns an object that contains the status of the operation.

Returns:
A WriteResult object that contains the status of the operation.

Behavior

Safe Writes

Changed in version 2.6.

The remove() method uses the delete command, which uses the default write concern. To specify a different write concern, include the write concern in the options parameter.

Query Considerations

By default, remove() removes all documents that match the query expression. Specify the justOne option to limit the operation to removing a single document. To delete a single document sorted by a specified order, use the findAndModify() method.

When removing multiple documents, the remove operation may interleave with other read and/or write operations to the collection. For unsharded collections, you can override this behavior with the $isolated operator, which “isolates” the remove operation and disallows yielding during the operation. This ensures that no client can see the affected documents until they are all processed or an error stops the remove operation.

See Isolate Remove Operations for an example.

Capped Collections

You cannot use the remove() method with a capped collection.

Sharded Collections

All remove() operations for a sharded collection that specify the justOne option must include the shard key or the _id field in the query specification. remove() operations specifying justOne in a sharded collection without the shard key or the _id field return an error.

Examples

The following are examples of the remove() method.

Remove All Documents from a Collection

To remove all documents in a collection, call the remove method with an empty query document {}. The following operation deletes all documents from the bios collection:

db.bios.remove( { } )

This operation is not equivalent to the drop() method.

To remove all documents from a collection, it may be more efficient to use the drop() method to drop the entire collection, including the indexes, and then recreate the collection and rebuild the indexes.

Remove All Documents that Match a Condition

To remove the documents that match a deletion criteria, call the remove() method with the <query> parameter:

The following operation removes all the documents from the collection products where qty is greater than 20:

db.products.remove( { qty: { $gt: 20 } } )

Override Default Write Concern

The following operation to a replica set removes all the documents from the collection products where qty is greater than 20 and specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the write propagates to a majority of the replica set members or the method times out after 5 seconds.

db.products.remove(
    { qty: { $gt: 20 } },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

Remove a Single Document that Matches a Condition

To remove the first document that match a deletion criteria, call the remove method with the query criteria and the justOne parameter set to true or 1.

The following operation removes the first document from the collection products where qty is greater than 20:

db.products.remove( { qty: { $gt: 20 } }, true )

Isolate Remove Operations

To isolate the query, include $isolated: 1 in the <query> parameter as in the following examples:

db.products.remove( { qty: { $gt: 20 }, $isolated: 1 } )

WriteResult

Changed in version 2.6.

Successful Results

The remove() returns a WriteResult object that contains the status of the operation. Upon success, the WriteResult object contains information on the number of documents removed:

WriteResult({ "nRemoved" : 4 })

See also

WriteResult.nRemoved

Write Concern Errors

If the remove() method encounters write concern errors, the results include the WriteResult.writeConcernError field:

WriteResult({
   "nRemoved" : 21,
   "writeConcernError" : {
      "code" : 64,
      "errInfo" : {
         "wtimeout" : true
      },
      "errmsg" : "waiting for replication timed out"
   }
})

See also

WriteResult.hasWriteConcernError()

Errors Unrelated to Write Concern

If the remove() method encounters a non-write concern error, the results include WriteResult.writeError field:

WriteResult({
   "nRemoved" : 0,
   "writeError" : {
      "code" : 2,
      "errmsg" : "unknown top level operator: $invalidFieldName"
   }
})

See also

WriteResult.hasWriteError()

db.collection.renameCollection()

Definition

db.collection.renameCollection(target, dropTarget)

Renames a collection. Provides a wrapper for the renameCollection database command.

Parameter | Description
target | The new name of the collection. Enclose the string in quotes.
dropTarget | Optional. If true, mongod drops the target of renameCollection prior to renaming the collection.

param string target:
| The new name of the collection. Enclose the string in quotes.
param boolean dropTarget:
| Optional. If true, mongod drops the target of renameCollection prior to renaming the collection.

Example

Call the db.collection.renameCollection() method on a collection object. For example:

db.rrecord.renameCollection("record")

This operation will rename the rrecord collection to record. If the target name (i.e. record) is the name of an existing collection, then the operation will fail.

Limitations

The method has the following limitations:

db.collection.renameCollection() cannot move a collection between databases. Use renameCollection for these rename operations.

db.collection.renameCollection() is not supported on sharded collections.

The db.collection.renameCollection() method operates within a collection by changing the metadata associated with a given collection.

Refer to the documentation renameCollection for additional warnings and messages.

Warning

The db.collection.renameCollection() method and renameCollection command will invalidate open cursors which interrupts queries that are currently returning data.

db.collection.save()

Definition

db.collection.save()

Updates an existing document or inserts a new document, depending on its document parameter.

The save() method has the following form:

Changed in version 2.6.

db.collection.save(
   <document>,
   {
     writeConcern: <document>
   }
)

Parameter
Description

document
A document to save to the collection.

writeConcern

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

param document document:

A document to save to the collection.

param document writeConcern:

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

Changed in version 2.6: The save() returns an object that contains the status of the operation.

Returns:
A WriteResult object that contains the status of the operation.

Behavior

Safe Writes

Changed in version 2.6.

The save() method uses either the insert or the update command, which use the default write concern. To specify a different write concern, include the write concern in the options parameter.

Insert

If the document does not contain an _id field, then the save() method calls the insert() method. During the operation, the mongo shell will create an ObjectId and assign it to the _id field.

Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.

Update

If the document contains an _id field, then the save() method is equivalent to an update with the upsert option set to true and the query predicate on the _id field.

Examples

Save a New Document without Specifying an _id Field

In the following example, save() method performs an insert since the document passed to the method does not contain the _id field:

db.products.save( { item: "book", qty: 40 } )

During the insert, mongod will create the _id field with a unique ObjectId value, as verified by the inserted document:

{ "_id" : ObjectId("50691737d386d8fadbd6b01d"), "item" : "book", "qty" : 40 }

The ObjectId values are specific to the machine and time when the operation is run. As such, your values may differ from those in the example.

Save a New Document Specifying an _id Field

In the following example, save() performs an update with upsert:true since the document contains an _id field:

db.products.save( { _id: 100, item: "water", qty: 30 } )

Because the _id field holds a value that does not exist in the collection, the update operation results in an insertion of the document. The results of these operations are identical to an update() method with the upsert option set to true.

The operation results in the following new document in the products collection:

{ "_id" : 100, "item" : "water", "qty" : 30 }

Replace an Existing Document

The products collection contains the following document:

{ "_id" : 100, "item" : "water", "qty" : 30 }

The save() method performs an update with upsert:true since the document contains an _id field:

db.products.save( { _id : 100, item : "juice" } )

Because the _id field holds a value that exists in the collection, the operation performs an update to replace the document and results in the following document:

{ "_id" : 100, "item" : "juice" }

Override Default Write Concern

The following operation to a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the write propagates to a majority of the replica set members or the method times out after 5 seconds.

db.products.save(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

WriteResult

Changed in version 2.6.

The save() returns a WriteResult object that contains the status of the insert or update operation. See WriteResult for insert and WriteResult for update for details.

db.collection.stats()

Definition

db.collection.stats(scale)

Returns statistics about the collection. The method includes the following parameter:

Parameter | Description
scale | Optional. The scale used in the output to display the sizes of items. By default, output displays sizes in bytes. To display kilobytes rather than bytes, specify a scale value of 1024.

param number scale:

Optional. The scale used in the output to display the sizes of items. By default, output displays sizes in bytes. To display kilobytes rather than bytes, specify a scale value of 1024.

Returns:
A document that contains statistics on the specified collection.

The stats() method provides a wrapper around the database command collStats.

Example

The following operation returns stats on the people collection:

db.people.stats()

See also

collStats for an overview of the output of this command.

db.collection.storageSize()

db.collection.storageSize()

Returns:
The total amount of storage allocated to this collection for document storage. Provides a wrapper around the storageSize field of the collStats (i.e. db.collection.stats()) output.

db.collection.totalSize()

db.collection.totalSize()

Returns:
The total size of the data in the collection plus the size of every indexes on the collection.

db.collection.totalIndexSize()

db.collection.totalIndexSize()

Returns:
The total size of all indexes for the collection. This method provides a wrapper around the totalIndexSize output of the collStats (i.e. db.collection.stats()) operation.

db.collection.update()

Definition

db.collection.update(query, update, options)

Modifies an existing document or documents in a collection. The method can modify specific fields of an existing document or documents or replace an existing document entirely, depending on the update parameter.

By default, the update() method updates a single document. Set the Multi Parameter to update all documents that match the query criteria.

The update() method has the following form:

Changed in version 2.6.

db.collection.update(
   <query>,
   <update>,
   {
     upsert: <boolean>,
     multi: <boolean>,
     writeConcern: <document>
   }
)

The update() method takes the following parameters:

Parameter
Description

query
The selection criteria for the update. Use the same query selectors as used in the find() method.

update
The modifications to apply. For details see Update Parameter.

upsert
Optional. If set to true, creates a new document when no document matches the query criteria. The default value is false, which does not insert a new document when no match is found.

multi
Optional. If set to true, updates multiple documents that meet the query criteria. If set to false, updates one document. The default value is false. For additional information, see Multi Parameter.

writeConcern

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

param document query:

The selection criteria for the update. Use the same query selectors as used in the find() method.

param document update:

The modifications to apply. For details see Update Parameter.

param boolean upsert:

Optional. If set to true, creates a new document when no document matches the query criteria. The default value is false, which does not insert a new document when no match is found.

param boolean multi:

Optional. If set to true, updates multiple documents that meet the query criteria. If set to false, updates one document. The default value is false. For additional information, see Multi Parameter.

param document writeConcern:

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

Changed in version 2.6: The update() method returns an object that contains the status of the operation.

Returns:
A WriteResult object that contains the status of the operation.

Behavior

Safe Writes

Changed in version 2.6.

The update() method uses the update command, which uses the default write concern. To specify a different write concern, include the writeConcern option in the options parameter. See Override Default Write Concern for an example.

Update Parameter

The update() method either modifies specific fields in existing documents or replaces an existing document entirely.

Update Specific Fields

If the <update> document contains update operator modifiers, such as those using the $set modifier, then:

The <update> document must contain only update operator expressions.

The update() method updates only the corresponding fields in the document.

To update an embedded document or an array as a whole, specify the replacement value for the field. To update particular fields in an embedded document or in an array, use dot notation to specify the field.

Replace a Document Entirely

If the <update> document contains only field:value expressions, then:

The update() method replaces the matching document with the <update> document. The update() method does not replace the _id value. For an example, see Replace All Fields.

update() cannot update multiple documents.

Upsert Option

Upsert Behavior

If upsert is true and no document matches the query criteria, update() inserts a single document. The update creates the new document with either:

The fields and values of the <update> parameter if the <update> parameter contains only field and value pairs, or

The fields and values of both the <query> and <update> parameters if the <update> parameter contains update operator expressions. The update creates a base document from the equality clauses in the <query> parameter, and then applies the update expressions from the <update> parameter.

If upsert is true and there are documents that match the query criteria, update() performs an update.

See also

$setOnInsert

Use Unique Indexes

Warning

To avoid inserting the same document more than once, only use upsert: true if the query field is uniquely indexed.

Given a collection named people where no documents have a name field that holds the value Andy. Consider when multiple clients issue the following update with upsert: true at the same time:

db.people.update(
   { name: "Andy" },
   {
      name: "Andy",
      rating: 1,
      score: 1
   },
   { upsert: true }
)

If all update() operations complete the query portion before any client successfully inserts data, and there is no unique index on the name field, then each update operation may result in an insert.

To prevent MongoDB from inserting the same document more than once, create a unique index on the name field. With a unique index, if multiple applications issue the same update with upsert: true, exactly one update() would successfully insert a new document.

The remaining operations would either:

update the newly inserted document, or

fail when they attempted to insert a duplicate.

If the operation fails because of a duplicate index key error, applications may retry the operation which will succeed as an update operation.

Multi Parameter

If multi is set to true, the update() method updates all documents that meet the <query> criteria. The multi update operation may interleave with other operations, both read and/or write operations. For unsharded collections, you can override this behavior with the $isolated operator, which isolates the update operation and disallows yielding during the operation. This isolates the update so that no client can see the updated documents until they are all processed, or an error stops the update operation.

If the <update> document contains only field:value expressions, then update() cannot update multiple documents.

For an example, see Update Multiple Documents.

Sharded Collections

All update() operations for a sharded collection that specify the multi: false option must include the shard key or the _id field in the query specification. update() operations specifying multi: false in a sharded collection without the shard key or the _id field return an error.

See also

findAndModify()

Examples

Update Specific Fields

To update specific fields in a document, use update operators in the <update> parameter.

For example, given a books collection with the following document:

{
  _id: 1,
  item: "TBD",
  stock: 0,
  info: { publisher: "1111", pages: 430 },
  tags: [ "technology", "computer" ],
  ratings: [ { by: "ijk", rating: 4 }, { by: "lmn", rating: 5 } ],
  reorder: false
}

The following operation uses:

the $inc operator to increment the stock field; and

the $set operator to replace the value of the item field, the publisher field in the info embedded document, the tags field, and the second element in the ratings array.

db.books.update(
   { _id: 1 },
   {
     $inc: { stock: 5 },
     $set: {
       item: "ABC123",
       "info.publisher": "2222",
       tags: [ "software" ],
       "ratings.1": { by: "xyz", rating: 3 }
     }
   }
)

The updated document is the following:

{
  "_id" : 1,
  "item" : "ABC123",
  "stock" : 5,
  "info" : { "publisher" : "2222", "pages" : 430 },
  "tags" : [ "software" ],
  "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ],
  "reorder" : false
}

See also

$set, $inc, Update Operators, dot notation

Remove Fields

The following operation uses the $unset operator to remove the tags field:

db.books.update( { _id: 1 }, { $unset: { tags: 1 } } )

See also

$unset, $rename, Update Operators

Replace All Fields

Given the following document in the books collection:

{
  _id: 2,
  item: "XYZ123",
  stock: 15,
  info: { publisher: "5555", pages: 150 },
  tags: [ ],
  ratings: [ { by: "xyz", rating: 5, comment: "ratings and reorder will go away after update"} ],
  reorder: false
}

The following operation passes an <update> document that contains only field and value pairs. The <update> document completely replaces the original document except for the _id field.

db.books.update(
   { item: "XYZ123" },
   {
     item: "XYZ123",
     stock: 10,
     info: { publisher: "2255", pages: 150 },
     tags: [ "baking", "cooking" ]
   }
)

The updated document contains only the fields from the replacement document and the _id field. That is, the fields ratings and reorder no longer exist in the updated document since the fields were not in the replacement document.

{
   "_id" : 2,
   "item" : "XYZ123",
   "stock" : 10,
   "info" : { "publisher" : "2255", "pages" : 150 },
   "tags" : [ "baking", "cooking" ]
}

Insert a New Document if No Match Exists

The following update sets the upsert option to true so that update() creates a new document in the books collection if no document matches the <query> parameter:

db.books.update(
   { item: "ZZZ135" },
   {
     item: "ZZZ135",
     stock: 5,
     tags: [ "database" ]
   },
   { upsert: true }
)

If no document matches the <query> parameter, the update operation inserts a document with only the fields and values of the <update> document and a new unique ObjectId for the _id field:

{
  "_id" : ObjectId("542310906694ce357ad2a1a9"),
  "item" : "ZZZ135",
  "stock" : 5,
  "tags" : [ "database" ]
}

For more information on upsert option and the inserted document, Upsert Option.

Update Multiple Documents

To update multiple documents, set the multi option to true. For example, the following operation updates all documents where stock is less than or equal to 10:

db.books.update(
   { stock: { $lte: 10 } },
   { $set: { reorder: true } },
   { multi: true }
)

If the reorder field does not exist in the matching document(s), the $set operator will add the field with the specified value. See $set for more information.

Override Default Write Concern

The following operation on a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the write propagates to a majority of the replica set members or the method times out after 5 seconds.

db.books.update(
   { stock: { $lte: 10 } },
   { $set: { reorder: true } },
   {
     multi: true,
     writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Combine the upsert and multi Options

Given a books collection that includes the following documents:

{
  _id: 5,
  item: "EFG222",
  stock: 18,
  info: { publisher: "0000", pages: 70 },
  reorder: true
}
{
  _id: 6,
  item: "EFG222",
  stock: 15,
  info: { publisher: "1111", pages: 72 },
  reorder: true
}

The following operation specifies both the multi option and the upsert option. If matching documents exist, the operation updates all matching documents. If no matching documents exist, the operation inserts a new document.

db.books.update(
   { item: "EFG222" },
   { $set: { reorder: false, tags: [ "literature", "translated" ] } },
   { upsert: true, multi: true }
)

The operation updates all matching documents and results in the following:

{
   "_id" : 5,
   "item" : "EFG222",
   "stock" : 18,
   "info" : { "publisher" : "0000", "pages" : 70 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}
{
   "_id" : 6,
   "item" : "EFG222",
   "stock" : 15,
   "info" : { "publisher" : "1111", "pages" : 72 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}

If the collection had no matching document, the operation would result in the insertion of a document using the fields from both the <query> and the <update> specifications:

{
   "_id" : ObjectId("5423200e6694ce357ad2a1ac"),
   "item" : "EFG222",
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}

For more information on upsert option and the inserted document, Upsert Option.

WriteResult

Changed in version 2.6.

Successful Results

The update() method returns a WriteResult object that contains the status of the operation. Upon success, the WriteResult object contains the number of documents that matched the query condition, the number of documents inserted by the update, and the number of documents modified:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

See

WriteResult.nMatched, WriteResult.nUpserted, WriteResult.nModified

Write Concern Errors

If the update() method encounters write concern errors, the results include the WriteResult.writeConcernError field:

WriteResult({
   "nMatched" : 1,
   "nUpserted" : 0,
   "nModified" : 1,
   "writeConcernError" : {
      "code" : 64,
      "errmsg" : "waiting for replication timed out at shard-a"
   }
})

See also

WriteResult.hasWriteConcernError()

Errors Unrelated to Write Concern

If the update() method encounters a non-write concern error, the results include the WriteResult.writeError field:

WriteResult({
   "nMatched" : 0,
   "nUpserted" : 0,
   "nModified" : 0,
   "writeError" : {
      "code" : 7,
      "errmsg" : "could not contact primary for replica set shard-a"
   }
})

See also

WriteResult.hasWriteError()

db.collection.validate()

Description

db.collection.validate(full)

Validates a collection. The method scans a collection’s data structures for correctness and returns a single document that describes the relationship between the logical collection and the physical representation of the data.

The validate() method has the following parameter:

Parameter | Description
full | Optional. Specify true to enable a full validation and to return full statistics. MongoDB disables full validation by default because it is a potentially resource-intensive operation.

param Boolean full:

Optional. Specify true to enable a full validation and to return full statistics. MongoDB disables full validation by default because it is a potentially resource-intensive operation.

The validate() method output provides an in-depth view of how the collection uses storage. Be aware that this command is potentially resource intensive and may impact the performance of your MongoDB instance.

The validate() method is a wrapper around the validate database command.

See also

validate

Cursor Methods

Name | Description
cursor.addOption() | Adds special wire protocol flags that modify the behavior of the query.’
cursor.batchSize() | Controls the number of documents MongoDB will return to the client in a single network message.
cursor.count() | Returns a count of the documents in a cursor.
cursor.explain() | Reports on the query execution plan, including index use, for a cursor.
cursor.forEach() | Applies a JavaScript function for every document in a cursor.
cursor.hasNext() | Returns true if the cursor has documents and can be iterated.
cursor.hint() | Forces MongoDB to use a specific index for a query.
cursor.limit() | Constrains the size of a cursor’s result set.
cursor.map() | Applies a function to each document in a cursor and collects the return values in an array.
cursor.maxTimeMS() | Specifies a cumulative time limit in milliseconds for processing operations on a cursor.
cursor.max() | Specifies an exclusive upper index bound for a cursor. For use with cursor.hint()
cursor.min() | Specifies an inclusive lower index bound for a cursor. For use with cursor.hint()
cursor.next() | Returns the next document in a cursor.
cursor.objsLeftInBatch() | Returns the number of documents left in the current cursor batch.
cursor.readPref() | Specifies a read preference to a cursor to control how the client directs queries to a replica set.
cursor.showDiskLoc() | Returns a cursor with modified documents that include the on-disk location of the document.
cursor.size() | Returns a count of the documents in the cursor after applying skip() and limit() methods.
cursor.skip() | Returns a cursor that begins returning results only after passing or skipping a number of documents.
cursor.snapshot() | Forces the cursor to use the index on the _id field. Ensures that the cursor returns each document, with regards to the value of the _id field, only once.
cursor.sort() | Returns results ordered according to a sort specification.
cursor.toArray() | Returns an array that contains all documents returned by the cursor.

cursor.addOption()

cursor.batchSize()

cursor.count()

cursor.explain()

cursor.forEach()

cursor.hasNext()

cursor.hint()

cursor.limit()

cursor.map()

cursor.maxTimeMS()

cursor.max()

cursor.min()

cursor.next()

cursor.objsLeftInBatch()

cursor.readPref()

cursor.showDiskLoc()

cursor.size()

cursor.skip()

cursor.snapshot()

cursor.sort()

cursor.toArray()

cursor.addOption()

Definition

cursor.addOption(flag)

Adds OP_QUERY wire protocol flags, such as the tailable flag, to change the behavior of queries.

The cursor.addOption() method has the following parameter:

Parameter
Description

flag
OP_QUERY wire protocol flag. See MongoDB wire protocol [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/?pageVersion=106#op-query] for more information on MongoDB Wire Protocols and the OP_QUERY flags. For the mongo shell, you can use cursor flags. For the driver-specific list, see your driver documentation.

param flag flag:

OP_QUERY wire protocol flag. See MongoDB wire protocol [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/?pageVersion=106#op-query] for more information on MongoDB Wire Protocols and the OP_QUERY flags. For the mongo shell, you can use cursor flags. For the driver-specific list, see your driver documentation.

Flags

The mongo shell provides several additional cursor flags to modify the behavior of the cursor.

DBQuery.Option.tailable

DBQuery.Option.slaveOk

DBQuery.Option.oplogReplay

DBQuery.Option.noTimeout

DBQuery.Option.awaitData

DBQuery.Option.exhaust

DBQuery.Option.partial

For a description of the flags, see MongoDB wire protocol [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/?pageVersion=106#op-query].

Example

The following example adds the DBQuery.Option.tailable flag and the DBQuery.Option.awaitData flag to ensure that the query returns a tailable cursor. The sequence creates a cursor that will wait for few seconds after returning the full result set so that it can capture and return additional data added during the query:

var t = db.myCappedCollection;
var cursor = t.find().addOption(DBQuery.Option.tailable).
                      addOption(DBQuery.Option.awaitData)

Warning

Adding incorrect wire protocol flags can cause problems and/or extra server load.

cursor.batchSize()

Definition

cursor.batchSize(size)

Specifies the number of documents to return in each batch of the response from the MongoDB instance. In most cases, modifying the batch size will not affect the user or the application, as the mongo shell and most drivers return results as if MongoDB returned a single batch.

The batchSize() method takes the following parameter:

Parameter | Description
size | The number of documents to return per batch. Do not use a batch size of 1.

param integer size:

The number of documents to return per batch. Do not use a batch size of 1.

Note

Specifying 1 or a negative number is analogous to using the limit() method.

Example

The following example sets the batch size for the results of a query (i.e. find()) to 10. The batchSize() method does not change the output in the mongo shell, which, by default, iterates over the first 20 documents.

db.inventory.find().batchSize(10)

cursor.count()

Definition

cursor.count()

Counts the number of documents referenced by a cursor. Append the count() method to a find() query to return the number of matching documents. The operation does not perform the query but instead counts the results that would be returned by the query.

Changed in version 2.6: MongoDB supports the use of hint() with count(). See Specify the Index to Use for an example.

The count() method has the following prototype form:

db.collection.find(<query>).count()

The count() method has the following parameter:

Parameter | Description
applySkipLimit | Optional. Specifies whether to consider the effects of the cursor.skip() and cursor.limit() methods in the count. By default, the count() method ignores the effects of the cursor.skip() and cursor.limit(). Set applySkipLimit to true to consider the effect of these methods.

param Boolean applySkipLimit:

Optional. Specifies whether to consider the effects of the cursor.skip() and cursor.limit() methods in the count. By default, the count() method ignores the effects of the cursor.skip() and cursor.limit(). Set applySkipLimit to true to consider the effect of these methods.

MongoDB also provides an equivalent db.collection.count() as an alternative to the db.collection.find(<query>).count() construct.

See also

cursor.size()

Behavior

Sharded Clusters

On a sharded cluster, count() method can result in an inaccurate count if orphaned documents exist or if a chunk migration is in progress.

To avoid these situations, on a sharded cluster, use the $group stage of the db.collection.aggregate() method to $sum the documents. For example, the following operation counts the documents in a collection:

db.collection.aggregate(
   [
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

To get a count of documents that match a query condition, include the $match stage as well:

db.collection.aggregate(
   [
      { $match: <query condition> },
      { $group: { _id: null, count: { $sum: 1 } } }
   ]
)

See Perform a Count for an example.

Index Use

Consider a collection with the following index:

{ a: 1, b: 1 }

When performing a count, MongoDB can return the count using only the index if:

the query can use an index,

the query only contains conditions on the keys of the index, and

the query predicates access a single contiguous range of index keys.

For example, the following operations can return the count using only the index:

db.collection.find( { a: 5, b: 5 } ).count()
db.collection.find( { a: { $gt: 5 } } ).count()
db.collection.find( { a: 5, b: { $gt: 10 } } ).count()

If, however, the query can use an index but the query predicates do not access a single contiguous range of index keys or the query also contains conditions on fields outside the index, then in addition to using the index, MongoDB must also read the documents to return the count.

db.collection.find( { a: 5, b: { $in: [ 1, 2, 3 ] } } ).count()
db.collection.find( { a: { $gt: 5 }, b: 5 } ).count()
db.collection.find( { a: 5, b: 5, c: 5 } ).count()

In such cases, during the initial read of the documents, MongoDB pages the documents into memory such that subsequent calls of the same count operation will have better performance.

Examples

The following are examples of the count() method.

Count All Documents

The following operation counts the number of all documents in the orders collection:

db.orders.find().count()

Count Documents That Match a Query

The following operation counts the number of the documents in the orders collection with the field ord_dt greater than new Date('01/01/2012'):

db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).count()

Limit Documents in Count

The following operation counts the number of the documents in the orders collection with the field ord_dt greater than new Date('01/01/2012') taking into account the effect of the limit(5):

db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).limit(5).count(true)

Specify the Index to Use

The following operation uses the index named "status_1", which has the index key specification of { status: 1 }, to return a count of the documents in the orders collection with the field ord_dt greater than new Date('01/01/2012') and the status field is equal to "D":

db.orders.find(
   { ord_dt: { $gt: new Date('01/01/2012') }, status: "D" }
).hint( "status_1" ).count()

cursor.explain()

Definition

cursor.explain(verbose)

Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information may be useful when optimizing a query. The explain() method returns a document that describes the process used to return the query results.

The explain() method has the following form:

db.collection.find().explain()

The explain() method has the following parameter:

Parameter | Description
verbose | Optional. Specifies the level of detail to include in the output. If true or 1, includes the allPlans and oldPlan fields in the output.

param Boolean verbose:

Optional. Specifies the level of detail to include in the output. If true or 1, includes the allPlans and oldPlan fields in the output.

For an explanation of output, see Explain on Queries on Sharded Collections and Core Explain Output Fields.

Behavior

The explain() method runs the actual query to determine the result. Although there are some differences between running the query with explain() and running without, generally, the performance will be similar between the two. So, if the query is slow, the explain() operation is also slow.

Additionally, the explain() operation reevaluates a set of candidate query plans, which may cause the explain() operation to perform differently than a normal query. As a result, these operations generally provide an accurate account of how MongoDB would perform the query, but do not reflect the length of these queries.

Explain Results

Explain on Queries on Unsharded Collections

For queries on unsharded collections, explain() returns the following core information.

{
  "cursor" : "<Cursor Type and Index>",
  "isMultiKey" : <boolean>,
  "n" : <num>,
  "nscannedObjects" : <num>,
  "nscanned" : <num>,
  "nscannedObjectsAllPlans" : <num>,
  "nscannedAllPlans" : <num>,
  "scanAndOrder" : <boolean>,
  "indexOnly" : <boolean>,
  "nYields" : <num>,
  "nChunkSkips" : <num>,
  "millis" : <num>,
  "indexBounds" : { <index bounds> },
  "allPlans" : [
                 { "cursor" : "<Cursor Type and Index>",
                   "n" : <num>,
                   "nscannedObjects" : <num>,
                   "nscanned" : <num>,
                   "indexBounds" : { <index bounds> }
                 },
                  ...
               ],
  "oldPlan" : {
                "cursor" : "<Cursor Type and Index>",
                "indexBounds" : { <index bounds> }
              }
  "server" : "<host:port>",
  "filterSet" : <boolean>
}

For details on the fields, see Core Explain Output Fields.

Explain on $or Queries

Queries with the $or operator can use separate indexes on each clause of the $or expression. If the query is indexed, explain() contains output for each clause as well as the cumulative data for the entire query:

{
   "clauses" : [
                  {
                     <core explain output>
                  },
                  {
                     <core explain output>
                  },
                  ...
               ],
   "n" : <num>,
   "nscannedObjects" : <num>,
   "nscanned" : <num>,
   "nscannedObjectsAllPlans" : <num>,
   "nscannedAllPlans" : <num>,
   "millis" : <num>,
   "server" : "<host:port>"
}

For details on the fields, see $or Query Output Fields and Core Explain Output Fields.

Explain on Queries on Sharded Collections

For queries on sharded collections, explain() returns information for each shard the query accesses. For queries on unsharded collections, see Core Explain Output Fields.

For queries on a sharded collection, the output contains the Core Explain Output Fields for each accessed shard and cumulative shard information:

{
   "clusteredType" : "<Shard Access Type>",
   "shards" : {

                "<shard1>" : [
                               {
                                 <core explain output>
                               }
                             ],
                "<shard2>" : [
                               {
                                <core explain output>
                               }
                             ],
                ...
              },
   "millisShardTotal" : <num>,
   "millisShardAvg" : <num>,
   "numQueries" : <num>,
   "numShards" : <num>,
   "cursor" : "<Cursor Type and Index>",
   "n" : <num>,
   "nChunkSkips" : <num>,
   "nYields" : <num>,
   "nscanned" : <num>,
   "nscannedAllPlans" : <num>,
   "nscannedObjects" : <num>,
   "nscannedObjectsAllPlans" : <num>,
   "millis" : <num>
}

For details on these fields, see Core Explain Output Fields for each accessed shard and Sharded Collections Output Fields.

Explain Output Fields

Core Explain Output Fields

This section explains output for queries on collections that are not sharded. For queries on sharded collections, see Explain on Queries on Sharded Collections.

explain.cursor

cursor is a string that reports the type of cursor used by the query operation:

BasicCursor indicates a full collection scan.

BtreeCursor indicates that the query used an index. The cursor includes name of the index. When a query uses an index, the output of explain() includes indexBounds details.

GeoSearchCursor indicates that the query used a geospatial index.

Complex Plan indicates that MongoDB used index intersection.

For BtreeCursor cursors, MongoDB will append the name of the index to the cursor string. Additionally, depending on how the query uses an index, MongoDB may append one or both of the following strings to the cursor string:

reverse indicates that query transverses the index from the highest values to the lowest values (e.g. “right to left”.)

multi indicates that the query performed multiple look-ups. Otherwise, the query uses the index to determine a range of possible matches.

explain.isMultiKey

isMultiKey is a boolean. When true, the query uses a multikey index, where one of the fields in the index holds an array.

explain.n

n is the number of documents that match the query selection criteria.

explain.nscanned

nscanned is the total number of index entries scanned (or documents for a collection scan).

nscanned can be greater than nscannedObjects, which is the total number of documents scanned during the query. For examples, see Covered Query Explain Output, Multikey Index Explain Output, and Compare Performance of Indexes.

explain.nscannedObjects

nscannedObjects is the total number of documents scanned.

nscannedObjects can be lower than nscanned. For examples, see Covered Query Explain Output, Multikey Index Explain Output, and Compare Performance of Indexes.

explain.nscannedObjectsAllPlans

New in version 2.2.

nscannedObjectsAllPlans is a number that reflects the total number of documents scanned for all query plans during the database operation.

explain.nscannedAllPlans

New in version 2.2.

nscannedAllPlans is a number that reflects the total number of documents or index entries scanned for all query plans during the database operation.

explain.scanAndOrder

scanAndOrder is a boolean that is true when the query cannot use the order of documents in the index for returning sorted results: MongoDB must sort the documents after it receives the documents from a cursor.

If scanAndOrder is false, MongoDB can use the order of the documents in an index to return sorted results.

explain.indexOnly

indexOnly is a boolean value that returns true when the query is covered by the index indicated in the cursor field. When an index covers a query, MongoDB can both match the query conditions and return the results using only the index because:

all the fields in the query are part of that index, and

all the fields returned in the results set are in the same index.

explain.nYields

nYields is a number that reflects the number of times this query yielded the read lock to allow waiting writes to execute.

explain.nChunkSkips

nChunkSkips is a number that reflects the number of documents skipped because of active chunk migrations in a sharded system. Typically this will be zero. A number greater than zero is ok, but indicates a little bit of inefficiency.

explain.millis

millis is a number that reflects the time in milliseconds to complete the query.

explain.indexBounds

indexBounds is a document that contains the lower and upper index key bounds. This field resembles one of the following:

"indexBounds" : {
                    "start" : { <index key1> : <value>, ...  },
                    "end" : { <index key1> : <value>, ... }
                },

"indexBounds" : { "<field>" : [ [ <lower bound>, <upper bound> ] ],
                  ...
                }

explain.allPlans

allPlans is an array that holds the list of plans the query optimizer runs in order to select the index for the query. Displays only when the <verbose> parameter to explain() is true or 1.

explain.oldPlan

New in version 2.2.

oldPlan is a document value that contains the previous plan selected by the query optimizer for the query. Displays only when the <verbose> parameter to explain() is true or 1.

explain.server

New in version 2.2.

server is a string that reports the MongoDB server hostname or IP address.

explain.filterSet

New in version 2.6.

filterSet is a boolean that indicates whether MongoDB applied an index filter for the query.

$or Query Output Fields

explain.clauses

clauses is an array that holds the Core Explain Output Fields information for each clause of the $or expression. clauses is only included when the clauses in the $or expression use indexes.

Sharded Collections Output Fields

explain.clusteredType

clusteredType is a string that reports the access pattern for shards. The value is:

ParallelSort, if the mongos queries shards in parallel.

SerialServer, if the mongos queries shards sequentially.

explain.shards

shards contains fields for each shard in the cluster accessed during the query. Each field holds the Core Explain Output Fields for that shard.

explain.millisShardTotal

millisShardTotal is a number that reports the total time in milliseconds for the query to run on the shards.

explain.millisShardAvg

millisShardAvg is a number that reports the average time in millisecond for the query to run on each shard.

explain.numQueries

numQueries is a number that reports the total number of queries executed.

explain.numShards

numShards is a number that reports the total number of shards queried.

Examples

Consider a collection survey with the following documents:

{ "_id" : 1, "item" : "xyz", "ratings" : [ 8, 9, 10 ] }
{ "_id" : 2, "item" : "abc", "ratings" : [ 7 ] }
{ "_id" : 3, "item" : "ijk", "ratings" : [ 6, 5 ] }
{ "_id" : 4, "item" : "lmn", "ratings" : [ 8 ] }

Collection Scan

Consider the query:

db.survey.find( { item: "abc" } )

If no index supports the query, MongoDB must perform a collection scan. To view the query plan used, use explain():

db.survey.find( { item: "abc" } ).explain()

explain() returns the following output:

{
   "cursor" : "BasicCursor",
   "isMultiKey" : false,
   "n" : 1,
   "nscannedObjects" : 4,
   "nscanned" : 4,
   "nscannedObjectsAllPlans" : 4,
   "nscannedAllPlans" : 4,
   "scanAndOrder" : false,
   "indexOnly" : false,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BasicCursor to indicate a collection scan.

n displays 1 to indicate that the query matches and returns one document.

However, nscanned and nscannedObjects display 4 to indicate that MongoDB had to scan four documents (i.e. all the documents in the collection) to find the one document that matched.

Index Use

Consider the following index on the item field on the survey collection:

db.survey.ensureIndex( { item: 1 } )

To view how MongoDB uses the index for the following query on the item field, use explain():

db.survey.find( { item: "abc" } ).explain()

explain() returns the following output:

{
   "cursor" : "BtreeCursor item_1",
   "isMultiKey" : false,
   "n" : 1,
   "nscannedObjects" : 1,
   "nscanned" : 1,
   "nscannedObjectsAllPlans" : 1,
   "nscannedAllPlans" : 1,
   "scanAndOrder" : false,
   "indexOnly" : false,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "indexBounds" : { "item" : [ [ "abc", "abc" ] ] },
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BtreeCursor item_1 to indicate index use and the name of the index.

n displays 1 to indicate that the query matches and returns one document.

nscanned displays 1 to indicate that MongoDB scanned one index entry.

nscannedObjects displays 1 to indicate that MongoDB scanned one document.

Covered Query Explain Output

With covered queries, MongoDB can use the index to match and return the results; i.e. MongoDB does not need access the documents. If an index covers a query, nscannedObjects will be 0.

Consider the following query, which specify a query predicate on the indexed item field and returns only the indexed item field:

db.survey.find( { item: "abc" }, { item: 1, _id: 0 } )

To view how MongoDB uses the index for the query, use explain():

db.survey.find( { item: "abc" }, { item: 1, _id: 0 } ).explain()

explain() returns the following output:

{
   "cursor" : "BtreeCursor item_1",
   "isMultiKey" : false,
   "n" : 1,
   "nscannedObjects" : 0,
   "nscanned" : 1,
   "nscannedObjectsAllPlans" : 0,
   "nscannedAllPlans" : 1,
   "scanAndOrder" : false,
   "indexOnly" : true,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "indexBounds" : { "item" : [ [ "abc", "abc" ] ] },
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BtreeCursor item_1 to indicate index use and the name of the index.

n displays 1 to indicate that one document matches the query.

nscanned displays 1 to indicate that MongoDB scanned one index entry.

However, nscannedObjects displays 0 to indicate that MongoDB did not need to scan any document. MongoDB used just the index, as verified by indexOnly.

indexOnly displays true to indicate that MongoDB used only the index to match and return the result of the query.

Multikey Index Explain Output

With a multikey index on an array field, MongoDB adds an index entry for each item in the array.

Consider following multi-key index on the ratings array on the survey collection:

db.survey.ensureIndex( { ratings: 1 } )

And consider the following query:

db.survey.find( { ratings: { $gte: 9 } } )

The query matches a single document:

{ "_id" : 1, "item" : "xyz", "ratings" : [ 8, 9, 10 ] }

To view how MongoDB uses the index for the query, use explain():

db.survey.find( { ratings: { $gte: 9 } } ).explain()

explain() returns the following output:

{
   "cursor" : "BtreeCursor ratings_1",
   "isMultiKey" : true,
   "n" : 1,
   "nscannedObjects" : 1,
   "nscanned" : 2,
   "nscannedObjectsAllPlans" : 1,
   "nscannedAllPlans" : 2,
   "scanAndOrder" : false,
   "indexOnly" : false,
   "nYields" : 0,
   "nChunkSkips" : 0,
   "millis" : 0,
   "ratings" : [ [ 9, Infinity ] ]
   "server" : "myMongoDB.local:27017",
   "filterSet" : false
}

cursor displays BtreeCursor ratings_1 to indicate index use and the name of the index.

isMultiKey displays true to indicate that the index is multi-key.

n displays 1 to indicate that one document matches the query.

nscanned displays 2 to indicate that MongoDB scanned two index entries.

However, nscannedObjects displays 1 since both keys refer to the same document and MongoDB de-duplicates.

See also

Analyze Query Performance, Query Optimization, Index Introduction, Query Plans

cursor.forEach()

Description

cursor.forEach(function)

Iterates the cursor to apply a JavaScript function to each document from the cursor.

The forEach() method has the following prototype form:

db.collection.find().forEach(<function>)

The forEach() method has the following parameter:

Parameter | Description
function | A JavaScript function to apply to each document from the cursor. The <function> signature includes a single argument that is passed the current document to process.

param JavaScript function:

A JavaScript function to apply to each document from the cursor. The <function> signature includes a single argument that is passed the current document to process.

Example

The following example invokes the forEach() method on the cursor returned by find() to print the name of each user in the collection:

db.users.find().forEach( function(myDoc) { print( "user: " + myDoc.name ); } );

See also

cursor.map() for similar functionality.

cursor.hasNext()

cursor.hasNext()

Returns:
Boolean.

cursor.hasNext() returns true if the cursor returned by the db.collection.find() query can iterate further to return more documents.

cursor.hint()

Definition

cursor.hint(index)

Call this method on a query to override MongoDB’s default index selection and query optimization process. Use db.collection.getIndexes() to return the list of current indexes on a collection.

The cursor.hint() method has the following parameter:

Parameter | Description
index | The index to “hint” or force MongoDB to use when performing the query. Specify the index either by the index name or by the index specification document.

param string, document index:

The index to “hint” or force MongoDB to use when performing the query. Specify the index either by the index name or by the index specification document.

Behavior

When an index filter exists for the query shape, MongoDB ignores the hint(). The explain.filterSet field of the explain() output indicates whether MongoDB applied an index filter for the query.

You cannot use hint() if the query includes a $text query expression.

Example

The following example returns all documents in the collection named users using the index on the age field.

db.users.find().hint( { age: 1 } )

You can also specify the index using the index name:

db.users.find().hint( "age_1" )

See also

Index Introduction

Indexing Tutorials

Query Plans

Index Filters

$hint

cursor.limit()

Definition

cursor.limit()

Use the limit() method on a cursor to specify the maximum number of documents the cursor will return. limit() is analogous to the LIMIT statement in a SQL database.

Note

You must apply limit() to the cursor before retrieving any documents from the database.

Use limit() to maximize performance and prevent MongoDB from returning more results than required for processing.

Behavior

Supported Values

The behavior of limit() is undefined for values less than -2³¹ and greater than 2³¹.

Negative Values

A limit() value of 0 (i.e. .limit(0)) is equivalent to setting no limit. A negative limit is similar to a positive limit, but a negative limit prevents the creation of a cursor such that only a single batch of results is returned. As such, with a negative limit, if the limited result set does not fit into a single batch, the number of documents received will be less than the limit.

cursor.map()

cursor.map(function)

Applies function to each document visited by the cursor and collects the return values from successive application into an array.

The cursor.map() method has the following parameter:

Parameter | Description
function | A function to apply to each document visited by the cursor.

param function function:

A function to apply to each document visited by the cursor.

Example

db.users.find().map( function(u) { return u.name; } );

See also

cursor.forEach() for similar functionality.

cursor.maxTimeMS()

Definition

New in version 2.6.

cursor.maxTimeMS(<time limit>)

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

The maxTimeMS() method has the following parameter:

Parameter | Description
milliseconds | Specifies a cumulative time limit in milliseconds for processing operations on the cursor.

param integer milliseconds:

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

Important

maxTimeMS() is not related to the NoCursorTimeout query flag. maxTimeMS() relates to processing time, while NoCursorTimeout relates to idle time. A cursor’s idle time does not contribute towards its processing time.

Behaviors

MongoDB targets operations for termination if the associated cursor exceeds its allotted time limit. MongoDB terminates operations that exceed their allotted time limit, using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

MongoDB does not count network latency towards a cursor’s time limit.

Queries that generate multiple batches of results continue to return batches until the cursor exceeds its allotted time limit.

Examples

Example

The following query specifies a time limit of 50 milliseconds:

db.collection.find({description: /August [0-9]+, 1969/}).maxTimeMS(50)

cursor.max()

Definition

cursor.max()

Specifies the exclusive upper bound for a specific index in order to constrain the results of find(). max() provides a way to specify an upper bound on compound key indexes.

The max() method has the following parameter:

Parameter | Description
indexBounds | The exclusive upper bound for the index keys.

param document indexBounds:

The exclusive upper bound for the index keys.

The indexBounds parameter has the following prototype form:

{ field1: <max value>, field2: <max value2> ... fieldN:<max valueN> }

The fields correspond to all the keys of a particular index in order. You can explicitly specify the particular index with the hint() method. Otherwise, mongod selects the index using the fields in the indexBounds; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous.

See also

min().

max() exists primarily to support the mongos (sharding) process, and is a shell wrapper around the query modifier $max.

Behavior

Interaction with Index Selection

Because max() requires an index on a field, and forces the query to use this index, you may prefer the $lt operator for the query if possible. Consider the following example:

db.products.find( { _id: 7 } ).max( { price: 1.39 } )

The query will use the index on the price field, even if the index on _id may be better.

Index Bounds

If you use max() with min() to specify a range, the index bounds specified in min() and max() must both refer to the keys of the same index.

max() without min()

The min and max operators indicate that the system should avoid normal query planning. Instead they construct an index scan where the index bounds are explicitly specified by the values given in min and max.

If one of the two boundaries is not specified, then the query plan will be an index scan that is unbounded on one side. This may degrade performance compared to a query containing neither operator, or one that uses both operators to more tightly constrain the index scan.

Example

This example assumes a collection named products that holds the following documents:

{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }

The collection has the following indexes:

{ "_id" : 1 }
{ "item" : 1, "type" : 1 }
{ "item" : 1, "type" : -1 }
{ "price" : 1 }

Using the ordering of { item: 1, type: 1 } index, max() limits the query to the documents that are below the bound of item equal to apple and type equal to jonagold:

db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )

The query returns the following documents:

{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }

If the query did not explicitly specify the index with the hint() method, it is ambiguous as to whether mongod would select the { item: 1, type: 1 } index ordering or the { item: 1, type: -1 } index ordering.

Using the ordering of the index { price: 1 }, max() limits the query to the documents that are below the index key bound of price equal to 1.99 and min() limits the query to the documents that are at or above the index key bound of price equal to 1.39:

db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )

The query returns the following documents:

{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }

cursor.min()

Definition

cursor.min()

Specifies the inclusive lower bound for a specific index in order to constrain the results of find(). min() provides a way to specify lower bounds on compound key indexes.

The min() method has the following parameter:

Parameter | Description
indexBounds | The inclusive lower bound for the index keys.

param document indexBounds:

The inclusive lower bound for the index keys.

The indexBounds parameter has the following prototype form:

{ field1: <min value>, field2: <min value2>, fieldN:<min valueN> }

The fields correspond to all the keys of a particular index in order. You can explicitly specify the particular index with the hint() method. Otherwise, MongoDB selects the index using the fields in the indexBounds; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous.

See also

max().

min() exists primarily to support the mongos process, and is a shell wrapper around the query modifier $min.

Behaviors

Interaction with Index Selection

Because min() requires an index on a field, and forces the query to use this index, you may prefer the $gte operator for the query if possible. Consider the following example:

db.products.find( { _id: 7 } ).min( { price: 1.39 } )

The query will use the index on the price field, even if the index on _id may be better.

Index Bounds

If you use min() with max() to specify a range, the index bounds specified in min() and max() must both refer to the keys of the same index.

min() without max()

The min and max operators indicate that the system should avoid normal query planning. Instead they construct an index scan where the index bounds are explicitly specified by the values given in min and max.

If one of the two boundaries is not specified, then the query plan will be an index scan that is unbounded on one side. This may degrade performance compared to a query containing neither operator, or one that uses both operators to more tightly constrain the index scan.

Example

This example assumes a collection named products that holds the following documents:

{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
{ "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }

The collection has the following indexes:

{ "_id" : 1 }
{ "item" : 1, "type" : 1 }
{ "item" : 1, "type" : -1 }
{ "price" : 1 }

Using the ordering of the { item: 1, type: 1 } index, min() limits the query to the documents that are at or above the index key bound of item equal to apple and type equal to jonagold, as in the following:

db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )

The query returns the following documents:

{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
{ "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
{ "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }

If the query did not explicitly specify the index with the hint() method, it is ambiguous as to whether mongod would select the { item: 1, type: 1 } index ordering or the { item: 1, type: -1 } index ordering.

Using the ordering of the index { price: 1 }, min() limits the query to the documents that are at or above the index key bound of price equal to 1.39 and max() limits the query to the documents that are below the index key bound of price equal to 1.99:

db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )

The query returns the following documents:

{ "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
{ "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
{ "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
{ "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
{ "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }

cursor.next()

cursor.next()

Returns:
The next document in the cursor returned by the db.collection.find() method. See cursor.hasNext() related functionality.

cursor.objsLeftInBatch()

cursor.objsLeftInBatch()

cursor.objsLeftInBatch() returns the number of documents remaining in the current batch.

The MongoDB instance returns response in batches. To retrieve all the documents from a cursor may require multiple batch responses from the MongoDB instance. When there are no more documents remaining in the current batch, the cursor will retrieve another batch to get more documents until the cursor exhausts.

cursor.readPref()

Definition

cursor.readPref(mode, tagSet)

Append readPref() to a cursor to control how the client routes the query to members of the replica set.

Parameter | Description
mode | One of the following read preference modes: primary, primaryPreferred, secondary, secondaryPreferred, or nearest
tagSet | Optional. A tag set used to specify custom read preference modes. For details, see Tag Sets.

param string mode:
| One of the following read preference modes: primary, primaryPreferred, secondary, secondaryPreferred, or nearest
param array tagSet:
| Optional. A tag set used to specify custom read preference modes. For details, see Tag Sets.

Note

You must apply readPref() to the cursor before retrieving any documents from the database.

cursor.showDiskLoc()

cursor.showDiskLoc()

Modifies the output of a query by adding a field $diskLoc to matching documents. $diskLoc contains disk location information and has the form:

"$diskLoc": {
  "file": <int>,
  "offset": <int>
}

cursor.showDiskLoc() method is a wrapper around $showDiskLoc.

Returns:
A modified cursor object that contains documents with appended information that describes the on-disk location of the document.

Example

The following operation appends the showDiskLoc() method to the db.collection.find() method in order to include in the matching documents the disk location information:

db.collection.find( { a: 1 } ).showDiskLoc()

The operation returns the following documents, which includes the $diskLoc field:

{
  "_id" : ObjectId("53908ccb18facd50a75bfbac"),
  "a" : 1,
  "b" : 1,
  "$diskLoc" : { "file" : 0, "offset" : 16195760 }
}
{
   "_id" : ObjectId("53908cd518facd50a75bfbad"),
   "a" : 1,
   "b" : 2,
   "$diskLoc" : { "file" : 0, "offset" : 16195824 }
}

The projection can also access the added field $diskLoc, as in the following example:

db.collection.find( { a: 1 }, { $diskLoc: 1 } ).showDiskLoc()

The operation returns just the _id field and the $diskLoc field in the matching documents:

{
  "_id" : ObjectId("53908ccb18facd50a75bfbac"),
  "$diskLoc" : { "file" : 0, "offset" : 16195760 }
}
{
   "_id" : ObjectId("53908cd518facd50a75bfbad"),
   "$diskLoc" : { "file" : 0, "offset" : 16195824 }
}

See also

$showDiskLoc for related functionality.

cursor.size()

cursor.size()

Returns:
A count of the number of documents that match the db.collection.find() query after applying any cursor.skip() and cursor.limit() methods.

cursor.skip()

cursor.skip()

Call the cursor.skip() method on a cursor to control where MongoDB begins returning results. This approach may be useful in implementing “paged” results.

Note

You must apply cursor.skip() to the cursor before retrieving any documents from the database.

Consider the following JavaScript function as an example of the skip function:

function printStudents(pageNumber, nPerPage) {
   print("Page: " + pageNumber);
   db.students.find().skip(pageNumber > 0 ? ((pageNumber-1)*nPerPage) : 0).limit(nPerPage).forEach( function(student) { print(student.name + "<p>"); } );
}

The cursor.skip() method is often expensive because it requires the server to walk from the beginning of the collection or index to get the offset or skip position before beginning to return results. As the offset (e.g. pageNumber above) increases, cursor.skip() will become slower and more CPU intensive. With larger collections, cursor.skip() may become IO bound.

Consider using range-based pagination for these kinds of tasks. That is, query for a range of objects, using logic within the application to determine the pagination rather than the database itself. This approach features better index utilization, if you do not need to easily jump to a specific page.

cursor.snapshot()

cursor.snapshot()

Append the snapshot() method to a cursor to toggle the “snapshot” mode. This ensures that the query will not return a document multiple times, even if intervening write operations result in a move of the document due to the growth in document size.

Warning

You must apply snapshot() to the cursor before retrieving any documents from the database.

You can only use snapshot() with unsharded collections.

The snapshot() does not guarantee isolation from insertion or deletions.

The snapshot() traverses the index on the _id field. As such, snapshot() cannot be used with sort() or hint().

Queries with results of less than 1 megabyte are effectively implicitly snapshotted.

cursor.sort()

Definition

cursor.sort(sort)

Specifies the order in which the query returns matching documents. You must apply sort() to the cursor before retrieving any documents from the database.

The sort() method has the following parameter:

Parameter | Description
sort | A document that defines the sort order of the result set.

param document sort:

A document that defines the sort order of the result set.

The sort parameter contains field and value pairs, in the following form:

{ field: value }

The sort document can specify ascending or descending sort on existing fields or sort on computed metadata.

Behaviors

Result Ordering

Unless you specify the sort() method or use the $near operator, MongoDB does not guarantee the order of query results.

Ascending/Descending Sort

Specify in the sort parameter the field or fields to sort by and a value of 1 or -1 to specify an ascending or descending sort respectively.

The following sample document specifies a descending sort by the age field and then an ascending sort by the posts field:

{ age : -1, posts: 1 }

When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:

MinKey (internal type)

Null

Numbers (ints, longs, doubles)

Symbol, String

Object

Array

BinData

ObjectId

Boolean

Date, Timestamp

Regular Expression

MaxKey (internal type)

MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.

The comparison treats a non-existent field as it would an empty BSON Object. As such, a sort on the a field in documents { } and { a: null } would treat the documents as equivalent in sort order.

With arrays, a less-than comparison or an ascending sort compares the smallest element of arrays, and a greater-than comparison or a descending sort compares the largest element of the arrays. As such, when comparing a field whose value is a single-element array (e.g. [ 1 ]) with non-array fields (e.g. 2), the comparison is between 1 and 2. A comparison of an empty array (e.g. [ ]) treats the empty array as less than null or a missing field.

MongoDB sorts BinData in the following order:

First, the length or size of the data.

Then, by the BSON one-byte subtype.

Finally, by the data, performing a byte-by-byte comparison.

Metadata Sort

Specify in the sort parameter a new field name for the computed metadata and specify the $meta expression as its value.

The following sample document specifies a descending sort by the "textScore" metadata:

{ score: { $meta: "textScore" } }

The specified metadata determines the sort order. For example, the "textScore" metadata sorts in descending order. See $meta for details.

Limit Results

The sort operation requires that the entire sort be able to complete within 32 megabytes.

When the sort operation consumes more than 32 megabytes, MongoDB returns an error. To avoid this error, either create an index to support the sort operation or use sort() in conjunction with limit(). The specified limit must result in a number of documents that fall within the 32 megabyte limit.

For example, if the following sort operation stocks_quotes exceeds the 32 megabyte limit:

db.stocks.find().sort( { ticker: 1, date: -1 } )

Either create an index to support the sort operation:

db.stocks.ensureIndex( { ticker: 1, date: -1 } )

Or use sort() in conjunction with limit():

db.stocks.find().sort( { ticker: 1, date: -1 } ).limit(100)

Interaction with Projection

When a set of results are both sorted and projected, the MongoDB query engine will always apply the sorting first.

Examples

A collection orders contain the following documents:

{ _id: 1, item: { category: "cake", type: "chiffon" }, amount: 10 }
{ _id: 2, item: { category: "cookies", type: "chocolate chip" }, amount: 50 }
{ _id: 3, item: { category: "cookies", type: "chocolate chip" }, amount: 15 }
{ _id: 4, item: { category: "cake", type: "lemon" }, amount: 30 }
{ _id: 5, item: { category: "cake", type: "carrot" }, amount: 20 }
{ _id: 6, item: { category: "brownies", type: "blondie" }, amount: 10 }

The following query, which returns all documents from the orders collection, does not specify a sort order:

db.orders.find()

The query returns the documents in indeterminate order:

{ "_id" : 1, "item" : { "category" : "cake", "type" : "chiffon" }, "amount" : 10 }
{ "_id" : 2, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 50 }
{ "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 }
{ "_id" : 4, "item" : { "category" : "cake", "type" : "lemon" }, "amount" : 30 }
{ "_id" : 5, "item" : { "category" : "cake", "type" : "carrot" }, "amount" : 20 }
{ "_id" : 6, "item" : { "category" : "brownies", "type" : "blondie" }, "amount" : 10 }

The following query specifies a sort on the amount field in descending order.

db.orders.find().sort( { amount: -1 } )

The query returns the following documents, in descending order of amount:

{ "_id" : 2, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 50 }
{ "_id" : 4, "item" : { "category" : "cake", "type" : "lemon" }, "amount" : 30 }
{ "_id" : 5, "item" : { "category" : "cake", "type" : "carrot" }, "amount" : 20 }
{ "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 }
{ "_id" : 1, "item" : { "category" : "cake", "type" : "chiffon" }, "amount" : 10 }
{ "_id" : 6, "item" : { "category" : "brownies", "type" : "blondie" }, "amount" : 10 }

The following query specifies the sort order using the fields from an embedded document item. The query sorts first by the category field in ascending order, and then within each category, by the type field in ascending order.

db.orders.find().sort( { "item.category": 1, "item.type": 1 } )

The query returns the following documents, ordered first by the category field, and within each category, by the type field:

{ "_id" : 6, "item" : { "category" : "brownies", "type" : "blondie" }, "amount" : 10 }
{ "_id" : 5, "item" : { "category" : "cake", "type" : "carrot" }, "amount" : 20 }
{ "_id" : 1, "item" : { "category" : "cake", "type" : "chiffon" }, "amount" : 10 }
{ "_id" : 4, "item" : { "category" : "cake", "type" : "lemon" }, "amount" : 30 }
{ "_id" : 2, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 50 }
{ "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 }

Return in Natural Order

The $natural parameter returns items according to their natural order within the database. This ordering is an internal implementation feature, and you should not rely on any particular structure within it.

Typically, the natural order reflects insertion order, except when documents relocate because of document growth due to updates or remove operations free up space which are then taken up by newly inserted documents.

Consider the sequence of insert operations to the trees collection:

db.trees.insert( { _id: 1, common_name: "oak", genus: "quercus" } )
db.trees.insert( { _id: 2, common_name: "chestnut", genus: "castanea" } )
db.trees.insert( { _id: 3, common_name: "maple", genus: "aceraceae" } )
db.trees.insert( { _id: 4, common_name: "birch", genus: "betula" } )

The following query returns the documents in the natural order:

db.trees.find().sort( { $natural: 1 } )

The documents return in the following order:

{ "_id" : 1, "common_name" : "oak", "genus" : "quercus" }
{ "_id" : 2, "common_name" : "chestnut", "genus" : "castanea" }
{ "_id" : 3, "common_name" : "maple", "genus" : "aceraceae" }
{ "_id" : 4, "common_name" : "birch", "genus" : "betula" }

Update a document such that the document outgrows its current allotted space:

db.trees.update(
   { _id: 1 },
   { $set: { famous_oaks: [ "Emancipation Oak", "Goethe Oak" ] } }
)

Rerun the query to returns the documents in natural order:

db.trees.find().sort( { $natural: 1 } )

The documents return in the following natural order:

{ "_id" : 2, "common_name" : "chestnut", "genus" : "castanea" }
{ "_id" : 3, "common_name" : "maple", "genus" : "aceraceae" }
{ "_id" : 4, "common_name" : "birch", "genus" : "betula" }
{ "_id" : 1, "common_name" : "oak", "genus" : "quercus", "famous_oaks" : [ "Emancipation Oak", "Goethe Oak" ] }

See also

$natural

cursor.toArray()

cursor.toArray()

The toArray() method returns an array that contains all the documents from a cursor. The method iterates completely the cursor, loading all the documents into RAM and exhausting the cursor.

Returns:
An array of documents.

Consider the following example that applies toArray() to the cursor returned from the find() method:

var allProductsArray = db.products.find().toArray();

if (allProductsArray.length > 0) { printjson (allProductsArray[0]); }

The variable allProductsArray holds the array of documents returned by toArray().

Database Methods

Name | Description
db.addUser() | Adds a user to a database, and allows administrators to configure the user’s privileges.
db.auth() | Authenticates a user to a database.
db.changeUserPassword() | Changes an existing user’s password.
db.cloneCollection() | Copies data directly between MongoDB instances. Wraps cloneCollection.
db.cloneDatabase() | Copies a database from a remote host to the current host. Wraps clone.
db.commandHelp() | Returns help information for a database command.
db.copyDatabase() | Copies a database to another database on the current host. Wraps copydb.
db.createCollection() | Creates a new collection. Commonly used to create a capped collection.
db.currentOp() | Reports the current in-progress operations.
db.dropDatabase() | Removes the current database.
db.eval() | Passes a JavaScript function to the mongod instance for server-side JavaScript evaluation.
db.fsyncLock() | Flushes writes to disk and locks the database to prevent write operations and assist backup operations. Wraps fsync.
db.fsyncUnlock() | Allows writes to continue on a database locked with db.fsyncLock().
db.getCollection() | Returns a collection object. Used to access collections with names that are not valid in the mongo shell.
db.getCollectionNames() | Lists all collections in the current database.
db.getLastError() | Checks and returns the status of the last operation. Wraps getLastError.
db.getLastErrorObj() | Returns the status document for the last operation. Wraps getLastError.
db.getMongo() | Returns the Mongo() connection object for the current connection.
db.getName() | Returns the name of the current database.
db.getPrevError() | Returns a status document containing all errors since the last error reset. Wraps getPrevError.
db.getProfilingLevel() | Returns the current profiling level for database operations.
db.getProfilingStatus() | Returns a document that reflects the current profiling level and the profiling threshold.
db.getReplicationInfo() | Returns a document with replication statistics.
db.getSiblingDB() | Provides access to the specified database.
db.help() | Displays descriptions of common db object methods.
db.hostInfo() | Returns a document with information about the system MongoDB runs on. Wraps hostInfo
db.isMaster() | Returns a document that reports the state of the replica set.
db.killOp() | Terminates a specified operation.
db.listCommands() | Displays a list of common database commands.
db.loadServerScripts() | Loads all scripts in the system.js collection for the current database into the shell session.
db.logout() | Ends an authenticated session.
db.printCollectionStats() | Prints statistics from every collection. Wraps db.collection.stats().
db.printReplicationInfo() | Prints a report of the status of the replica set from the perspective of the primary.
db.printShardingStatus() | Prints a report of the sharding configuration and the chunk ranges.
db.printSlaveReplicationInfo() | Prints a report of the status of the replica set from the perspective of the secondaries.
db.removeUser() | Removes a user from a database.
db.repairDatabase() | Runs a repair routine on the current database.
db.resetError() | Resets the error message returned by db.getPrevError() and getPrevError.
db.runCommand() | Runs a database command.
db.serverBuildInfo() | Returns a document that displays the compilation parameters for the mongod instance. Wraps buildinfo.
db.serverCmdLineOpts() | Returns a document with information about the runtime used to start the MongoDB instance. Wraps getCmdLineOpts.
db.serverStatus() | Returns a document that provides an overview of the state of the database process.
db.setProfilingLevel() | Modifies the current level of database profiling.
db.shutdownServer() | Shuts down the current mongod or mongos process cleanly and safely.
db.stats() | Returns a document that reports on the state of the current database.
db.version() | Returns the version of the mongod instance.
db.upgradeCheck() | Performs a preliminary check for upgrade preparedness for a specific database or collection.
db.upgradeCheckAllDBs() | Performs a preliminary check for upgrade preparedness for all databases and collections.

db.addUser()

db.auth()

db.changeUserPassword()

db.cloneCollection()

db.cloneDatabase()

db.commandHelp()

db.copyDatabase()

db.createCollection()

db.currentOp()

db.dropDatabase()

db.eval()

db.fsyncLock()

db.fsyncUnlock()

db.getCollection()

db.getCollectionNames()

db.getLastError()

db.getLastErrorObj()

db.getMongo()

db.getName()

db.getPrevError()

db.getProfilingLevel()

db.getProfilingStatus()

db.getReplicationInfo()

db.getSiblingDB()

db.help()

db.hostInfo()

db.isMaster()

db.killOp()

db.listCommands()

db.loadServerScripts()

db.logout()

db.printCollectionStats()

db.printReplicationInfo()

db.printShardingStatus()

db.printSlaveReplicationInfo()

db.removeUser()

db.repairDatabase()

db.resetError()

db.runCommand()

db.serverBuildInfo()

db.serverCmdLineOpts()

db.serverStatus()

db.setProfilingLevel()

db.shutdownServer()

db.stats()

db.version()

db.upgradeCheck()

db.upgradeCheckAllDBs()

db.addUser()

Deprecated since version 2.6: Use db.createUser() and db.updateUser() instead of db.addUser() to add users to MongoDB.

In 2.6, MongoDB introduced a new model for user credentials and privileges, as described in Security Introduction. To use db.addUser() on MongoDB 2.4, see db.addUser() in the version 2.4 of the MongoDB Manual [http://docs.mongodb.org/v2.4/reference/method/db.addUser].

Definition

db.addUser(document)

Adds a new user on the database where you run the method. The db.addUser() method takes a user document as its argument:

db.addUser(<user document>)

Specify a document that resembles the following as an argument to db.addUser():

{ user: "<name>",
  pwd: "<cleartext password>",
  customData: { <any information> },
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  writeConcern: { <write concern> }
}

The db.addUser() user document has the following fields:

Field | Description
pwd | The user’s password. The pwd field is not required if you run db.addUser() on the $external database to create users who have credentials stored externally to MongoDB.
customData | Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
roles | The roles granted to the user. Can specify an empty array [] to create users without roles.
writeConcern | Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.
user | The name of the new user.

field string pwd:
| The user’s password. The pwd field is not required if you run db.addUser() on the $external database to create users who have credentials stored externally to MongoDB.
field document customData:
| Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
field array roles:
| The roles granted to the user. Can specify an empty array [] to create users without roles.
field document writeConcern:
| Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.
field string user:
| The name of the new user.

Users created on the $external database should have credentials stored externally to MongoDB, as, for example, with MongoDB Enterprise installations that use Kerberos.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.addUser() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

Considerations

The db.addUser() method returns a duplicate user error if the user exists.

When interacting with 2.6 and later MongoDB instances, db.addUser() sends unencrypted passwords. To encrypt the password in transit use SSL.

In the 2.6 version of the shell, db.addUser() is backwards compatible with both the 2.4 version of db.addUser() [http://docs.mongodb.org/v2.4/reference/method/db.addUser] and the 2.2 version of db.addUser() [http://docs.mongodb.org/v2.2/reference/method/db.addUser]. In 2.6, for backwards compatibility db.addUser() creates users that approximate the privileges available in previous versions of MongoDB.

Example

The following db.addUser() method creates a user Carlos on the database where the command runs. The command gives Carlos the clusterAdmin and readAnyDatabase roles on the admin database and the readWrite role on the current database:

{ user: "Carlos",
  pwd: "cleartext password",
  customData: { employeeId: 12345 },
  roles: [
    { role: "clusterAdmin", db: "admin" },
    { role: "readAnyDatabase", db: "admin" },
    "readWrite"
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
}

db.auth()

Definition

db.auth(username, password)

Allows a user to authenticate to the database from within the shell.

Parameter | Description
username | Specifies an existing username with access privileges for this database.
password | Specifies the corresponding password.

param string username:
| Specifies an existing username with access privileges for this database.
param string password:
| Specifies the corresponding password.

Alternatively, you can use mongo --username, --password, and --authenticationMechanism to specify authentication credentials.

--authenticationMechanism supports additional mechanisms not available when using db.auth().

Note

The mongo shell excludes all db.auth() operations from the saved history.

Returns:
db.auth() returns 0 when authentication is not successful, and 1 when the operation is successful.

db.changeUserPassword()

Definition

db.changeUserPassword(username, password)

Updates a user’s password.

Parameter | Description
username | Specifies an existing username with access privileges for this database.
password | Specifies the corresponding password.

param string username:
| Specifies an existing username with access privileges for this database.
param string password:
| Specifies the corresponding password.

Example

The following operation changes the reporting user’s password to SOh3TbYhx8ypJPxmt1oOfL:

db.changeUserPassword("reporting", "SOh3TbYhx8ypJPxmt1oOfL")

db.cloneCollection()

Definition

db.cloneCollection(from, collection, query)

Copies data directly between MongoDB instances. The db.cloneCollection() wraps the cloneCollection database command and accepts the following arguments:

Parameter
Description

from
Host name of the MongoDB instance that holds the collection to copy.

collection
The collection in the MongoDB instance that you want to copy. db.cloneCollection() will only copy the collection with this name from database of the same name as the current database the remote MongoDB instance. If you want to copy a collection from a different database name you must use the cloneCollection directly.

query
Optional. A standard query document that limits the documents copied as part of the db.cloneCollection() operation. All query selectors available to the find() are available here.

param string from:

Host name of the MongoDB instance that holds the collection to copy.

param string collection:

The collection in the MongoDB instance that you want to copy. db.cloneCollection() will only copy the collection with this name from database of the same name as the current database the remote MongoDB instance. If you want to copy a collection from a different database name you must use the cloneCollection directly.

param document query:

Optional. A standard query document that limits the documents copied as part of the db.cloneCollection() operation. All query selectors available to the find() are available here.

db.cloneCollection() does not allow you to clone a collection through a mongos. You must connect directly to the mongod instance.

db.cloneDatabase()

Definition

db.cloneDatabase("hostname")

Copies a remote database to the current database. The command assumes that the remote database has the same name as the current database.

Parameter | Description
hostname | The hostname of the database to copy.

param string hostname:

The hostname of the database to copy.

This method provides a wrapper around the MongoDB database command “clone.” The copydb database command provides related functionality.

Example

To clone a database named importdb on a host named hostname, issue the following:

use importdb
db.cloneDatabase("hostname")

New databases are implicitly created, so the current host does not need to have a database named importdb for this command to succeed.

db.commandHelp()

Description

db.commandHelp(command)

Displays help text for the specified database command. See the Database Commands.

The db.commandHelp() method has the following parameter:

Parameter | Description
command | The name of a database command.

param string command:

The name of a database command.

db.copyDatabase()

Definition

db.copyDatabase(fromdb, todb, fromhost, username, password)

Copies a database from a remote host to the current host or copies a database to another database within the current host. db.copyDatabase() wraps the copydb command and takes the following arguments:

Parameter | Description
fromdb | The name of the source database.
todb | The name of the destination database.
fromhost | Optional. The name of the source database host. Omit the hostname to copy from one database to another on the same server.
username | Optional. The username credentials on the fromhost for authentication and authorization.
password | Optional. The password on the fromhost for authentication and authorization. The method does not transmit the password in plaintext.

param string fromdb:
| The name of the source database.
param string todb:
| The name of the destination database.
param string fromhost:
| Optional. The name of the source database host. Omit the hostname to copy from one database to another on the same server.
param string username:
| Optional. The username credentials on the fromhost for authentication and authorization.
param string password:
| Optional. The password on the fromhost for authentication and authorization. The method does not transmit the password in plaintext.

Behavior

Be aware of the following properties of db.copyDatabase():

db.copyDatabase() runs on the destination mongod instance, i.e. the host receiving the copied data.

If the destination mongod has authorization enabled, db.copyDatabase() must specify the credentials of a user present in the source database who has the privileges described in Required Access.

db.copyDatabase() creates the target database if it does not exist.

db.copyDatabase() requires enough free disk space on the host instance for the copied database. Use the db.stats() operation to check the size of the database on the source mongod instance.

db.copyDatabase() and clone do not produce point-in-time snapshots of the source database. Write traffic to the source or destination database during the copy process will result in divergent data sets.

db.copyDatabase() does not lock the destination server during its operation, so the copy will occasionally yield to allow other operations to complete.

Required Access

Changed in version 2.6.

The copydb command requires the following authorization on the target and source databases.

Source Database (fromdb)

Source is non-admin Database

If the source database is a non-admin database, you must have privileges that specify find action on the source database, and find action on the system.js collection in the source database. For example:

{ resource: { db: "mySourceDB", collection: "" }, actions: [ "find" ] }
{ resource: { db: "mySourceDB", collection: "system.js" }, actions: [ "find" ] }

If the source database is on a remote server, you also need the find action on the system.indexes and system.namespaces collections in the source database; e.g.

{ resource: { db: "mySourceDB", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "mySourceDB", collection: "system.namespaces" }, actions: [ "find" ] }

Source is admin Database

If the source database is the admin database, you must have privileges that specify find action on the admin database, and find action on the system.js, system.users, system.roles, and system.version collections in the admin database. For example:

{ resource: { db: "admin", collection: "" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.js" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.roles" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find" ] }

If the source database is on a remote server, the you also need the find action on the system.indexes and system.namespaces collections in the admin database; e.g.

{ resource: { db: "admin", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.namespaces" }, actions: [ "find" ] }

Source Database is on a Remote Server

If copying from a remote server and the remote server has authentication enabled, you must authenticate to the remote host as a user with the proper authorization. See Authentication.

Target Database (todb)

Copy from non-admin Database

If the source database is not the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js collection in the target database. For example:

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] }
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] }

Copy from admin Database

If the source database is the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js, system.users, system.roles, and system.version collections in the target database. For example:

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] },
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.users" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.roles" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.version" }, actions: [ "insert" ] }

Authentication

If copying from a remote server and the remote server has authentication enabled, then you must include the <username> and <password>. The method does not transmit the password in plaintext.

Example

To copy a database named records into a database named archive_records, use the following invocation of db.copyDatabase():

db.copyDatabase('records', 'archive_records')

See also

clone

db.createCollection()

Definition

db.createCollection(name, options)

Creates a new collection explicitly.

Because MongoDB creates a collection implicitly when the collection is first referenced in a command, this method is used primarily for creating new capped collections. This is also used to pre-allocate space for an ordinary collection.

The db.createCollection() method has the following prototype form:

db.createCollection(name, {capped: <boolean>, autoIndexId: <boolean>, size: <number>, max: <number>} )

The db.createCollection() method has the following parameters:

Parameter | Description
name | The name of the collection to create.
options | Optional. Configuration options for creating a capped collection or for preallocating space in a new collection.

param string name:
| The name of the collection to create.
param document options:
| Optional. Configuration options for creating a capped collection or for preallocating space in a new collection.

The options document creates a capped collection or preallocates space in a new ordinary collection. The options document contains the following fields:

Field
Description

capped
Optional. Enables a capped collection. To create a capped collection, specify true. If you specify true, you must also set a maximum size in the size field.

autoIndexId

Optional. Specify false to disable the automatic creation of an index on the _id field. Before 2.2, the default value for autoIndexId was false. See _id Fields and Indexes on Capped Collections for more information.

Do not set autoIndexId to true for replicated collections.

size
Optional. Specifies a maximum size in bytes for a capped collection. The size field is required for capped collections, and ignored for other collections.

max
Optional. The maximum number of documents allowed in the capped collection. The size limit takes precedence over this limit. If a capped collection reaches its maximum size before it reaches the maximum number of documents, MongoDB removes old documents. If you prefer to use this limit, ensure that the size limit, which is required, is sufficient to contain the documents limit.

usePowerOf2Sizes

Optional. .. versionadded:: 2.6

usePowerOf2Sizes became an option to db.createCollection() when usePowerOf2Sizes became the default allocation strategy for all new collections by default.

Set to false to disable the usePowerOf2Sizes allocation strategy for this collection. Defaults to true unless the newCollectionsUsePowerOf2Sizes parameter is set to false.

field Boolean capped:

Optional. Enables a capped collection. To create a capped collection, specify true. If you specify true, you must also set a maximum size in the size field.

field Boolean autoIndexId:

Optional. Specify false to disable the automatic creation of an index on the _id field. Before 2.2, the default value for autoIndexId was false. See _id Fields and Indexes on Capped Collections for more information.

Do not set autoIndexId to true for replicated collections.

field number size:

Optional. Specifies a maximum size in bytes for a capped collection. The size field is required for capped collections, and ignored for other collections.

field number max:

Optional. The maximum number of documents allowed in the capped collection. The size limit takes precedence over this limit. If a capped collection reaches its maximum size before it reaches the maximum number of documents, MongoDB removes old documents. If you prefer to use this limit, ensure that the size limit, which is required, is sufficient to contain the documents limit.

field boolean usePowerOf2Sizes:

Optional. .. versionadded:: 2.6

usePowerOf2Sizes became an option to db.createCollection() when usePowerOf2Sizes became the default allocation strategy for all new collections by default.

Set to false to disable the usePowerOf2Sizes allocation strategy for this collection. Defaults to true unless the newCollectionsUsePowerOf2Sizes parameter is set to false.

Example

The following example creates a capped collection. Capped collections have maximum size or document counts that prevent them from growing beyond maximum thresholds. All capped collections must specify a maximum size and may also specify a maximum document count. MongoDB removes older documents if a collection reaches the maximum size limit before it reaches the maximum document count. Consider the following example:

db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

This command creates a collection named log with a maximum size of 5 megabytes and a maximum of 5000 documents.

The following command simply pre-allocates a 2-gigabyte, uncapped collection named people:

db.createCollection("people", { size: 2147483648 } )

This command provides a wrapper around the database command create. See Capped Collections for more information about capped collections.

db.currentOp()

Definition

db.currentOp()

Returns a document that contains information on in-progress operations for the database instance.

db.currentOp() method has the following form:

db.currentOp(<operations>)

The db.currentOp() method can take the following optional argument:

Parameter
Description

operations

Optional. Specifies the operations to report on. Can pass either a boolean or a document.

Specify true to include operations on idle connections and system operations. Specify a document with query conditions to report only on operations that match the conditions. See Behavior for details.

param boolean or document operations:

Optional. Specifies the operations to report on. Can pass either a boolean or a document.

Specify true to include operations on idle connections and system operations. Specify a document with query conditions to report only on operations that match the conditions. See Behavior for details.

Behavior

If you pass in true to db.currentOp(), the method returns information on all operations, including operations on idle connections and system operations.

db.currentOp(true)

Passing in true is equivalent to passing in a query document of { '$all': true }.

If you pass a query document to db.currentOp(), the output returns information only for the current operations that match the query. You can query on the Output Fields. See Examples.

You can also specify { '$all': true } query document to return information on all in-progress operations, including operations on idle connections and system operations. If you specify in the query document other conditions as well as '$all': true, only the '$all': true applies.

Access Control

On systems running with authorization, a user must have access that includes the inprog action. For example, see Create a Role to Manage Current Operations.

Examples

The following examples use the db.currentOp() method with various query documents to filter the output.

Write Operations Waiting for a Lock

The following example returns information on all write operations that are waiting for a lock:

db.currentOp(
   {
     "waitingForLock" : true,
     $or: [
        { "op" : { "$in" : [ "insert", "update", "remove" ] } },
        { "query.update": { $exists: true } },
        { "query.insert": { $exists: true } },
        { "query.remove": { $exists: true } }
    ]
   }
)

Active Operations with no Yields

The following example returns information on all active running operations that have never yielded:

db.currentOp(
   {
     "active" : true,
     "numYields" : 0,
     "waitingForLock" : false
   }
)

Active Operations on a Specific Database

The following example returns information on all active operations for database db1 that have been running longer than 3 seconds:

db.currentOp(
   {
     "active" : true,
     "secs_running" : { "$gt" : 3 },
     "ns" : /^db1./
   }
)

Active Indexing Operations

The following example returns information on index creation operations:

db.currentOp(
    {
      $or: [
        { op: "query", "query.createIndexes": { $exists: true } },
        { op: "insert", ns: /\.system\.indexes\b/ }
      ]
    }
)

Output Example

The following is an example of db.currentOp() output.

{
  "inprog": [
       {
         "opid" : <number>,
         "active" : <boolean>,
         "secs_running" : <NumberLong()>,
         "microsecs_running" : <number>,
         "op" : <string>,
         "ns" : <string>,
         "query" : <document>,
         "insert" : <document>,
         "planSummary": <string>,
         "client" : <string>,
         "desc" : <string>,
         "threadId" : <string>,
         "connectionId" : <number>,
         "locks" : {
             "^" : <string>,
             "^local" : <string>,
             "^<database>" : <string>
         },
         "waitingForLock" : <boolean>,
         "msg": <string>,
         "progress" : {
             "done" : <number>,
             "total" : <number>
         },
         "killPending" : <boolean>,
         "numYields" : <number>,
         "lockStats" : {
             "timeLockedMicros" : {
                 "R" : <NumberLong()>,
                 "W" : <NumberLong()>,
                 "r" : <NumberLong()>,
                 "w" : <NumberLong()>
             },
             "timeAcquiringMicros" : {
                 "R" : <NumberLong()>,
                 "W" : <NumberLong()>,
                 "r" : <NumberLong()>,
                 "w" : <NumberLong()>
             }
         }
       },
       ...
   ]
}

Output Fields

currentOp.opid

The identifier for the operation. You can pass this value to db.killOp() in the mongo shell to terminate the operation.

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

currentOp.active

A boolean value specifying whether the operation has started. Value is true if the operation has started or false if the operation is queued and waiting for a lock to run. active may be true even if the operation has yielded to another operation.

currentOp.secs_running

The duration of the operation in seconds. MongoDB calculates this value by subtracting the current time from the start time of the operation.

Only appears if the operation is running, (i.e. if active is true).

currentOp.microsecs_running

New in version 2.6.

The duration of the operation in microseconds. MongoDB calculates this value by subtracting the current time from the start time of the operation.

Only appears if the operation is running, (i.e. if active is true).

currentOp.op

A string that identifies the type of operation. The possible values are:

"none"

"update"

"insert"

"query"

"getmore"

"remove"

"killcursors"

The "query" type includes operations that use the insert, update, and delete commands. Write operations that do not use the aforementioned write commands will show with the appropriate "insert", "update", or "remove" value.

currentOp.ns

The namespace the operation targets. A namespace consists of the database name and the collection name concatenated with a dot (.); i.e., "<database>.<collection>".

currentOp.insert

Contains the document to be inserted for operations with op value of "insert". Only appears for operations with op value "insert".

Insert operations such as db.collection.insert() that use the insert command will have op value of "query".

currentOp.query

A document containing information on current operation if op value is not "insert". query does not appear for op of type "insert".

Write operations that use the insert, update, and delete commands have op value of "query" and the corresponding query contains information on these operations.

For example, the following query field contains information for an update operation:

"query" : {
            "update" : "grades",
            "updates" : [
               {
                  "q" : {
                     "x" : {
                        "$gt" : 70
                     }
                  },
                  "u" : {
                     "$set" : {
                        "y" : 1
                     }
                  },
                  "multi" : true,
                  "upsert" : false
               }
            ],
            "ordered" : true
         }

The document can be empty for op types such as "getmore".

currentOp.planSummary

A string that contains the query plan to help debug slow queries.

currentOp.client

The IP address (or hostname) and the ephemeral port of the client connection where the operation originates. If your inprog array has operations from many different clients, use this string to relate operations to clients.

For some commands, including findAndModify and db.eval(), the client will be 0.0.0.0:0, rather than an actual client.

currentOp.desc

A description of the client. This string includes the connectionId.

currentOp.threadId

An identifier for the thread that services the operation and its connection.

currentOp.connectionId

An identifier for the connection where the operation originated.

currentOp.locks

New in version 2.2.

The locks document reports by databases the types of locks the operation currently holds. The possible lock types are:

R represents the global read lock,

W represents the global write lock,

r represents the database specific read lock, and

w represents the database specific write lock.

currentOp.locks.^

^ reports on the use of the global lock for the mongod instance. All operations must hold the global lock for some phases of operation.

currentOp.locks.^local

^local reports on the lock for the local database. MongoDB uses the local database for a number of operations, but the most frequent use of the local database is for the oplog used in replication.

currentOp.locks.^<database>

locks.^<database> reports on the lock state for the database that this operation targets.

currentOp.waitingForLock

Returns a boolean value. waitingForLock is true if the operation is waiting for a lock and false if the operation has the required lock.

currentOp.msg

The msg provides a message that describes the status and progress of the operation. In the case of indexing or mapReduce operations, the field reports the completion percentage.

currentOp.progress

Reports on the progress of mapReduce or indexing operations. The progress fields corresponds to the completion percentage in the msg field. The progress specifies the following information:

currentOp.progress.done

Reports the number completed.

currentOp.progress.total

Reports the total number.

currentOp.killPending

Returns true if the operation is currently flagged for termination. When the operation encounters its next safe termination point, the operation will terminate.

currentOp.numYields

numYields is a counter that reports the number of times the operation has yielded to allow other operations to complete.

Typically, operations yield when they need access to data that MongoDB has not yet fully read into memory. This allows other operations that have data in memory to complete quickly while MongoDB reads in data for the yielding operation.

currentOp.lockStats

New in version 2.2.

The lockStats document reflects the amount of time the operation has spent both acquiring and holding locks. lockStats reports data on a per-lock type, with the following possible lock types:

R represents the global read lock,

W represents the global write lock,

r represents the database specific read lock, and

w represents the database specific write lock.

currentOp.timeLockedMicros

The timeLockedMicros document reports the amount of time the operation has spent holding a specific lock.

For operations that require more than one lock, like those that lock the local database to update the oplog, then the values in this document can be longer than this value may be longer than the total length of the operation (i.e. secs_running.)

currentOp.timeLockedMicros.R

Reports the amount of time in microseconds the operation has held the global read lock.

currentOp.timeLockedMicros.W

Reports the amount of time in microseconds the operation has held the global write lock.

currentOp.timeLockedMicros.r

Reports the amount of time in microseconds the operation has held the database specific read lock.

currentOp.timeLockedMicros.w

Reports the amount of time in microseconds the operation has held the database specific write lock.

currentOp.timeAcquiringMicros

The timeAcquiringMicros document reports the amount of time the operation has spent waiting to acquire a specific lock.

currentOp.timeAcquiringMicros.R

Reports the mount of time in microseconds the operation has waited for the global read lock.

currentOp.timeAcquiringMicros.W

Reports the mount of time in microseconds the operation has waited for the global write lock.

currentOp.timeAcquiringMicros.r

Reports the mount of time in microseconds the operation has waited for the database specific read lock.

currentOp.timeAcquiringMicros.w

Reports the mount of time in microseconds the operation has waited for the database specific write lock.

db.dropDatabase()

db.dropDatabase()

Removes the current database. Does not change the current database, so the insertion of any documents in this database will allocate a fresh set of data files.

Changed in version 2.6: This command does not delete the users associated with the current database. To drop the associated users, run the dropAllUsersFromDatabase command in the database you are deleting.

See also

dropDatabase

db.eval()

Definition

db.eval(function, arguments)

Provides the ability to run JavaScript code on the MongoDB server.

The helper db.eval() in the mongo shell wraps the eval command. Therefore, the helper method shares the characteristics and behavior of the underlying command with one exception: db.eval() method does not support the nolock option.

The method accepts the following parameters:

Parameter | Description
function | A JavaScript function to execute.
arguments | Optional. A list of arguments to pass to the JavaScript function. Omit if the function does not take arguments.

param JavaScript function function:
| A JavaScript function to execute.
param list arguments:
| Optional. A list of arguments to pass to the JavaScript function. Omit if the function does not take arguments.

The JavaScript function need not take any arguments, as in the first example, or may optionally take arguments as in the second:

function () {
  // ...
}

function (arg1, arg2) {
   // ...
}

Behavior

Write Lock

By default, db.eval() takes a global write lock while evaluating the JavaScript function. As a result, db.eval() blocks all other read and write operations to the database while the db.eval() operation runs.

To prevent the taking of the global write lock while evaluating the JavaScript code, use the eval command with nolock set to true. nolock does not impact whether the operations within the JavaScript code take write locks.

For long running db.eval() operation, consider using either the eval command with nolock: true or using other server side code execution options.

Sharded Data

You can not use db.eval() with sharded collections. In general, you should avoid using db.eval() in sharded clusters; nevertheless, it is possible to use db.eval() with non-sharded collections and databases stored in a sharded cluster.

Access Control

Changed in version 2.6.

If authorization is enabled, you must have access to all actions on all resources in order to run db.eval(). Providing such access is not recommended, but if your organization requires a user to run db.eval(), create a role that grants anyAction on anyResource. Do not assign this role to any other user.

JavaScript Engine

Changed in version 2.4.

The V8 JavaScript engine, which became the default in 2.4, allows multiple JavaScript operations to execute at the same time. Prior to 2.4, db.eval() executed in a single thread.

Examples

The following is an example of the db.eval() method:

db.eval( function(name, incAmount) {
            var doc = db.myCollection.findOne( { name : name } );

            doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };

            doc.num++;
            doc.total += incAmount;
            doc.avg = doc.total / doc.num;

            db.myCollection.save( doc );
            return doc;
         },
         "eliot", 5 );

The db in the function refers to the current database.

"eliot" is the argument passed to the function, and corresponds to the name argument.

5 is an argument to the function and corresponds to the incAmount field.

If you want to use the server’s interpreter, you must run db.eval(). Otherwise, the mongo shell’s JavaScript interpreter evaluates functions entered directly into the shell.

If an error occurs, db.eval() throws an exception. The following is an example of an invalid function that uses the variable x without declaring it as an argument:

db.eval( function() { return x + x; }, 3 );

The statement results in the following exception:

{
   "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ",
   "code" : 16722,
   "ok" : 0
}

See also

Server-side JavaScript

db.fsyncLock()

db.fsyncLock()

Forces the mongod to flush all pending write operations to the disk and locks the entire mongod instance to prevent additional writes until the user releases the lock with the db.fsyncUnlock() command. db.fsyncLock() is an administrative command.

This command provides a simple wrapper around a fsync database command with the following syntax:

{ fsync: 1, lock: true }

This function locks the database and create a window for backup operations.

Important

db.fsyncLock() may block reads, including those necessary to verify authentication. Such reads are necessary to establish new connections to a mongod that enforces authorization checks.

Warning

When calling db.fsyncLock(), ensure that the connection is kept open to allow a subsequent call to db.fsyncUnlock().

Closing the connection may make it difficult to release the lock.

db.fsyncUnlock()

db.fsyncUnlock()

Unlocks a mongod instance to allow writes and reverses the operation of a db.fsyncLock() operation. Typically you will use db.fsyncUnlock() following a database backup operation.

db.fsyncUnlock() is an administrative command.

db.getCollection()

Description

db.getCollection(name)

Returns a collection name. This is useful for a collection whose name might interact with the shell itself, such names that begin with _ or that mirror the database commands.

The db.getCollection() method has the following parameter:

Parameter | Description
name | The name of the collection.

param string name:

The name of the collection.

db.getCollectionNames()

db.getCollectionNames()

Returns:
An array containing all collections in the existing database.

db.getLastError()

db.getLastError()

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations, eliminating the need for a separate db.getLastError() method. Write methods now return the status of the write operation, including error information.

In previous versions, clients typically used the db.getLastError() method in combination with the write operations to ensure that the write succeeds.

Returns:
The last error message string.

Sets the level of write concern for confirming the success of write operations.

See

getLastError and Write Concern Reference for all options, Write Concern for a conceptual overview, Write Operations for information about all write operations in MongoDB.

db.getLastErrorObj()

db.getLastErrorObj()

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations, eliminating the need for a separate db.getLastError() method. Write methods now return the status of the write operation, including error information.

In previous versions, clients typically used the db.getLastError() method in combination with the write operations to ensure that the write succeeds.

Returns:
A full document with status information.

See also

Write Concern, Write Concern Reference, and Replica Acknowledged.

db.getMongo()

db.getMongo()

Returns:
The current database connection.

db.getMongo() runs when the shell initiates. Use this command to test that the mongo shell has a connection to the proper database instance.

db.getName()

db.getName()

Returns:
the current database name.

db.getPrevError()

db.getPrevError()

Returns:
A status document, containing the errors.

Deprecated since version 1.6.

This output reports all errors since the last time the database received a resetError (also db.resetError()) command.

This method provides a wrapper around the getPrevError command.

db.getProfilingLevel()

db.getProfilingLevel()

This method provides a wrapper around the database command “profile” and returns the current profiling level.

Deprecated since version 1.8.4: Use db.getProfilingStatus() for related functionality.

db.getProfilingStatus()

db.getProfilingStatus()

Returns:
The current profile level and slowOpThresholdMs setting.

db.getReplicationInfo()

Definition

db.getReplicationInfo()

Returns:
A document with the status of the replica set, using data polled from the oplog. Use this output when diagnosing issues with replication.

Output

db.getReplicationInfo.logSizeMB

Returns the total size of the oplog in megabytes. This refers to the total amount of space allocated to the oplog rather than the current size of operations stored in the oplog.

db.getReplicationInfo.usedMB

Returns the total amount of space used by the oplog in megabytes. This refers to the total amount of space currently used by operations stored in the oplog rather than the total amount of space allocated.

db.getReplicationInfo.errmsg

Returns an error message if there are no entries in the oplog.

db.getReplicationInfo.oplogMainRowCount

Only present when there are no entries in the oplog. Reports a the number of items or rows in the oplog (e.g. 0).

db.getReplicationInfo.timeDiff

Returns the difference between the first and last operation in the oplog, represented in seconds.

Only present if there are entries in the oplog.

db.getReplicationInfo.timeDiffHours

Returns the difference between the first and last operation in the oplog, rounded and represented in hours.

Only present if there are entries in the oplog.

db.getReplicationInfo.tFirst

Returns a time stamp for the first (i.e. earliest) operation in the oplog. Compare this value to the last write operation issued against the server.

Only present if there are entries in the oplog.

db.getReplicationInfo.tLast

Returns a time stamp for the last (i.e. latest) operation in the oplog. Compare this value to the last write operation issued against the server.

Only present if there are entries in the oplog.

db.getReplicationInfo.now

Returns a time stamp that reflects reflecting the current time. The shell process generates this value, and the datum may differ slightly from the server time if you’re connecting from a remote host as a result. Equivalent to Date().

Only present if there are entries in the oplog.

db.getSiblingDB()

Definition

db.getSiblingDB(<database>)

Parameter | Description
database | The name of a MongoDB database.

param string database:

The name of a MongoDB database.

Returns:
A database object.

Used to return another database without modifying the db variable in the shell environment.

Example

You can use db.getSiblingDB() as an alternative to the use <database> helper. This is particularly useful when writing scripts using the mongo shell where the use helper is not available. Consider the following sequence of operations:

db = db.getSiblingDB('users')
db.active.count()

This operation sets the db object to point to the database named users, and then returns a count of the collection named active. You can create multiple db objects, that refer to different databases, as in the following sequence of operations:

users = db.getSiblingDB('users')
records = db.getSiblingDB('records')

users.active.count()
users.active.findOne()

records.requests.count()
records.requests.findOne()

This operation creates two db objects referring to different databases (i.e. users and records) and then returns a count and an example document from one collection in that database (i.e. active and requests respectively.)

db.help()

db.help()

Returns:
Text output listing common methods on the db object.

db.hostInfo()

db.hostInfo()

New in version 2.2.

Returns:
A document with information about the underlying system that the mongod or mongos runs on. Some of the returned fields are only included on some platforms.

db.hostInfo() provides a helper in the mongo shell around the hostInfo The output of db.hostInfo() on a Linux system will resemble the following:

{
   "system" : {
          "currentTime" : ISODate("<timestamp>"),
          "hostname" : "<hostname>",
          "cpuAddrSize" : <number>,
          "memSizeMB" : <number>,
          "numCores" : <number>,
          "cpuArch" : "<identifier>",
          "numaEnabled" : <boolean>
   },
   "os" : {
          "type" : "<string>",
          "name" : "<string>",
          "version" : "<string>"
   },
   "extra" : {
          "versionString" : "<string>",
          "libcVersion" : "<string>",
          "kernelVersion" : "<string>",
          "cpuFrequencyMHz" : "<string>",
          "cpuFeatures" : "<string>",
          "pageSize" : <number>,
          "numPages" : <number>,
          "maxOpenFiles" : <number>
   },
   "ok" : <return>
}

See hostInfo for full documentation of the output of db.hostInfo().

db.isMaster()

db.isMaster()

Returns:
A document that describes the role of the mongod instance.

If the mongod is a member of a replica set, then the ismaster and secondary fields report if the instance is the primary or if it is a secondary member of the replica set.

See

isMaster for the complete documentation of the output of db.isMaster().

db.killOp()

Description

db.killOp(opid)

Terminates an operation as specified by the operation ID. To find operations and their corresponding IDs, see db.currentOp().

The db.killOp() method has the following parameter:

Parameter | Description
opid | An operation ID.

param number opid:

An operation ID.

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

db.listCommands()

db.listCommands()

Provides a list of all database commands. See the Database Commands document for a more extensive index of these options.

db.loadServerScripts()

db.loadServerScripts()

db.loadServerScripts() loads all scripts in the system.js collection for the current database into the mongo shell session.

Documents in the system.js collection have the following prototype form:

{ _id : "<name>" , value : <function> } }

The documents in the system.js collection provide functions that your applications can use in any JavaScript context with MongoDB in this database. These contexts include $where clauses and mapReduce operations.

db.logout()

db.logout()

Ends the current authentication session. This function has no effect if the current session is not authenticated.

Note

If you’re not logged in and using authentication, db.logout() has no effect.

Changed in version 2.4: Because MongoDB now allows users defined in one database to have privileges on another database, you must call db.logout() while using the same database context that you authenticated to.

If you authenticated to a database such as users or $external, you must issue db.logout() against this database in order to successfully log out.

Example

Use the use <database-name> helper in the interactive mongo shell, or the following db.getSiblingDB() in the interactive shell or in mongo shell scripts to change the db object:

db = db.getSiblingDB('<database-name>')

When you have set the database context and db object, you can use the db.logout() to log out of database as in the following operation:

db.logout()

db.logout() function provides a wrapper around the database command logout.

db.printCollectionStats()

db.printCollectionStats()

Provides a wrapper around the db.collection.stats() method. Returns statistics from every collection separated by three hyphen characters.

Note

The db.printCollectionStats() in the mongo shell does not return JSON. Use db.printCollectionStats() for manual inspection, and db.collection.stats() in scripts.

See also

collStats

db.printReplicationInfo()

Definition

db.printReplicationInfo()

Prints a formatted report of the replica set member’s oplog. The displayed report formats the data returned by db.getReplicationInfo(). [1]

The output of db.printReplicationInfo() is identical to that of rs.printReplicationInfo().

Note

The db.printReplicationInfo() in the mongo shell does not return JSON. Use db.printReplicationInfo() for manual inspection, and db.getReplicationInfo() in scripts.

Output Example

The following example is a sample output from the db.printReplicationInfo() method run on the primary:

configured oplog size:   192MB
log length start to end: 65422secs (18.17hrs)
oplog first event time:  Mon Jun 23 2014 17:47:18 GMT-0400 (EDT)
oplog last event time:   Tue Jun 24 2014 11:57:40 GMT-0400 (EDT)
now:                     Thu Jun 26 2014 14:24:39 GMT-0400 (EDT)

Output Fields

db.printReplicationInfo() formats and prints the data returned by db.getReplicationInfo():

configured oplog size

Displays the db.getReplicationInfo.logSizeMB value.

log length start to end

Displays the db.getReplicationInfo.timeDiff and db.getReplicationInfo.timeDiffHours values.

oplog first event time

Displays the db.getReplicationInfo.tFirst.

oplog last event time

Displays the db.getReplicationInfo.tLast.

now

Displays the db.getReplicationInfo.now.

See db.getReplicationInfo() for description of the data.

[1]
If run on a slave of a master-slave replication, the method calls db.printSlaveReplicationInfo(). See db.printSlaveReplicationInfo() for details.

db.printShardingStatus()

Definition

db.printShardingStatus()

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

Only use db.printShardingStatus() when connected to a mongos instance.

The db.printShardingStatus() method has the following parameter:

Parameter | Description
verbose | Optional. If true, the method displays details of the document distribution across chunks when you have 20 or more chunks.

param Boolean verbose:

Optional. If true, the method displays details of the document distribution across chunks when you have 20 or more chunks.

See sh.status() for details of the output.

Note

The db.printShardingStatus() in the mongo shell does not return JSON. Use db.printShardingStatus() for manual inspection, and Config Database in scripts.

See also

sh.status()

db.printSlaveReplicationInfo()

Definition

db.printSlaveReplicationInfo()

Returns a formatted report of the status of a replica set from the perspective of the secondary member of the set. The output is identical to that of rs.printSlaveReplicationInfo().

Output

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

source: m1.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary
source: m2.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary

Note

The db.printSlaveReplicationInfo() in the mongo shell does not return JSON. Use db.printSlaveReplicationInfo() for manual inspection, and rs.status() in scripts.

A delayed member may show as 0 seconds behind the primary when the inactivity period on the primary is greater than the slaveDelay value.

db.removeUser()

Deprecated since version 2.6: Use db.dropUser() instead of db.removeUser()

Definition

db.removeUser(username)

Removes the specified username from the database.

The db.removeUser() method has the following parameter:

Parameter | Description
username | The database username.

param string username:

The database username.

db.repairDatabase()

db.repairDatabase()

db.repairDatabase() provides a wrapper around the database command repairDatabase, and has the same effect as the run-time option mongod --repair option, limited to only the current database. See repairDatabase for full documentation.

Behavior

Warning

During normal operations, only use the repairDatabase command and wrappers including db.repairDatabase() in the mongo shell and mongod --repair, to compact database files and/or reclaim disk space. Be aware that these operations remove and do not save any corrupt data during the repair process.

If you are trying to repair a replica set member, and you have access to an intact copy of your data (e.g. a recent backup or an intact member of the replica set), you should restore from that intact copy, and not use repairDatabase.

When using journaling, there is almost never any need to run repairDatabase. In the event of an unclean shutdown, the server will be able to restore the data files to a pristine state automatically.

Changed in version 2.6: The db.repairDatabase() is now available for secondary as well as primary members of replica sets.

db.resetError()

db.resetError()

Deprecated since version 1.6.

Resets the error message returned by db.getPrevError or getPrevError. Provides a wrapper around the resetError command.

db.runCommand()

Definition

db.runCommand(command)

Provides a helper to run specified database commands. This is the preferred method to issue database commands, as it provides a consistent interface between the shell and drivers.

Parameter | Description
command | “A database command, specified either in document form or as a string. If specified as a string, db.runCommand() transforms the string into a document.”

param document, string command:

“A database command, specified either in document form or as a string. If specified as a string, db.runCommand() transforms the string into a document.”

New in version 2.6: To specify a time limit in milliseconds, see Terminate Running Operations.

Behavior

db.runCommand() runs the command in the context of the current database. Some commands are only applicable in the context of the admin database, and you must change your db object to before running these commands.

db.serverBuildInfo()

db.serverBuildInfo()

Provides a wrapper around the buildInfo database command. buildInfo returns a document that contains an overview of parameters used to compile this mongod instance.

db.serverCmdLineOpts()

db.serverCmdLineOpts()

Wraps the getCmdLineOpts database command.

Returns a document that reports on the arguments and configuration options used to start the mongod or mongos instance.

See Configuration File Options, mongod, and mongos for additional information on available MongoDB runtime options.

db.serverStatus()

db.serverStatus()

Returns a document that provides an overview of the database process’s state.

This command provides a wrapper around the database command serverStatus.

Changed in version 2.4: In 2.4 you can dynamically suppress portions of the db.serverStatus() output, or include suppressed sections in a document passed to the db.serverStatus() method, as in the following example:

db.serverStatus( { repl: 0, indexCounters: 0, locks: 0 } )
db.serverStatus( { workingSet: 1, metrics: 0, locks: 0 } )

db.serverStatus() includes all fields by default, except workingSet.

Note

You may only dynamically include top-level fields from the serverStatus document that are not included by default. You can exclude any field that db.serverStatus() includes by default.

See also

serverStatus for complete documentation of the output of this function.

db.setProfilingLevel()

Definition

db.setProfilingLevel(level, slowms)

Modifies the current database profiler level used by the database profiling system to capture data about performance. The method provides a wrapper around the database command profile.

Parameter | Description
level | Specifies a profiling level, which is either 0 for no profiling, 1 for only slow operations, or 2 for all operations.
slowms | Optional. Sets the threshold in milliseconds for the profile to consider a query or operation to be slow.

param integer level:
| Specifies a profiling level, which is either 0 for no profiling, 1 for only slow operations, or 2 for all operations.
param integer slowms:
| Optional. Sets the threshold in milliseconds for the profile to consider a query or operation to be slow.

The level chosen can affect performance. It also can allow the server to write the contents of queries to the log, which might have information security implications for your deployment.

Configure the slowOpThresholdMs option to set the threshold for the profiler to consider a query “slow.” Specify this value in milliseconds to override the default, 100ms.

mongod writes the output of the database profiler to the system.profile collection.

mongod prints information about queries that take longer than the slowOpThresholdMs to the log even when the database profiler is not active.

db.shutdownServer()

db.shutdownServer()

Shuts down the current mongod or mongos process cleanly and safely.

This operation fails when the current database is not the admin database.

This command provides a wrapper around the shutdown.

db.stats()

Description

db.stats(scale)

Returns statistics that reflect the use state of a single database.

The db.stats() method has the following parameter:

Parameter | Description
scale | Optional. The scale at which to deliver results. Unless specified, this command returns all data in bytes.

param number scale:

Optional. The scale at which to deliver results. Unless specified, this command returns all data in bytes.

Returns:
A document with statistics reflecting the database system’s state. For an explanation of the output, see dbStats.

The db.stats() method is a wrapper around the dbStats database command.

Example

The following example converts the returned values to kilobytes:

db.stats(1024)

Note

The scale factor rounds values to whole numbers. This can produce unpredictable and unexpected results in some situations.

db.version()

db.version()

Returns:
The version of the mongod or mongos instance.

db.upgradeCheck()

Definition

db.upgradeCheck(<document>)

New in version 2.6.

Performs a preliminary check for upgrade preparedness to 2.6. The helper, available in the 2.6 mongo shell, can run connected to either a 2.4 or a 2.6 server.

The method checks for:

documents with index keys longer than the index key limit,

documents with illegal field names,

collections without an _id index, and

indexes with invalid specifications, such as an index key with an empty or illegal field name.

The method can accept a document parameter which determine the scope of the check:

Parameter
Description

scope

Optional. Document to limit the scope of the check to the specified collection in the database.

Omit to perform the check on all collections in the database.

param document scope:

Optional. Document to limit the scope of the check to the specified collection in the database.

Omit to perform the check on all collections in the database.

The optional scope document has the following form:

{
   collection: <string>
}

Additional 2.6 changes that affect compatibility with older versions require manual checks and intervention. See Compatibility Changes in MongoDB 2.6 for details.

See also

db.upgradeCheckAllDBs()

Behavior

db.upgradeCheck() performs collection scans and has an impact on performance. To mitigate the performance impact:

For sharded clusters, configure to read from secondaries and run the command on the mongos.

For replica sets, run the command on the secondary members.

db.upgradeCheck() can miss new data during the check when run on a live system with active write operations.

For index validation, db.upgradeCheck() only supports the check of version 1 indexes and skips the check of version 0 indexes.

The db.upgradeCheck() checks all of the data stored in the mongod instance: the time to run db.upgradeCheck() depends on the quantity of data stored by mongod.

Required Access

On systems running with authorization, a user must have access that includes the find action on all collections, including the system collections.

Example

The following example connects to a secondary running on localhost and runs db.upgradeCheck() against the employees collection in the records database. Because the output from the method can be quite large, the example pipes the output to a file.

./mongo --eval "db.getMongo().setSlaveOk(); db.upgradeCheck( { collection: 'employees' } )"  localhost/records | tee /tmp/upgradecheck.txt

Error Output

The upgrade check can return the following errors when it encounters incompatibilities in your data:

Index Key Exceed Limit

Document Error: key for index '<indexName>' (<indexSpec>) too long on document: <doc>

To resolve, remove the document. Ensure that the query to remove the document does not specify a condition on the invalid field or field.

Documents with Illegal Field Names

Document Error: document is no longer valid in 2.6 because <errmsg>: <doc>

To resolve, remove the document and re-insert with the appropriate corrections.

Index Specification Invalid

Index Error: invalid index spec for index '<indexName>': <indexSpec>

To resolve, remove the invalid index and recreate with a valid index specification.

Missing _id Index

Collection Error: lack of _id index on collection: <collectionName>

To resolve, create a unique index on _id.

Warning Output

Warning: upgradeCheck only supports V1 indexes. Skipping index: <indexSpec>

To resolve, remove the invalid index and recreate the index omitting the version specification, or reindex the collection. Reindex operation may be expensive for collections that have a large amount of data and/or a large number of indexes.

db.upgradeCheckAllDBs()

Definition

db.upgradeCheckAllDBs()

New in version 2.6.

Performs a preliminary check for upgrade preparedness to 2.6. The helper, available in the 2.6 mongo shell, can run connected to either a 2.4 or a 2.6 server in the admin database.

The method cycles through all the databases and checks for:

documents with index keys longer than the index key limit,

documents with illegal field names,

collections without an _id index, and

indexes with invalid specifications, such as an index key with an empty or illegal field name.

Additional 2.6 changes that affect compatibility with older versions require manual checks and intervention. See Compatibility Changes in MongoDB 2.6 for details.

See also

db.upgradeCheck()

Behavior

db.upgradeCheckAllDBs() performs collection scans and has an impact on performance. To mitigate the performance impact:

For sharded clusters, configure to read from secondaries and run the command on the mongos.

For replica sets, run the command on the secondary members.

db.upgradeCheckAllDBs() can miss new data during the check when run on a live system with active write operations.

For index validation, db.upgradeCheckAllDBs() only supports the check of version 1 indexes and skips the check of version 0 indexes.

The db.upgradeCheckAllDBs() checks all of the data stored in the mongod instance: the time to run db.upgradeCheckAllDBs() depends on the quantity of data stored by mongod.

Required Access

On systems running with authorization, a user must have access that includes the listDatabases action on all databases and the find action on all collections, including the system collections.

You must run the db.upgradeCheckAllDBs() operation in the admin database.

Example

The following example connects to a secondary running on localhost and runs db.upgradeCheckAllDBs() against the admin database. Because the output from the method can be quite large, the example pipes the output to a file.

./mongo --eval "db.getMongo().setSlaveOk(); db.upgradeCheckAllDBs();" localhost/admin | tee /tmp/upgradecheckalldbs.txt

Error Output

The upgrade check can return the following errors when it encounters incompatibilities in your data:

Index Key Exceed Limit

Document Error: key for index '<indexName>' (<indexSpec>) too long on document: <doc>

To resolve, remove the document. Ensure that the query to remove the document does not specify a condition on the invalid field or field.

Documents with Illegal Field Names

Document Error: document is no longer valid in 2.6 because <errmsg>: <doc>

To resolve, remove the document and re-insert with the appropriate corrections.

Index Specification Invalid

Index Error: invalid index spec for index '<indexName>': <indexSpec>

To resolve, remove the invalid index and recreate with a valid index specification.

Missing _id Index

Collection Error: lack of _id index on collection: <collectionName>

To resolve, create a unique index on _id.

Warning Output

Warning: upgradeCheck only supports V1 indexes. Skipping index: <indexSpec>

To resolve, remove the invalid index and recreate the index omitting the version specification, or reindex the collection. Reindex operation may be expensive for collections that have a large amount of data and/or a large number of indexes.

Query Plan Cache Methods

The PlanCache methods are only accessible from a collection’s plan cache object. To retrieve the plan cache object, use the db.collection.getPlanCache() method.

Name | Description
db.collection.getPlanCache() | Returns an interface to access the query plan cache object and associated PlanCache methods for a collection.”
PlanCache.help() | Displays the methods available for a collection’s query plan cache. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().help().
PlanCache.listQueryShapes() | Displays the query shapes for which cached query plans exist. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().listQueryShapes().
PlanCache.getPlansByQuery() | Displays the cached query plans for the specified query shape. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().getPlansByQuery().
PlanCache.clearPlansByQuery() | Clears the cached query plans for the specified query shape. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().clearPlansByQuery()
PlanCache.clear() | Clears all the cached query plans for a collection. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().clear().

db.collection.getPlanCache()

PlanCache.help()

PlanCache.listQueryShapes()

PlanCache.getPlansByQuery()

PlanCache.clearPlansByQuery()

PlanCache.clear()

db.collection.getPlanCache()

Definition

db.collection.getPlanCache()

Returns an interface to access the query plan cache for a collection. The interface provides methods to view and clear the query plan cache.

Returns:
Interface to access the query plan cache.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

Methods

The following methods are available through the interface:

Name | Description
PlanCache.help() | Displays the methods available for a collection’s query plan cache. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().help().
PlanCache.listQueryShapes() | Displays the query shapes for which cached query plans exist. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().listQueryShapes().
PlanCache.getPlansByQuery() | Displays the cached query plans for the specified query shape. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().getPlansByQuery().
PlanCache.clearPlansByQuery() | Clears the cached query plans for the specified query shape. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().clearPlansByQuery()
PlanCache.clear() | Clears all the cached query plans for a collection. Accessible through the plan cache object of a specific collection, i.e. db.collection.getPlanCache().clear().

PlanCache.help()

Definition

PlanCache.help()

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

The method is only available from the plan cache object of a specific collection; i.e.

db.collection.getPlanCache().help()

See also

db.collection.getPlanCache()

PlanCache.listQueryShapes()

Definition

PlanCache.listQueryShapes()

Displays the query shapes for which cached query plans exist.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

The method is only available from the plan cache object of a specific collection; i.e.

db.collection.getPlanCache().listQueryShapes()

Returns:
Array of query shape documents.

The method wraps the planCacheListQueryShapes command.

Required Access

On systems running with authorization, a user must have access that includes the planCacheRead action.

Example

The following returns the query shapes that have cached plans for the orders collection:

db.orders.getPlanCache().listQueryShapes()

The method returns an array of the query shapes currently in the cache. In the example, the orders collection had cached query plans associated with the following shapes:

[
  {
    "query" : { "qty" : { "$gt" : 10 } },
    "sort" : { "ord_date" : 1 },
    "projection" : { }
  },
  {
    "query" : { "$or" :
       [
         { "qty" : { "$gt" : 15 }, "item" : "xyz123" },
         { "status" : "A" }
       ]
    },
    "sort" : { },
    "projection" : { }
  },
  {
    "query" : { "$or" : [ { "qty" : { "$gt" : 15 } }, { "status" : "A" } ] },
    "sort" : { },
    "projection" : { }
  }
]

See also

db.collection.getPlanCache()

PlanCache.getPlansByQuery()

PlanCache.help()

planCacheListQueryShapes

PlanCache.getPlansByQuery()

Definition

PlanCache.getPlansByQuery(<query>, <projection>, <sort>)

Displays the cached query plans for the specified query shape.

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.

The method is only available from the plan cache object of a specific collection; i.e.

db.collection.getPlanCache().getPlansByQuery( <query>, <projection>, <sort> )

The PlanCache.getPlansByQuery() method accepts the following parameters:

Parameter | Description
query | The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
projection | Optional. The projection associated with the query shape. Required if specifying the sort parameter.
sort | Optional. The sort associated with the query shape.

param document query:
| The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
param document projection:
| Optional. The projection associated with the query shape. Required if specifying the sort parameter.
param document sort:
| Optional. The sort associated with the query shape.

Returns:
Array of cached query plans for a query shape.

To see the query shapes for which cached query plans exist, use the PlanCache.listQueryShapes() method.

Required Access

On systems running with authorization, a user must have access that includes the planCacheRead action.

Example

If a collection orders has the following query shape:

{
  "query" : { "qty" : { "$gt" : 10 } },
  "sort" : { "ord_date" : 1 },
  "projection" : { }
}

The following operation displays the query plan cached for the shape:

db.orders.getPlanCache().getPlansByQuery(
   { "qty" : { "$gt" : 10 } },
   { },
   { "ord_date" : 1 }
)

See also

db.collection.getPlanCache()

PlanCache.listQueryShapes()

PlanCache.help()

PlanCache.clearPlansByQuery()

Definition

PlanCache.clearPlansByQuery(<query>, <projection>, <sort>)

Clears the cached query plans for the specified query shape.

The method is only available from the plan cache object of a specific collection; i.e.

db.collection.getPlanCache().clearPlansByQuery( <query>, <projection>, <sort> )

The PlanCache.clearPlansByQuery() method accepts the following parameters:

Parameter | Description
query | The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
projection | Optional. The projection associated with the query shape. Required if specifying the sort parameter.
sort | Optional. The sort associated with the query shape.

param document query:
| The query predicate of the query shape. Only the structure of the predicate, including the field names, are significant to the shape; the values in the query predicate are insignificant.
param document projection:
| Optional. The projection associated with the query shape. Required if specifying the sort parameter.
param document sort:
| Optional. The sort associated with the query shape.

To see the query shapes for which cached query plans exist, use the PlanCache.listQueryShapes() method.

Required Access

On systems running with authorization, a user must have access that includes the planCacheWrite action.

Example

If a collection orders has the following query shape:

{
  "query" : { "qty" : { "$gt" : 10 } },
  "sort" : { "ord_date" : 1 },
  "projection" : { }
}

The following operation removes the query plan cached for the shape:

db.orders.getPlanCache().clearPlansByQuery(
   { "qty" : { "$gt" : 10 } },
   { },
   { "ord_date" : 1 }
)

See also

db.collection.getPlanCache()

PlanCache.listQueryShapes()

PlanCache.clear()

PlanCache.clear()

Definition

PlanCache.clear()

Removes all cached query plans for a collection.

The method is only available from the plan cache object of a specific collection; i.e.

db.collection.getPlanCache().clear()

For example, to clear the cache for the orders collection:

db.orders.getPlanCache().clear()

Required Access

On systems running with authorization, a user must have access that includes the planCacheWrite action.

See also

db.collection.getPlanCache()

PlanCache.clearPlansByQuery()

Bulk Operation Methods

New in version 2.6.

Name | Description
Bulk() | Bulk operations builder.
db.collection.initializeOrderedBulkOp() | Initializes a Bulk() operations builder for an ordered list of operations.
db.collection.initializeUnorderedBulkOp() | Initializes a Bulk() operations builder for an unordered list of operations.
Bulk.insert() | Adds an insert operation to a list of operations.
Bulk.find() | Specifies the query condition for an update or a remove operation.
Bulk.find.removeOne() | Adds a single document remove operation to a list of operations.
Bulk.find.remove() | Adds a multiple document remove operation to a list of operations.
Bulk.find.replaceOne() | Adds a single document replacement operation to a list of operations.
Bulk.find.updateOne() | Adds a single document update operation to a list of operations.
Bulk.find.update() | Adds a multi update operation to a list of operations.
Bulk.find.upsert() | Specifies upsert: true for an update operation.
Bulk.execute() | Executes a list of operations in bulk.
Bulk.getOperations() | Returns an array of write operations executed in the Bulk() operations object.
Bulk.tojson() | Returns a JSON document that contains the number of operations and batches in the Bulk() operations object.
Bulk.toString() | Returns the Bulk.tojson() results as a string.

Bulk()

db.collection.initializeOrderedBulkOp()

db.collection.initializeUnorderedBulkOp()

Bulk.insert()

Bulk.find()

Bulk.find.removeOne()

Bulk.find.remove()

Bulk.find.replaceOne()

Bulk.find.updateOne()

Bulk.find.update()

Bulk.find.upsert()

Bulk.execute()

Bulk.getOperations()

Bulk.tojson()

Bulk.toString()

Bulk()

Description

Bulk()

New in version 2.6.

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 db.collection.initializeUnorderedBulkOp() method.

Ordered and Unordered Bulk Operations

The builder can construct the list of operations as ordered or unordered.

Ordered Operations

With an ordered operations list, MongoDB executes the write operations in the list serially. If an error occurs during the processing of one of the write operations, MongoDB will return without processing any remaining write operations in the list.

Use db.collection.initializeOrderedBulkOp() to create a builder for an ordered list of write commands.

When executing an ordered list of operations, MongoDB groups the operations by the operation type and contiguity; i.e. contiguous operations of the same type are grouped together. For example, if an ordered list has two insert operations followed by an update operation followed by another insert operation, MongoDB groups the operations into three separate groups: first group contains the two insert operations, second group contains the update operation, and the third group contains the last insert operation. This behavior is subject to change in future versions.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.

Unordered Operations

With an unordered operations list, MongoDB can execute in parallel, as well as in a nondeterministic order, the write operations in the list. If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

Use db.collection.initializeUnorderedBulkOp() to create a builder for an unordered list of write commands.

When executing an unordered list of operations, MongoDB groups the operations. With an unordered bulk operation, the operations in the list may be reordered to increase performance. As such, applications should not depend on the ordering when performing unordered bulk operations.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Methods

The Bulk() builder has the following methods:

Name | Description
Bulk.insert() | Adds an insert operation to a list of operations.
Bulk.find() | Specifies the query condition for an update or a remove operation.
Bulk.find.removeOne() | Adds a single document remove operation to a list of operations.
Bulk.find.remove() | Adds a multiple document remove operation to a list of operations.
Bulk.find.replaceOne() | Adds a single document replacement operation to a list of operations.
Bulk.find.updateOne() | Adds a single document update operation to a list of operations.
Bulk.find.update() | Adds a multi update operation to a list of operations.
Bulk.find.upsert() | Specifies upsert: true for an update operation.
Bulk.execute() | Executes a list of operations in bulk.
Bulk.getOperations() | Returns an array of write operations executed in the Bulk() operations object.
Bulk.tojson() | Returns a JSON document that contains the number of operations and batches in the Bulk() operations object.
Bulk.toString() | Returns the Bulk.tojson() results as a string.

db.collection.initializeOrderedBulkOp()

Definition

db.collection.initializeOrderedBulkOp()

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

Returns:
new Bulk() operations builder object.

Behavior

Order of Operation

With an ordered operations list, MongoDB executes the write operations in the list serially.

Execution of Operations

When executing an ordered list of operations, MongoDB groups the operations by the operation type and contiguity; i.e. contiguous operations of the same type are grouped together. For example, if an ordered list has two insert operations followed by an update operation followed by another insert operation, MongoDB groups the operations into three separate groups: first group contains the two insert operations, second group contains the update operation, and the third group contains the last insert operation. This behavior is subject to change in future versions.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.

Error Handling

If an error occurs during the processing of one of the write operations, MongoDB will return without processing any remaining write operations in the list.

Examples

The following initializes a Bulk() operations builder on the users collection, adds a series of write operations, and executes the operations:

var bulk = db.users.initializeOrderedBulkOp();
bulk.insert( { user: "abc123", status: "A", points: 0 } );
bulk.insert( { user: "ijk123", status: "A", points: 0 } );
bulk.insert( { user: "mop123", status: "P", points: 0 } );
bulk.find( { status: "D" } ).remove();
bulk.find( { status: "P" } ).update( { $set: { comment: "Pending" } } );
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

Bulk.find()

Bulk.find.removeOne()

Bulk.execute()

db.collection.initializeUnorderedBulkOp()

Definition

db.collection.initializeUnorderedBulkOp()

New in version 2.6.

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

Behavior

Order of Operation

With an unordered operations list, MongoDB can execute in parallel the write operations in the list and in any order. If the order of operations matter, use db.collection.initializeOrderedBulkOp() instead.

Execution of Operations

When executing an unordered list of operations, MongoDB groups the operations. With an unordered bulk operation, the operations in the list may be reordered to increase performance. As such, applications should not depend on the ordering when performing unordered bulk operations.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Error Handling

If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

Example

The following initializes a Bulk() operations builder and adds a series of insert operations to add multiple documents:

var bulk = db.users.initializeUnorderedBulkOp();
bulk.insert( { user: "abc123", status: "A", points: 0 } );
bulk.insert( { user: "ijk123", status: "A", points: 0 } );
bulk.insert( { user: "mop123", status: "P", points: 0 } );
bulk.execute();

See also

db.collection.initializeOrderedBulkOp()

Bulk()

Bulk.insert()

Bulk.execute()

Bulk.insert()

Description

Bulk.insert(<document>)

New in version 2.6.

Adds an insert operation to a bulk operations list.

Bulk.insert() accepts the following parameter:

Parameter | Description
doc | Document to insert. The size of the document must be less than or equal to the maximum BSON document size.

param document doc:

Document to insert. The size of the document must be less than or equal to the maximum BSON document size.

Example

The following initializes a Bulk() operations builder for the items collection and adds a series of insert operations to add multiple documents:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { item: "abc123", defaultQty: 100, status: "A", points: 100 } );
bulk.insert( { item: "ijk123", defaultQty: 200, status: "A", points: 200 } );
bulk.insert( { item: "mop123", defaultQty: 0, status: "P", points: 0 } );
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.execute()

Bulk.find()

Description

Bulk.find(<query>)

New in version 2.6.

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

Bulk.find() accepts the following parameter:

Parameter
Description

query

Specifies a query condition using Query Selectors to select documents for an update or a remove operation. To specify all documents, use an empty document {}.

With update operations, the sum of the query document and the update document must be less than or equal to the maximum BSON document size.

With remove operations, the query document must be less than or equal to the maximum BSON document size.

param document query:

Specifies a query condition using Query Selectors to select documents for an update or a remove operation. To specify all documents, use an empty document {}.

With update operations, the sum of the query document and the update document must be less than or equal to the maximum BSON document size.

With remove operations, the query document must be less than or equal to the maximum BSON document size.

Use Bulk.find() with the following write operations:

Bulk.find.removeOne()

Bulk.find.remove()

Bulk.find.replaceOne()

Bulk.find.updateOne()

Bulk.find.update()

Example

The following example initializes a Bulk() operations builder for the items collection and adds a remove operation and an update operation to the list of operations. The remove operation and the update operation use the Bulk.find() method to specify a condition for their respective actions:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "D" } ).remove();
bulk.find( { status: "P" } ).update( { $set: { points: 0 } } )
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.execute()

Bulk.find.removeOne()

Description

Bulk.find.removeOne()

New in version 2.6.

Adds a single document remove operation to a bulk operations list. Use the Bulk.find() method to specify the condition that determines which document to remove. The Bulk.find.removeOne() limits the removal to one document. To remove multiple documents, see Bulk.find.remove().

Example

The following example initializes a Bulk() operations builder for the items collection and adds two Bulk.find.removeOne() operations to the list of operations.

Each remove operation removes just one document: one document with the status equal to "D" and another document with the status equal to "P".

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "D" } ).removeOne();
bulk.find( { status: "P" } ).removeOne();
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.find.remove()

Bulk.execute()

All Bulk Methods

Bulk.find.remove()

Description

Bulk.find.remove()

New in version 2.6.

Adds a remove operation to a bulk operations list. Use the Bulk.find() method to specify the condition that determines which documents to remove. The Bulk.find.remove() method removes all matching documents in the collection. To limit the remove to a single document, see Bulk.find.removeOne().

Example

The following example initializes a Bulk() operations builder for the items collection and adds a remove operation to the list of operations. The remove operation removes all documents in the collection where the status equals "D":

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "D" } ).remove();
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.find.removeOne()

Bulk.execute()

Bulk.find.replaceOne()

Description

Bulk.find.replaceOne(<document>)

New in version 2.6.

Adds a single document replacement operation to a bulk operations list. Use the Bulk.find() method to specify the condition that determines which document to replace. The Bulk.find.replaceOne() method limits the replacement to a single document.

Bulk.find.replaceOne() accepts the following parameter:

Parameter
Description

replacement

A replacement document that completely replaces the existing document. Contains only field and value pairs.

The sum of the associated <query> document from the Bulk.find() and the replacement document must be less than or equal to the maximum BSON document size.

param document replacement:

A replacement document that completely replaces the existing document. Contains only field and value pairs.

The sum of the associated <query> document from the Bulk.find() and the replacement document must be less than or equal to the maximum BSON document size.

To specify an upsert for this operation, see Bulk.find.upsert().

Example

The following example initializes a Bulk() operations builder for the items collection, and adds various replaceOne operations to the list of operations.

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { item: "abc123" } ).replaceOne( { item: "abc123", status: "P", points: 100 } );
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.execute()

All Bulk Methods

Bulk.find.updateOne()

Description

Bulk.find.updateOne(<update>)

New in version 2.6.

Adds a single document update operation to a bulk operations list. The operation can either replace an existing document or update specific fields in an existing document.

Use the Bulk.find() method to specify the condition that determines which document to update. The Bulk.find.updateOne() method limits the update or replacement to a single document. To update multiple documents, see Bulk.find.update().

Bulk.find.updateOne() accepts the following parameter:

Parameter
Description

update

An update document that updates specific fields or a replacement document that completely replaces the existing document.

An update document only contains update operator expressions. A replacement document contains only field and value pairs.

The sum of the associated <query> document from the Bulk.find() and the update/replacement document must be less than or equal to the maximum BSON document size.

param document update:

An update document that updates specific fields or a replacement document that completely replaces the existing document.

An update document only contains update operator expressions. A replacement document contains only field and value pairs.

The sum of the associated <query> document from the Bulk.find() and the update/replacement document must be less than or equal to the maximum BSON document size.

To specify an upsert: true for this operation, see Bulk.find.upsert().

Behavior

Update Specific Fields

If the <update> document contains only update operator expressions, as in:

{
  $set: { status: "D" },
  points: { $inc: 2 }
}

Then, Bulk.find.updateOne() updates only the corresponding fields, status and points, in the document.

Replace a Document

If the <update> document contains only field:value expressions, as in:

{
  item: "TBD",
  points: 0,
  inStock: true,
  status: "I"
}

Then, Bulk.find.updateOne() replaces the matching document with the <update> document with the exception of the _id field. The Bulk.find.updateOne() method does not replace the _id value.

Example

The following example initializes a Bulk() operations builder for the items collection, and adds various updateOne operations to the list of operations.

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "D" } ).updateOne( { $set: { status: "I", points: "0" } } );
bulk.find( { item: null } ).updateOne(
   {
      item: "TBD",
      points: 0,
      inStock: true,
      status: "I"
   }
);
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.find.update()

Bulk.execute()

All Bulk Methods

Bulk.find.update()

Description

Bulk.find.update(<update>)

New in version 2.6.

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

Use the Bulk.find() method to specify the condition that determines which documents to update. The Bulk.find.update() method updates all matching documents. To specify a single document update, see Bulk.find.updateOne().

Bulk.find.update() accepts the following parameter:

Parameter
Description

update

Specifies the fields to update. Only contains update operator expressions.

The sum of the associated <query> document from the Bulk.find() and the update document must be less than or equal to the maximum BSON document size.

param document update:

Specifies the fields to update. Only contains update operator expressions.

The sum of the associated <query> document from the Bulk.find() and the update document must be less than or equal to the maximum BSON document size.

To specify upsert: true for this operation, see Bulk.find.upsert(). With Bulk.find.upsert(), if no documents match the Bulk.find() query condition, the update operation inserts only a single document.

Example

The following example initializes a Bulk() operations builder for the items collection, and adds various multi update operations to the list of operations.

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "D" } ).update( { $set: { status: "I", points: "0" } } );
bulk.find( { item: null } ).update( { $set: { item: "TBD" } } );
bulk.execute();

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.find.updateOne()

Bulk.execute()

All Bulk Methods

Bulk.find.upsert()

Description

Bulk.find.upsert()

New in version 2.6.

Sets the upsert option to true for an update or a replacement operation and has the following syntax:

Bulk.find(<query>).upsert().update(<update>);
Bulk.find(<query>).upsert().updateOne(<update>);
Bulk.find(<query>).upsert().replaceOne(<replacement>);

With the upsert option set to true, if no matching documents exist for the Bulk.find() condition, then the update or the replacement operation performs an insert. If a matching document does exist, then the update or replacement operation performs the specified update or replacement.

Use Bulk.find.upsert() with the following write operations:

Bulk.find.replaceOne()

Bulk.find.updateOne()

Bulk.find.update()

Behavior

The following describe the insert behavior of various write operations when used in conjunction with Bulk.find.upsert().

Insert for Bulk.find.replaceOne()

The Bulk.find.replaceOne() method accepts, as its parameter, a replacement document that only contains field and value pairs:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { item: "abc123" } ).upsert().replaceOne(
   {
     item: "abc123",
     status: "P",
     points: 100,
   }
);
bulk.execute();

If the replacement operation with the Bulk.find.upsert() option performs an insert, the inserted document is the replacement document. If the replacement document does not specify an _id field, MongoDB adds the _id field:

{
  "_id" : ObjectId("52ded3b398ca567f5c97ac9e"),
  "item" : "abc123",
  "status" : "P",
  "points" : 100
}

Insert for Bulk.find.updateOne()

The Bulk.find.updateOne() method accepts, as its parameter, an <update> document that contains only field and value pairs or only update operator expressions.

Field and Value Pairs

If the <update> document contains only field and value pairs:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P" } ).upsert().updateOne(
   {
     item: "TBD",
     points: 0,
     inStock: true,
     status: "I"
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the inserted document is the <update> document. If the update document does not specify an _id field, MongoDB adds the _id field:

{
  "_id" : ObjectId("52ded5a898ca567f5c97ac9f"),
  "item" : "TBD",
  "points" : 0,
  "inStock" : true,
  "status" : "I"
}

Update Operator Expressions

If the <update> document contains contains only update operator expressions:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P", item: null } ).upsert().updateOne(
   {
     $setOnInsert: { defaultQty: 0, inStock: true },
     $currentDate: { lastModified: true },
     $set: { points: "0" }
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the update operation inserts a document with field and values from the <query> document of the Bulk.find() method and then applies the specified update from the <update> document:

{
   "_id" : ObjectId("52ded68c98ca567f5c97aca0"),
   "item" : null,
   "status" : "P",
   "defaultQty" : 0,
   "inStock" : true,
   "lastModified" : ISODate("2014-01-21T20:20:28.786Z"),
   "points" : "0"
}

If neither the <query> document nor the <update> document specifies an _id field, MongoDB adds the _id field.

Insert for Bulk.find.update()

When using upsert() with the multiple document update method Bulk.find.update(), if no documents match the query condition, the update operation inserts a single document.

The Bulk.find.update() method accepts, as its parameter, an <update> document that contains only update operator expressions:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P" } ).upsert().update(
   {
     $setOnInsert: { defaultQty: 0, inStock: true },
     $currentDate: { lastModified: true },
     $set: { status: "I", points: "0" }
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the update operation inserts a single document with the fields and values from the <query> document of the Bulk.find() method and then applies the specified update from the <update> document:

{
   "_id": ObjectId("52ded81a98ca567f5c97aca1"),
   "status": "I",
   "defaultQty": 0,
   "inStock": true,
   "lastModified": ISODate("2014-01-21T20:27:06.691Z"),
   "points": "0"
}

If neither the <query> document nor the <update> document specifies an _id field, MongoDB adds the _id field.

See also

db.collection.initializeUnorderedBulkOp()

db.collection.initializeOrderedBulkOp()

Bulk.find()

Bulk.execute()

All Bulk Methods

Bulk.execute()

Description

Bulk.execute()

New in version 2.6.

Executes the list of operations built by the Bulk() operations builder.

Bulk.execute() accepts the following parameter:

Parameter
Description

writeConcern

Optional. Write concern document for the bulk operation as a whole. Omit to use default. For a standalone mongod server, the write concern defaults to { w: 1 }. With a replica set, the default write concern is { w: 1 } unless modified as part of the replica set configuration.

See Override Default Write Concern for an example.

param document writeConcern:

Optional. Write concern document for the bulk operation as a whole. Omit to use default. For a standalone mongod server, the write concern defaults to { w: 1 }. With a replica set, the default write concern is { w: 1 } unless modified as part of the replica set configuration.

See Override Default Write Concern for an example.

Returns:
A BulkWriteResult object that contains the status of the operation.

After execution, you cannot re-execute the Bulk() object without reinitializing. See db.collection.initializeUnorderedBulkOp() and db.collection.initializeOrderedBulkOp().

Behavior

Ordered Operations

When executing an ordered list of operations, MongoDB groups the operations by the operation type and contiguity; i.e. contiguous operations of the same type are grouped together. For example, if an ordered list has two insert operations followed by an update operation followed by another insert operation, MongoDB groups the operations into three separate groups: first group contains the two insert operations, second group contains the update operation, and the third group contains the last insert operation. This behavior is subject to change in future versions.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.

Unordered Operations

When executing an unordered list of operations, MongoDB groups the operations. With an unordered bulk operation, the operations in the list may be reordered to increase performance. As such, applications should not depend on the ordering when performing unordered bulk operations.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Examples

Execute Bulk Operations

The following initializes a Bulk() operations builder on the items collection, adds a series of insert operations, and executes the operations:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } );
bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } );
bulk.execute( );

The operation returns the following BulkWriteResult() object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

For details on the return object, see BulkWriteResult(). For details on the batches executed, see Bulk.getOperations().

Override Default Write Concern

The following operation to a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the writes propagate to a majority of the replica set members or the method times out after 5 seconds.

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { item: "efg123", status: "A", defaultQty: 100, points: 0 } );
bulk.insert( { item: "xyz123", status: "A", defaultQty: 100, points: 0 } );
bulk.execute( { w: "majority", wtimeout: 5000 } );

The operation returns the following BulkWriteResult() object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

See

Bulk() for a listing of methods available for bulk operations.

Bulk.getOperations()

Bulk.getOperations()

New in version 2.6.

Returns an array of write operations executed through Bulk.execute(). The returned write operations are in groups as determined by MongoDB for execution. For information on how MongoDB groups the list of bulk write operations, see Bulk.execute() Behavior.

Only use Bulk.getOperations() after a Bulk.execute(). Calling Bulk.getOperations() before you call Bulk.execute() will result in an incomplete list.

Example

The following initializes a Bulk() operations builder on the items collection, adds a series of write operations, executes the operations, and then calls getOperations() on the bulk builder object:

var bulk = db.items.initializeUnorderedBulkOp();

for (var i = 1; i <= 1500; i++) {
    bulk.insert( { x: i } );
}

bulk.execute();
bulk.getOperations();

The getOperations() method returns an array with the operations executed. The output shows that MongoDB divided the operations into 2 groups, one with 1000 operations and one with 500. For information on how MongoDB groups the list of bulk write operations, see Bulk.execute() Behavior

Although the method returns all 1500 operations in the returned array, this page omits some of the results for brevity.

[
   {
      "originalZeroIndex" : 0,
      "batchType" : 1,
      "operations" : [
         { "_id" : ObjectId("53a8959f1990ca24d01c6165"), "x" : 1 },

         ... // Content omitted for brevity

         { "_id" : ObjectId("53a8959f1990ca24d01c654c"), "x" : 1000 }
      ]
   },
   {
      "originalZeroIndex" : 1000,
      "batchType" : 1,
      "operations" : [
         { "_id" : ObjectId("53a8959f1990ca24d01c654d"), "x" : 1001 },

         ... // Content omitted for brevity

         { "_id" : ObjectId("53a8959f1990ca24d01c6740"), "x" : 1500 }
      ]
   }
]

Returned Fields

The array contains documents with the following fields:

originalZeroIndex

Specifies the order in which the operation was added to the bulk operations builder, based on a zero index; e.g. first operation added to the bulk operations builder will have originalZeroIndex value of 0.

batchType

Specifies the write operations type.

batchType | Operation
1 | Insert
2 | Update
3 | Remove

operations

Array of documents that contain the details of the operation.

See also

Bulk() and Bulk.execute().

Bulk.tojson()

Bulk.tojson()

New in version 2.6.

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

Example

The following initializes a Bulk() operations builder on the items collection, adds a series of write operations, and calls Bulk.tojson() on the bulk builder object.

var bulk = db.items.initializeOrderedBulkOp();
bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } );
bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } );
bulk.find( { status: "D" } ).removeOne();
bulk.tojson();

The Bulk.tojson() returns the following JSON document

{ “nInsertOps” : 2, “nUpdateOps” : 0, “nRemoveOps” : 1, “nBatches” : 2 }

See also

Bulk()

Bulk.toString()

Bulk.toString()

New in version 2.6.

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

Example

The following initializes a Bulk() operations builder on the items collection, adds a series of write operations, and calls Bulk.toString() on the bulk builder object.

var bulk = db.items.initializeOrderedBulkOp();
bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } );
bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } );
bulk.find( { status: "D" } ).removeOne();
bulk.toString();

The Bulk.toString() returns the following JSON document

{ “nInsertOps” : 2, “nUpdateOps” : 0, “nRemoveOps” : 1, “nBatches” : 2 }

See also

Bulk()

User Management Methods

Name | Description
db.createUser() | Creates a new user.
db.addUser() | Deprecated. Adds a user to a database, and allows administrators to configure the user’s privileges.
db.updateUser() | Updates user data.
db.changeUserPassword() | Changes an existing user’s password.
db.removeUser() | Deprecated. Removes a user from a database.
db.dropAllUsers() | Deletes all users associated with a database.
db.dropUser() | Removes a single user.
db.grantRolesToUser() | Grants a role and its privileges to a user.
db.revokeRolesFromUser() | Removes a role from a user.
db.getUser() | Returns information about the specified user.
db.getUsers() | Returns information about all users associated with a database.

db.createUser()

db.addUser()

db.updateUser()

db.changeUserPassword()

db.removeUser()

db.dropAllUsers()

db.dropUser()

db.grantRolesToUser()

db.revokeRolesFromUser()

db.getUser()

db.getUsers()

db.createUser()

Definition

db.createUser(user, writeConcern)

Creates a new user for the database where the method runs. db.createUser() returns a duplicate user error if the user already exists on the database.

The db.createUser() method has the following syntax:

Field | Description
writeConcern | Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.
user | The document with authentication and access information about the user to create.

field document writeConcern:
| Optional. The level of write concern for the creation operation. The writeConcern document takes the same fields as the getLastError command.
field document user:
| The document with authentication and access information about the user to create.

The user document defines the user and has the following form:

{ user: "<name>",
  pwd: "<cleartext password>",
  customData: { <any information> },
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ]
}

The user document has the following fields:

Field | Description
pwd | The user’s password. The pwd field is not required if you run db.createUser() on the $external database to create users who have credentials stored externally to MongoDB.
customData | Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
roles | The roles granted to the user. Can specify an empty array [] to create users without roles.
user | The name of the new user.

field string pwd:
| The user’s password. The pwd field is not required if you run db.createUser() on the $external database to create users who have credentials stored externally to MongoDB.
field document customData:
| Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id.
field array roles:
| The roles granted to the user. Can specify an empty array [] to create users without roles.
field string user:
| The name of the new user.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.createUser() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.createUser() method wraps the createUser command.

Behavior

Encryption

db.createUser() sends password to the MongoDB instance without encryption. To encrypt the password during transmission, use SSL.

External Credentials

Users created on the $external database should have credentials stored externally to MongoDB, as, for example, with MongoDB Enterprise installations that use Kerberos.

local Database

You cannot create users on the local database.

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

Examples

The following db.createUser() operation creates the accountAdmin01 user on the products database.

use products
db.createUser( { "user" : "accountAdmin01",
                 "pwd": "cleartext password",
                 "customData" : { employeeId: 12345 },
                 "roles" : [ { role: "clusterAdmin", db: "admin" },
                             { role: "readAnyDatabase", db: "admin" },
                             "readWrite"
                             ] },
               { w: "majority" , wtimeout: 5000 } )

The operation gives accountAdmin01 the following roles:

the clusterAdmin and readAnyDatabase roles on the admin database

the readWrite role on the products database

Create User with Roles

The following operation creates accountUser in the products database and gives the user the readWrite and dbAdmin roles.

use products
db.createUser(
   {
     user: "accountUser",
     pwd: "password",
     roles: [ "readWrite", "dbAdmin" ]
   }
)

Create User Without Roles

The following operation creates a user named reportsUser in the admin database but does not yet assign roles:

use admin
db.createUser(
   {
     user: "reportsUser",
     pwd: "password",
     roles: [ ]
   }
)

Create Administrative User with Roles

The following operation creates a user named appAdmin in the admin database and gives the user readWrite access to the config database, which lets the user change certain settings for sharded clusters, such as to the balancer setting.

use admin
db.createUser(
   {
     user: "appAdmin",
     pwd: "password",
     roles:
       [
         { role: "readWrite", db: "config" },
         "clusterAdmin"
       ]
   }
)

db.updateUser()

Definition

db.updateUser(username, update, writeConcern)

Updates the user’s profile on the database on which you run the method. An update to a field completely replaces the previous field’s values. This includes updates to the user’s roles array.

Warning

When you update the roles array, you completely replace the previous array’s values. To add or remove roles without replacing all the user’s existing roles, use the db.grantRolesToUser() or db.revokeRolesFromUser() methods.

The db.updateUser() method uses the following syntax:

db.updateUser(
   "<username>",
   {
     customData : { <any information> },
     roles : [
               { role: "<role>", db: "<database>" } | "<role>",
               ...
             ],
     pwd: "<cleartext password>"
    },
    writeConcern: { <write concern> }
)

The db.updateUser() method has the following arguments.

Parameter | Description
writeConcern | Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.
username | The name of the user to update.
update | A document containing the replacement data for the user. This data completely replaces the corresponding data for the user.

param document writeConcern:
| Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.
param string username:
| The name of the user to update.
param document update:
| A document containing the replacement data for the user. This data completely replaces the corresponding data for the user.

The update document specifies the fields to update and their new values. All fields in the update document are optional, but must include at least one field.

The update document has the following fields:

Field | Description
customData | Optional. Any arbitrary information.
roles | Optional. The roles granted to the user. An update to the roles array overrides the previous array’s values.
pwd | Optional. The user’s password.

field document customData:
| Optional. Any arbitrary information.
field array roles:
| Optional. The roles granted to the user. An update to the roles array overrides the previous array’s values.
field string pwd:
| Optional. The user’s password.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.updateUser() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.updateUser() method wraps the updateUser command.

Behavior

db.updateUser() sends password to the MongoDB instance without encryption. To encrypt the password during transmission, use SSL.

Required Access

You must have access that includes the revokeRole action on all databases in order to update a user’s roles array.

You must have the grantRole action on a role’s database to add a role to a user.

To change another user’s pwd or customData field, you must have the changeAnyPassword and changeAnyCustomData actions respectively on that user’s database.

To modify your own password and custom data, you must have privileges that grant changeOwnPassword and changeOwnCustomData actions respectively on the user’s database.

Example

Given a user appClient01 in the products database with the following user info:

{
   "_id" : "products.appClient01",
   "user" : "appClient01",
   "db" : "products",
   "customData" : { "empID" : "12345", "badge" : "9156" },
   "roles" : [
       { "role" : "readWrite",
         "db" : "products"
       },
       { "role" : "read",
         "db" : "inventory"
       }
   ]
}

The following db.updateUser() method completely replaces the user’s customData and roles data:

use products
db.updateUser( "appClient01",
               {
                 customData : { employeeId : "0x3039" },
                 roles : [
                           { role : "read", db : "assets"  }
                         ]
                }
             )

The user appClient01 in the products database now has the following user information:

{
   "_id" : "products.appClient01",
   "user" : "appClient01",
   "db" : "products",
   "customData" : { "employeeId" : "0x3039" },
   "roles" : [
       { "role" : "read",
         "db" : "assets"
       }
   ]
}

db.dropAllUsers()

Definition

db.dropAllUsers(writeConcern)

Removes all users from the current database.

Warning

The dropAllUsers method removes all users from the database.

The dropAllUsers method takes the following arguments:

Field | Description
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field document writeConcern:

Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

The db.dropAllUsers() method wraps the dropAllUsersFromDatabase command.

Required Access

You must have the dropUser action on a database to drop a user from that database.

Example

The following db.dropAllUsers() operation drops every user from the products database.

use products
db.dropAllUsers( {w: "majority", wtimeout: 5000} )

The n field in the results document shows the number of users removed:

{ "n" : 12, "ok" : 1 }

db.dropUser()

Definition

db.dropUser(username, writeConcern)

Removes the user from the current database.

The db.dropUser() method takes the following arguments:

Parameter | Description
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.
username | The name of the user to remove from the database.

param document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.
param string username:
| The name of the user to remove from the database.

The db.dropUser() method wraps the dropUser command.

Required Access

You must have the dropUser action on a database to drop a user from that database.

Example

The following db.dropUser() operation drops the accountAdmin01 user on the products database.

use products
db.dropUser("accountAdmin01", {w: "majority", wtimeout: 5000})

db.grantRolesToUser()

Definition

db.grantRolesToUser(username, roles, writeConcern)

Grants additional roles to a user.

The grantRolesToUser method uses the following syntax:

db.grantRolesToUser( "<username>", [ <roles> ], { <writeConcern> } )

The grantRolesToUser method takes the following arguments:

Parameter | Description
roles | An array of additional roles to grant to the user.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
user | The name of the user to whom to grant roles.

param array roles:
| An array of additional roles to grant to the user.
param document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
param string user:
| The name of the user to whom to grant roles.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.grantRolesToUser() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.grantRolesToUser() method wraps the grantRolesToUser command.

Required Access

You must have the grantRole action on a database to grant a role on that database.

Example

Given a user accountUser01 in the products database with the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    }
]

The following grantRolesToUser() operation gives accountUser01 the readWrite role on the products database and the read role on the stock database.

use products
db.grantRolesToUser(
   "accountUser01",
   [ "readWrite" , { role: "read", db: "stock" } ],
   { w: "majority" , wtimeout: 4000 }
)

The user accountUser01 in the products database now has the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    },
    { "role" : "read",
      "db" : "stock"
    },
    { "role" : "readWrite",
      "db" : "products"
    }
]

db.revokeRolesFromUser()

Definition

db.revokeRolesFromUser()

Removes a one or more roles from a user on the current database. The db.revokeRolesFromUser() method uses the following syntax:

db.revokeRolesFromUser( "<username>", [ <roles> ], { <writeConcern> } )

The revokeRolesFromUser method takes the following arguments:

Parameter | Description
roles | The roles to remove from the user.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
user | The name of the user from whom to revoke roles.

param array roles:
| The roles to remove from the user.
param document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
param string user:
| The name of the user from whom to revoke roles.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.revokeRolesFromUser() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.revokeRolesFromUser() method wraps the revokeRolesFromUser command.

Required Access

You must have the revokeRole action on a database to revoke a role on that database.

Example

The accountUser01 user in the products database has the following roles:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    },
    { "role" : "read",
      "db" : "stock"
    },
    { "role" : "readWrite",
      "db" : "products"
    }
]

The following db.revokeRolesFromUser() method removes the two of the user’s roles: the read role on the stock database and the readWrite role on the products database, which is also the database on which the method runs:

use products
db.revokeRolesFromUser( "accountUser01",
                        [ { role: "read", db: "stock" }, "readWrite" ],
                        { w: "majority" }
                      )

The user accountUser01 user in the products database now has only one remaining role:

"roles" : [
    { "role" : "assetsReader",
      "db" : "assets"
    }
]

db.getUser()

Definition

db.getUser(username)

Returns user information for a specified user. Run this method on the user’s database. The user must exist on the database on which the method runs.

The db.getUser() method has the following parameter:

Parameter | Description
username | The name of the user for which to retrieve information.

param string username:

The name of the user for which to retrieve information.

db.getUser() wraps the usersInfo command.

Required Access

You must have the viewUser action on another user’s database to view the other user’s credentials.

You can view your own information.

Example

The following sequence of operations returns information about the appClient user on the accounts database:

use accounts
db.getUser("appClient")

db.getUsers()

Definition

db.getUsers()

Returns information for all the users in the database.

db.getUsers() wraps the usersInfo command.

Required Access

You must have the viewUser action on another user’s database to view the other user’s credentials.

You can view your own information.

Role Management Methods

Name | Description
db.createRole() | Creates a role and specifies its privileges.
db.updateRole() | Updates a user-defined role.
db.dropRole() | Deletes a user-defined role.
db.dropAllRoles() | Deletes all user-defined roles associated with a database.
db.grantPrivilegesToRole() | Assigns privileges to a user-defined role.
db.revokePrivilegesFromRole() | Removes the specified privileges from a user-defined role.
db.grantRolesToRole() | Specifies roles from which a user-defined role inherits privileges.
db.revokeRolesFromRole() | Removes a role from a user.
db.getRole() | Returns information for the specified role.
db.getRoles() | Returns information for all the user-defined roles in a database.

db.createRole()

db.updateRole()

db.dropRole()

db.dropAllRoles()

db.grantPrivilegesToRole()

db.revokePrivilegesFromRole()

db.grantRolesToRole()

db.revokeRolesFromRole()

db.getRole()

db.getRoles()

db.createRole()

Definition

db.createRole(role, writeConcern)

Creates a role and specifies its privileges. The role applies to the database on which you run the method. The db.createRole() method returns a duplicate role error if the role already exists in the database.

The db.createRole() method takes the following arguments:

Parameter | Description
writeConcern | Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.
role | A document containing the name of the role and the role definition.

param document writeConcern:
| Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.
param document role:
| A document containing the name of the role and the role definition.

The role document has the following form:

{ role: "<name>",
  privileges: [
     { resource: { <resource> }, actions: [ "<action>", ... ] },
     ...
  ],
  roles: [
     { role: "<role>", db: "<database>" } | "<role>",
      ...
  ]
}

The role document has the following fields:

Field | Description
privileges | The privileges to grant the role. A privilege consists of a resource and permitted actions. You must specify the privileges field. Use an empty array to specify no privileges. For the syntax of a privilege, see the privileges array.
roles | An array of roles from which this role inherits privileges. You must specify the roles field. Use an empty array to specify no roles.
role | The name of the new role.

field array privileges:
| The privileges to grant the role. A privilege consists of a resource and permitted actions. You must specify the privileges field. Use an empty array to specify no privileges. For the syntax of a privilege, see the privileges array.
field array roles:
| An array of roles from which this role inherits privileges. You must specify the roles field. Use an empty array to specify no roles.
field string role:
| The name of the new role.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.createRole() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.createRole() method wraps the createRole command.

Behavior

A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

Required Access

To create a role in a database, the user must have:

the createRole action on that database resource.

the grantRole action on that database to specify privileges for the new role as well as to specify roles to inherit from.

Built-in roles userAdmin and userAdminAnyDatabase provide createRole and grantRole actions on their respective resources.

Example

The following db.createRole() method creates the myClusterwideAdmin role on the admin database:

use admin
db.createRole({ role: "myClusterwideAdmin",
  privileges: [
    { resource: { cluster: true }, actions: [ "addShard" ] },
    { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
    { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
    { resource: { db: "", collection: "" }, actions: [ "find" ] }
  ],
  roles: [
    { role: "read", db: "admin" }
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
})

db.updateRole()

Definition

db.updateRole(rolename, update, writeConcern)

Updates a user-defined role. The db.updateRole() method must run on the role’s database.

An update to a field completely replaces the previous field’s values. To grant or remove roles or privileges without replacing all values, use one or more of the following methods:

db.grantRolesToRole()

db.grantPrivilegesToRole()

db.revokeRolesFromRole()

db.revokePrivilegesFromRole()

Warning

An update to the privileges or roles array completely replaces the previous array’s values.

The updateRole() method uses the following syntax:

db.updateRole(
    "<rolename>",
    {
      privileges:
          [
            { resource: { <resource> }, actions: [ "<action>", ... ] },
            ...
          ],
      roles:
          [
            { role: "<role>", db: "<database>" } | "<role>",
            ...
          ]
    },
    { <writeConcern> }
)

The db.updateRole() method takes the following arguments.

Parameter | Description
writeConcern | Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.
rolename | The name of the user-defined role to update.
update | A document containing the replacement data for the role. This data completely replaces the corresponding data for the role.

param document writeConcern:
| Optional. The level of write concern for the update operation. The writeConcern document takes the same fields as the getLastError command.
param string rolename:
| The name of the user-defined role to update.
param document update:
| A document containing the replacement data for the role. This data completely replaces the corresponding data for the role.

The update document specifies the fields to update and the new values. Each field in the update document is optional, but the document must include at least one field. The update document has the following fields:

Field | Description
privileges | Optional. Required if you do not specify roles array. The privileges to grant the role. An update to the privileges array overrides the previous array’s values. For the syntax for specifying a privilege, see the privileges array.
roles | Optional. Required if you do not specify privileges array. The roles from which this role inherits privileges. An update to the roles array overrides the previous array’s values.

field array privileges:
| Optional. Required if you do not specify roles array. The privileges to grant the role. An update to the privileges array overrides the previous array’s values. For the syntax for specifying a privilege, see the privileges array.
field array roles:
| Optional. Required if you do not specify privileges array. The roles from which this role inherits privileges. An update to the roles array overrides the previous array’s values.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.updateRole() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.updateRole() method wraps the updateRole command.

Behavior

A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

Required Access

You must have the revokeRole action on all databases in order to update a role.

You must have the grantRole action on the database of each role in the roles array to update the array.

You must have the grantRole action on the database of each privilege in the privileges array to update the array. If a privilege’s resource spans databases, you must have grantRole on the admin database. A privilege spans databases if the privilege is any of the following:

a collection in all databases

all collections and all database

the cluster resource

Example

The following db.updateRole() method replaces the privileges and the roles for the inventoryControl role that exists in the products database. The method runs on the database that contains inventoryControl:

use products
db.updateRole(
    "inventoryControl",
    {
      privileges:
          [
            {
              resource: { db:"products", collection:"clothing" },
              actions: [ "update", "createCollection", "createIndex"]
            }
          ],
      roles:
          [
            {
              role: "read",
              db: "products"
            }
          ]
    },
    { w:"majority" }
)

To view a role’s privileges, use the rolesInfo command.

db.dropRole()

Definition

db.dropRole(rolename, writeConcern)

Deletes a user-defined role from the database on which you run the method.

The db.dropRole() method takes the following arguments:

Parameter | Description
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.
rolename | The name of the user-defined role to remove from the database.

param document writeConcern:
| Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.
param string rolename:
| The name of the user-defined role to remove from the database.

The db.dropRole() method wraps the dropRole command.

Required Access

You must have the dropRole action on a database to drop a role from that database.

Example

The following operations remove the readPrices role from the products database:

use products
db.dropRole( "readPrices", { w: "majority" } )

db.dropAllRoles()

Definition

db.dropAllRoles(writeConcern)

Deletes all user-defined roles on the database where you run the method.

Warning

The dropAllRoles method removes all user-defined roles from the database.

The dropAllRoles method takes the following argument:

Field | Description
writeConcern | Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

field document writeConcern:

Optional. The level of write concern for the removal operation. The writeConcern document takes the same fields as the getLastError command.

Returns:
The number of user-defined roles dropped.

The db.dropAllRoles() method wraps the dropAllRolesFromDatabase command.

Required Access

You must have the dropRole action on a database to drop a role from that database.

Example

The following operations drop all user-defined roles from the products database and uses a write concern of majority.

use products
db.dropAllRoles( { w: "majority" } )

The method returns the number of roles dropped:

4

db.grantPrivilegesToRole()

Definition

db.grantPrivilegesToRole(rolename, privileges, writeConcern)

Grants additional privileges to a user-defined role.

The grantPrivilegesToRole() method uses the following syntax:

db.grantPrivilegesToRole(
    "< rolename >",
    [
        { resource: { <resource> }, actions: [ "<action>", ... ] },
        ...
    ],
    { < writeConcern > }
)

The grantPrivilegesToRole() method takes the following arguments:

Parameter | Description
privileges | The privileges to add to the role. For the format of a privilege, see privileges.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
rolename | The name of the role to grant privileges to.

param array privileges:
| The privileges to add to the role. For the format of a privilege, see privileges.
param document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
param string rolename:
| The name of the role to grant privileges to.

The grantPrivilegesToRole() method can grant one or more privileges. Each <privilege> has the following syntax:

{ resource: { <resource> }, actions: [ "<action>", ... ] }

The db.grantPrivilegesToRole() method wraps the grantPrivilegesToRole command.

Behavior

A role’s privileges apply to the database where the role is created. A role created on the admin database can include privileges that apply to all databases or to the cluster.

Required Access

You must have the grantRole action on the database a privilege targets in order to grant the privilege. To grant a privilege on multiple databases or on the cluster resource, you must have the grantRole action on the admin database.

Example

The following db.grantPrivilegesToRole() operation grants two additional privileges to the role inventoryCntrl01, which exists on the products database. The operation is run on that database:

use products
db.grantPrivilegesToRole(
  "inventoryCntrl01",
  [
    {
      resource: { db: "products", collection: "" },
      actions: [ "insert" ]
    },
    {
      resource: { db: "products", collection: "system.indexes" },
      actions: [ "find" ]
    }
  ],
  { w: "majority" }
)

The first privilege permits users with this role to perform the insert action on all collections of the products database, except the system collections. To access a system collection, a privilege must explicitly specify the system collection in the resource document, as in the second privilege.

The second privilege permits users with this role to perform the find action on the product database’s system collection named system.indexes.

db.revokePrivilegesFromRole()

Definition

db.revokePrivilegesFromRole(rolename, privileges, writeConcern)

Removes the specified privileges from the user-defined role on the database where the method runs. The revokePrivilegesFromRole method has the following syntax:

db.revokePrivilegesFromRole(
    "<rolename>",
    [
        { resource: { <resource> }, actions: [ "<action>", ... ] },
        ...
    ],
    { <writeConcern> }
)

The revokePrivilegesFromRole method takes the following arguments:

Parameter | Description
privileges | An array of privileges to remove from the role. See privileges for more information on the format of the privileges.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
rolename | The name of the user-defined role from which to revoke privileges.

param array privileges:
| An array of privileges to remove from the role. See privileges for more information on the format of the privileges.
param document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
param string rolename:
| The name of the user-defined role from which to revoke privileges.

The db.revokePrivilegesFromRole() method wraps the revokePrivilegesFromRole command.

Behavior

To revoke a privilege, the resource document pattern must match exactly the resource field of that privilege. The actions field can be a subset or match exactly.

For example, given the role accountRole in the products database with the following privilege that specifies the products database as the resource:

{
  "resource" : {
      "db" : "products",
      "collection" : ""
  },
  "actions" : [
      "find",
      "update"
  ]
}

You cannot revoke find and/or update from just one collection in the products database. The following operations result in no change to the role:

use products
db.revokePrivilegesFromRole(
   "accountRole",
   [
     {
       resource : {
          db : "products",
          collection : "gadgets"
       },
       actions : [
          "find",
          "update"
       ]
     }
   ]
)

db.revokePrivilegesFromRole(
   "accountRole",
   [
     {
       resource : {
          db : "products",
          collection : "gadgets"
       },
       actions : [
          "find"
       ]
     }
   ]
)

To revoke the "find" and/or the "update" action from the role accountRole, you must match the resource document exactly. For example, the following operation revokes just the "find" action from the existing privilege.

use products
db.revokePrivilegesFromRole(
   "accountRole",
   [
     {
       resource : {
          db : "products",
          collection : ""
       },
       actions : [
          "find"
       ]
     }
   ]
)

Required Access

You must have the revokeRole action on the database a privilege targets in order to revoke that privilege. If the privilege targets multiple databases or the cluster resource, you must have the revokeRole action on the admin database.

Example

The following operation removes multiple privileges from the associates role:

db.revokePrivilegesFromRole(
   "associate",
   [
     {
       resource: { db: "products", collection: "" },
       actions: [ "createCollection", "createIndex", "find" ]
     },
     {
       resource: { db: "products", collection: "orders" },
       actions: [ "insert" ]
     }
   ],
   { w: "majority" }
)

db.grantRolesToRole()

Definition

db.grantRolesToRole(rolename, roles, writeConcern)

Grants roles to a user-defined role.

The grantRolesToRole method uses the following syntax:

db.grantRolesToRole( "<rolename>", [ <roles> ], { <writeConcern> } )

The grantRolesToRole method takes the following arguments:

Parameter | Description
roles | An array of roles from which to inherit.
writeConcern | Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
rolename | The name of the role to which to grant sub roles.

param array roles:
| An array of roles from which to inherit.
param document writeConcern:
| Optional. The level of write concern for the modification. The writeConcern document takes the same fields as the getLastError command.
param string rolename:
| The name of the role to which to grant sub roles.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.grantRolesToRole() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.grantRolesToRole() method wraps the grantRolesToRole command.

Behavior

A role can inherit privileges from other roles in its database. A role created on the admin database can inherit privileges from roles in any database.

Required Access

You must have the grantRole action on a database to grant a role on that database.

Example

The following grantRolesToRole() operation updates the productsReaderWriter role in the products database to inherit the privileges of productsReader role:

use products
db.grantRolesToRole(
    "productsReaderWriter",
    [ "productsReader" ],
    { w: "majority" , wtimeout: 5000 }
)

db.revokeRolesFromRole()

Definition

db.revokeRolesFromRole(rolename, roles, writeConcern)

Removes the specified inherited roles from a role.

The revokeRolesFromRole method uses the following syntax:

db.revokeRolesFromRole( "<rolename>", [ <roles> ], { <writeConcern> } )

The revokeRolesFromRole method takes the following arguments:

Parameter | Description
roles | The inherited roles to remove.
writeConcern | Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.
rolename | The name of the role from which to revoke roles.

param array roles:
| The inherited roles to remove.
param document writeConcern:
| Optional. The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.
param string rolename:
| The name of the role from which to revoke roles.

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.revokeRolesFromRole() runs, you can either specify the role with the name of the role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role with a document.

The db.revokeRolesFromRole() method wraps the revokeRolesFromRole command.

Required Access

You must have the revokeRole action on a database to revoke a role on that database.

Example

The purchaseAgents role in the emea database inherits privileges from several other roles, as listed in the roles array:

{
   "_id" : "emea.purchaseAgents",
   "role" : "purchaseAgents",
   "db" : "emea",
   "privileges" : [],
   "roles" : [
      {
         "role" : "readOrdersCollection",
         "db" : "emea"
      },
      {
         "role" : "readAccountsCollection",
         "db" : "emea"
      },
      {
         "role" : "writeOrdersCollection",
         "db" : "emea"
      }
   ]
}

The following db.revokeRolesFromRole() operation on the emea database removes two roles from the purchaseAgents role:

use emea
db.revokeRolesFromRole( "purchaseAgents",
                        [
                          "writeOrdersCollection",
                          "readOrdersCollection"
                        ],
                        { w: "majority" , wtimeout: 5000 }
                      )

The purchaseAgents role now contains just one role:

{
   "_id" : "emea.purchaseAgents",
   "role" : "purchaseAgents",
   "db" : "emea",
   "privileges" : [],
   "roles" : [
      {
         "role" : "readAccountsCollection",
         "db" : "emea"
      }
   ]
}

db.getRole()

Definition

db.getRole(rolename, showPrivileges)

Returns the roles from which this role inherits privileges. Optionally, the method can also return all the role’s privileges.

Run db.getRole() from the database that contains the role. The command can retrieve information for both user-defined roles and built-in roles.

The db.getRole() method takes the following arguments:

Parameter | Description
rolename | The name of the role.
showPrivileges | Optional. If true, returns the role’s privileges. Pass this argument as a document: {showPrivileges: true}.

param string rolename:
| The name of the role.
param document showPrivileges:
| Optional. If true, returns the role’s privileges. Pass this argument as a document: {showPrivileges: true}.

db.getRole() wraps the rolesInfo command.

Required Access

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Examples

The following operation returns role inheritance information for the role associate defined on the products database:

use products
db.getRole( "associate" )

The following operation returns role inheritance information and privileges for the role associate defined on the products database:

use products
db.getRole( "associate", { showPrivileges: true } )

db.getRoles()

Definition

db.getRoles()

Returns information for all the roles in the database on which the command runs. The method can be run with or without an argument.

If run without an argument, db.getRoles() returns inheritance information for the database’s user-defined roles.

To return more information, pass the db.getRoles() a document with the following fields:

Field | Description
showPrivileges | Optional. Set the field to true to show role privileges, including both privileges inherited from other roles and privileges defined directly. By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.
rolesInfo | Set this field to 1 to retrieve all user-defined roles.
showBuiltinRoles | Optional. Set to true to display built-in roles as well as user-defined roles.

field Boolean showPrivileges:
| Optional. Set the field to true to show role privileges, including both privileges inherited from other roles and privileges defined directly. By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.
field integer rolesInfo:
| Set this field to 1 to retrieve all user-defined roles.
field Boolean showBuiltinRoles:
| Optional. Set to true to display built-in roles as well as user-defined roles.

db.getRoles() wraps the rolesInfo command.

Required Access

To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Example

The following operations return documents for all the roles on the products database, including role privileges and built-in roles:

db.getRoles(
    {
      rolesInfo: 1,
      showPrivileges:true,
      showBuiltinRoles: true
    }
)

Replication Methods

Name | Description
rs.add() | Adds a member to a replica set.
rs.addArb() | Adds an arbiter to a replica set.
rs.conf() | Returns the replica set configuration document.
rs.freeze() | Prevents the current member from seeking election as primary for a period of time.
rs.help() | Returns basic help text for replica set functions.
rs.initiate() | Initializes a new replica set.
rs.printReplicationInfo() | Prints a report of the status of the replica set from the perspective of the primary.
rs.printSlaveReplicationInfo() | Prints a report of the status of the replica set from the perspective of the secondaries.
rs.reconfig() | Re-configures a replica set by applying a new replica set configuration object.
rs.remove() | Remove a member from a replica set.
rs.slaveOk() | Sets the slaveOk property for the current connection. Deprecated. Use readPref() and Mongo.setReadPref() to set read preference.
rs.status() | Returns a document with information about the state of the replica set.
rs.stepDown() | Causes the current primary to become a secondary which forces an election.
rs.syncFrom() | Sets the member that this replica set member will sync from, overriding the default sync target selection logic.

rs.add()

rs.addArb()

rs.conf()

rs.freeze()

rs.help()

rs.initiate()

rs.printReplicationInfo()

rs.printSlaveReplicationInfo()

rs.reconfig()

rs.remove()

rs.slaveOk()

rs.status()

rs.stepDown()

rs.syncFrom()

rs.add()

Definition

rs.add()

Adds a member to a replica set. To run the method, you must connect to the primary of the replica set.

Parameter
Description

host

The new member to add to the replica set.

If a string, specify the hostname and optionally the port number for the new member. See Pass a Hostname String to rs.add() for an example.

If a document, specify a replica set member configuration document as found in the members array. You must specify _id and the host fields in the member configuration document. See Pass a Member Configuration Document to rs.add() for an example.

See Replica Set Configuration document for full documentation of all replica set configuration options

arbiterOnly
Optional. Applies only if the <host> value is a string. If true, the added host is an arbiter.

param string, document host:

The new member to add to the replica set.

If a string, specify the hostname and optionally the port number for the new member. See Pass a Hostname String to rs.add() for an example.

If a document, specify a replica set member configuration document as found in the members array. You must specify _id and the host fields in the member configuration document. See Pass a Member Configuration Document to rs.add() for an example.

See Replica Set Configuration document for full documentation of all replica set configuration options

param boolean arbiterOnly:

Optional. Applies only if the <host> value is a string. If true, the added host is an arbiter.

rs.add() provides a wrapper around some of the functionality of the replSetReconfig database command and the corresponding mongo shell helper rs.reconfig(). See the Replica Set Configuration document for full documentation of all replica set configuration options.

Behavior

rs.add() can, in some cases, force an election for primary which will disconnect the shell. In such cases, the mongo shell displays an error even if the operation succeeds.

Example

Pass a Hostname String to rs.add()

The following operation adds a mongod instance, running on the host mongodb3.example.net and accessible on the default port 27017:

rs.add('mongodb3.example.net:27017')

If mongodb3.example.net is an arbiter, use the following form:

rs.add('mongodb3.example.net:27017', true)

Pass a Member Configuration Document to rs.add()

The following operation adds a mongod instance, running on the host mongodb4.example.net and accessible on the default port 27017, as a priority 0 secondary member:

rs.add( { _id: 4, host: "mongodbd4.example.net:27017", priority: 0 } )

You must specify _id and the host fields in the member configuration document.

The _id value must be unique. Use rs.conf() to see the existing _id values in the replica set configuration document, and set _id to the next unused _id value in the replica set.

See the Replica Set Configuration for the available replica set member configuration settings.

See Replica Set Tutorials for more examples and information.

rs.addArb()

Description

rs.addArb(host)

Adds a new arbiter to an existing replica set.

The rs.addArb() method takes the following parameter:

Parameter | Description
host | Specifies the hostname and optionally the port number of the arbiter member to add to replica set.

param string host:

Specifies the hostname and optionally the port number of the arbiter member to add to replica set.

This function briefly disconnects the shell and forces a reconnection as the replica set renegotiates which member will be primary. As a result, the shell displays an error even if this command succeeds.

rs.conf()

rs.conf()

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

See Replica Set Configuration for more information on the replica set configuration document.

rs.config()

rs.config() is an alias of rs.conf().

rs.freeze()

Description

rs.freeze(seconds)

Makes the current replica set member ineligible to become primary for the period specified.

The rs.freeze() method has the following parameter:

Parameter | Description
seconds | The duration the member is ineligible to become primary.

param number seconds:

The duration the member is ineligible to become primary.

rs.freeze() provides a wrapper around the database command replSetFreeze.

rs.help()

rs.help()

Returns a basic help text for all of the replication related shell functions.

rs.initiate()

Description

rs.initiate(configuration)

Initiates a replica set. Optionally takes a configuration argument in the form of a document that holds the configuration of a replica set.

The rs.initiate() method has the following parameter:

Parameter | Description
configuration | Optional. A document that specifies configuration settings for the new replica set. If a configuration is not specified, MongoDB uses a default configuration.

param document configuration:

Optional. A document that specifies configuration settings for the new replica set. If a configuration is not specified, MongoDB uses a default configuration.

The rs.initiate() method provides a wrapper around the “replSetInitiate” database command.

Replica Set Configuration

See Member Configuration Tutorials and Replica Set Configuration for examples of replica set configuration and invitation objects.

rs.printReplicationInfo()

Definition

rs.printReplicationInfo()

New in version 2.6.

Prints a formatted report of the replica set member’s oplog. The displayed report formats the data returned by db.getReplicationInfo(). [1] The output of rs.printReplicationInfo() is identical to that of db.printReplicationInfo().

Note

The rs.printReplicationInfo() in the mongo shell does not return JSON. Use rs.printReplicationInfo() for manual inspection, and db.getReplicationInfo() in scripts.

Output Example

The following example is a sample output from the rs.printReplicationInfo() method run on the primary:

configured oplog size:   192MB
log length start to end: 65422secs (18.17hrs)
oplog first event time:  Mon Jun 23 2014 17:47:18 GMT-0400 (EDT)
oplog last event time:   Tue Jun 24 2014 11:57:40 GMT-0400 (EDT)
now:                     Thu Jun 26 2014 14:24:39 GMT-0400 (EDT)

Output Fields

rs.printReplicationInfo() formats and prints the data returned by db.getReplicationInfo():

configured oplog size

Displays the db.getReplicationInfo.logSizeMB value.

log length start to end

Displays the db.getReplicationInfo.timeDiff and db.getReplicationInfo.timeDiffHours values.

oplog first event time

Displays the db.getReplicationInfo.tFirst.

oplog last event time

Displays the db.getReplicationInfo.tLast.

now

Displays the db.getReplicationInfo.now.

See db.getReplicationInfo() for description of the data.

[1]
If run on a slave of a master-slave replication, the method calls db.printSlaveReplicationInfo(). See db.printSlaveReplicationInfo() for details.

rs.printSlaveReplicationInfo()

Definition

rs.printSlaveReplicationInfo()

Returns a formatted report of the status of a replica set from the perspective of the secondary member of the set. The output is identical to that of db.printSlaveReplicationInfo().

Output

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

source: m1.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary
source: m2.example.net:27017
    syncedTo: Thu Apr 10 2014 10:27:47 GMT-0400 (EDT)
    0 secs (0 hrs) behind the primary

A delayed member may show as 0 seconds behind the primary when the inactivity period on the primary is greater than the slaveDelay value.

rs.reconfig()

Definition

rs.reconfig(configuration, force)

Reconfigures an existing replica set, overwriting the existing replica set configuration. To run the method, you must connect to the primary of the replica set.

Parameter | Description
configuration | A document that specifies the configuration of a replica set.
force | Optional. If set as { force: true }, this forces the replica set to accept the new configuration even if a majority of the members are not accessible. Use with caution, as this can lead to rollback situations.

param document configuration:
| A document that specifies the configuration of a replica set.
param document force:
| Optional. If set as { force: true }, this forces the replica set to accept the new configuration even if a majority of the members are not accessible. Use with caution, as this can lead to rollback situations.

When used to reconfigure an existing replica set, first retrieve the current configuration with rs.conf(), modify the configuration document as needed, and then pass the modified document to rs.reconfig().

rs.reconfig() provides a wrapper around the replSetReconfig database command.

Behavior

The method disconnects the mongo shell and forces a reconnection as the replica set renegotiates which member will be primary. As a result, the shell will display an error even if this command succeeds.

The rs.reconfig() shell method can force the current primary to step down and triggers an election in some situations. When the primary steps down, the primary closes all client connections. This is by design. Since this typically takes 10-20 seconds, attempt to make such changes during scheduled maintenance periods.

Warning

Using rs.reconfig() with { force: true } can lead to rollback situations and other difficult-to-recover-from situations. Exercise caution when using this option.

Examples

A replica set named rs0 has the following configuration:

{
    "_id" : "rs0",
    "version" : 1,
    "members" : [
         {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
         },
         {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017"
         },
         {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
         }
     ]
}

The following sequence of operations updates the priority of the second member. The operations are issued through a mongo shell connected to the primary.

cfg = rs.conf();
cfg.members[1].priority = 2;
rs.reconfig(cfg);

The first statement uses the rs.conf() method to retrieve a document containing the current configuration for the replica set and sets the document to the local variable cfg.

The second statement sets a priority value to the second document in the members array. For additional settings, see replica set configuration settings.

To access the member configuration document in the array, the statement uses the array index and not the replica set member’s _id field.

The last statement calls the rs.reconfig() method with the modified cfg to initialize this new configuration. Upon successful reconfiguration, the replica set configuration will resemble the following:

{
    "_id" : "rs0",
    "version" : 2,
    "members" : [
         {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
         },
         {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017",
            "priority" : 2
         },
         {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
         }
     ]
}

See also

Replica Set Configuration and Replica Set Tutorials.

rs.remove()

Definition

rs.remove(hostname)

Removes the member described by the hostname parameter from the current replica set. This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which member will be primary. As a result, the shell will display an error even if this command succeeds.

The rs.remove() method has the following parameter:

Parameter | Description
hostname | The hostname of a system in the replica set.

param string hostname:

The hostname of a system in the replica set.

Note

Before running the rs.remove() operation, you must shut down the replica set member that you’re removing.

Changed in version 2.2: This procedure is no longer required when using rs.remove(), but it remains good practice.

rs.slaveOk()

rs.slaveOk()

Provides a shorthand for the following operation:

db.getMongo().setSlaveOk()

This allows the current connection to allow read operations to run on secondary members. See the readPref() method for more fine-grained control over read preference in the mongo shell.

rs.status()

rs.status()

Returns:
A document with status information.

This output reflects the current status of the replica set, using data derived from the heartbeat packets sent by the other members of the replica set.

This method provides a wrapper around the replSetGetStatus command. See the documentation of the command for a complete description of the output.

rs.stepDown()

Description

rs.stepDown(seconds)

Forces the current replica set member to step down as primary and then attempt to avoid election as primary for the designated number of seconds. Produces an error if the current member is not the primary.

The rs.stepDown() method has the following parameter:

Parameter | Description
seconds | Optional. The duration of time that the stepped-down member attempts to avoid reelection as primary. If this parameter is not specified, the method uses the default value of 60 seconds.

param number seconds:

Optional. The duration of time that the stepped-down member attempts to avoid reelection as primary. If this parameter is not specified, the method uses the default value of 60 seconds.

This function disconnects the shell briefly and forces a reconnection as the replica set renegotiates which member will be primary. As a result, the shell will display an error even if this command succeeds.

rs.stepDown() provides a wrapper around the database command replSetStepDown.

rs.syncFrom()

rs.syncFrom()

New in version 2.2.

Provides a wrapper around the replSetSyncFrom, which allows administrators to configure the member of a replica set that the current member will pull data from. Specify the name of the member you want to replicate from in the form of [hostname]:[port].

See replSetSyncFrom for more details.

See Configure a Secondary’s Sync Target for details how to use this command.

Sharding Methods

Name | Description
sh._adminCommand | Runs a database command against the admin database, like db.runCommand(), but can confirm that it is issued against a mongos.
sh._checkFullName() | Tests a namespace to determine if its well formed.
sh._checkMongos() | Tests to see if the mongo shell is connected to a mongos instance.
sh._lastMigration() | Reports on the last chunk migration.
sh.addShard() | Adds a shard to a sharded cluster.
sh.addShardTag() | Associates a shard with a tag, to support tag aware sharding.
sh.addTagRange() | Associates range of shard keys with a shard tag, to support tag aware sharding.
sh.disableBalancing() | Disable 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 sh.disableBalancing().
sh.enableSharding() | Enables sharding on a specific database.
sh.getBalancerHost() | Returns the name of a mongos that’s responsible for the balancer process.
sh.getBalancerState() | Returns a boolean to report if the balancer is currently enabled.
sh.help() | Returns help text for the sh methods.
sh.isBalancerRunning() | Returns a boolean to report if the balancer process is currently migrating chunks.
sh.moveChunk() | Migrates a chunk in a sharded cluster.
sh.removeShardTag() | Removes the association between a shard and a shard tag.
sh.setBalancerState() | Enables or disables the balancer which migrates chunks between shards.
sh.shardCollection() | Enables sharding for a collection.
sh.splitAt() | Divides an existing chunk into two chunks using a specific value of the shard key as the dividing point.
sh.splitFind() | Divides an existing chunk that contains a document matching a query into two approximately equal chunks.
sh.startBalancer() | Enables the balancer and waits for balancing to start.
sh.status() | Reports on the status of a sharded cluster, as db.printShardingStatus().
sh.stopBalancer() | Disables the balancer and waits for any in progress balancing rounds to complete.
sh.waitForBalancer() | Internal. Waits for the balancer state to change.
sh.waitForBalancerOff() | Internal. Waits until the balancer stops running.
sh.waitForDLock() | Internal. Waits for a specified distributed sharded cluster lock.
sh.waitForPingChange() | Internal. Waits for a change in ping state from one of the mongos in the sharded cluster.

sh._adminCommand()

sh._checkFullName()

sh._checkMongos()

sh._lastMigration()

sh.addShard()

sh.addShardTag()

sh.addTagRange()

sh.disableBalancing()

sh.enableBalancing()

sh.enableSharding()

sh.getBalancerHost()

sh.getBalancerState()

sh.help()

sh.isBalancerRunning()

sh.moveChunk()

sh.removeShardTag()

sh.setBalancerState()

sh.shardCollection()

sh.splitAt()

sh.splitFind()

sh.startBalancer()

sh.status()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.waitForDLock()

sh.waitForPingChange()

sh._adminCommand()

Definition

sh._adminCommand(command, checkMongos)

Runs a database command against the admin database of a mongos instance.

Parameter | Description
command | A database command to run against the admin database.
checkMongos | Require verification that the shell is connected to a mongos instance.

param string command:
| A database command to run against the admin database.
param boolean checkMongos:
| Require verification that the shell is connected to a mongos instance.

See also

db.runCommand()

sh._checkFullName()

Definition

sh._checkFullName(namespace)

Verifies that a namespace name is well formed. If the namespace is well formed, the sh._checkFullName() method exits with no message.

Throws:
If the namespace is not well formed, sh._checkFullName() throws: “name needs to be fully qualified <db>.<collection>”

The sh._checkFullName() method has the following parameter:

Parameter | Description
namespace | The namespace of a collection. The namespace is the combination of the database name and the collection name. Enclose the namespace in quotation marks.

param string namespace:

The namespace of a collection. The namespace is the combination of the database name and the collection name. Enclose the namespace in quotation marks.

sh._checkMongos()

sh._checkMongos()

Returns: | nothing
Throws: | “not connected to a mongos”

The sh._checkMongos() method throws an error message if the mongo shell is not connected to a mongos instance. Otherwise it exits (no return document or return code).

sh._lastMigration()

Definition

sh._lastMigration(namespace)

Returns information on the last migration performed on the specified database or collection.

The sh._lastMigration() method has the following parameter:

Parameter | Description
namespace | The namespace of a database or collection within the current database.

param string namespace:

The namespace of a database or collection within the current database.

Output

The sh._lastMigration() method returns a document with details about the last migration performed on the database or collection. The document contains the following output:

sh._lastMigration._id

The id of the migration task.

sh._lastMigration.server

The name of the server.

sh._lastMigration.clientAddr

The IP address and port number of the server.

sh._lastMigration.time

The time of the last migration, formatted as ISODate.

sh._lastMigration.what

The specific type of migration.

sh._lastMigration.ns

The complete namespace of the collection affected by the migration.

sh._lastMigration.details

A document containing details about the migrated chunk. The document includes min and max embedded documents with the bounds of the migrated chunk.

sh.addShard()

Definition

sh.addShard(host)

Adds a database instance or replica set to a sharded cluster. The optimal configuration is to deploy shards across replica sets. This method must be run on a mongos instance.

The sh.addShard() method has the following parameter:

Parameter | Description
host | The hostname of either a standalone database instance or of a replica set. Include the port number if the instance is running on a non-standard port. Include the replica set name if the instance is a replica set, as explained below.

param string host:

The hostname of either a standalone database instance or of a replica set. Include the port number if the instance is running on a non-standard port. Include the replica set name if the instance is a replica set, as explained below.

The sh.addShard() method has the following prototype form:

sh.addShard("<host>")

The host parameter can be in any of the following forms:

[hostname]
[hostname]:[port]
[replica-set-name]/[hostname]
[replica-set-name]/[hostname]:port

Warning

Do not use localhost for the hostname unless your configuration server is also running on localhost.

New in version 2.6: mongos installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

The sh.addShard() method is a helper for the addShard command. The addShard command has additional options which are not available with this helper.

Considerations

Balancing

When you add a shard to a sharded cluster, you affect the balance of chunks among the shards of a cluster for all existing sharded collections. The balancer will begin migrating chunks so that the cluster will achieve balance. See Sharded Collection Balancing for more information.

Hidden Members

Important

You cannot include a hidden member in the seed list provided to sh.addShard().

Example

To add a shard on a replica set, specify the name of the replica set and the hostname of at least one member of the replica set, as a seed. If you specify additional hostnames, all must be members of the same replica set.

The following example adds a replica set named repl0 and specifies one member of the replica set:

sh.addShard("repl0/mongodb3.example.net:27327")

sh.addShardTag()

Definition

sh.addShardTag(shard, tag)

New in version 2.2.

Associates a shard with a tag or identifier. MongoDB uses these identifiers to direct chunks that fall within a tagged range to specific shards. sh.addTagRange() associates chunk ranges with tag ranges.

Parameter | Description
shard | The name of the shard to which to give a specific tag.
tag | The name of the tag to add to the shard.

param string shard:
| The name of the shard to which to give a specific tag.
param string tag:
| The name of the tag to add to the shard.

Only issue sh.addShardTag() when connected to a mongos instance.

Example

The following example adds three tags, NYC, LAX, and NRT, to three shards:

sh.addShardTag("shard0000", "NYC")
sh.addShardTag("shard0001", "LAX")
sh.addShardTag("shard0002", "NRT")

See also

sh.addTagRange() and sh.removeShardTag().

sh.addTagRange()

Definition

sh.addTagRange(namespace, minimum, maximum, tag)

New in version 2.2.

Attaches a range of shard key values to a shard tag created using the sh.addShardTag() method. sh.addTagRange() takes the following arguments:

Parameter | Description
namespace | The namespace of the sharded collection to tag.
minimum | The minimum value of the shard key range to include in the tag. The minimum is an inclusive match. Specify the minimum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
maximum | The maximum value of the shard key range to include in the tag. The maximum is an exclusive match. Specify the maximum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
tag | The name of the tag to attach the range specified by the minimum and maximum arguments to.

param string namespace:
| The namespace of the sharded collection to tag.
param document minimum:
| The minimum value of the shard key range to include in the tag. The minimum is an inclusive match. Specify the minimum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
param document maximum:
| The maximum value of the shard key range to include in the tag. The maximum is an exclusive match. Specify the maximum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
param string tag:
| The name of the tag to attach the range specified by the minimum and maximum arguments to.

Use sh.addShardTag() to ensure that the balancer migrates documents that exist within the specified range to a specific shard or set of shards.

Only issue sh.addTagRange() when connected to a mongos instance.

Behavior

Bounds

Shard ranges are always inclusive of the lower value and exclusive of the upper boundary.

Dropped Collections

If you add a tag range to a collection using sh.addTagRange() and then later drop the collection or its database, MongoDB does not remove the tag association. If you later create a new collection with the same name, the old tag association will apply to the new collection.

Example

Given a shard key of {state: 1, zip: 1}, the following operation creates a tag range covering zip codes in New York State:

sh.addTagRange( "exampledb.collection",
                { state: "NY", zip: MinKey },
                { state: "NY", zip: MaxKey },
                "NY"
              )

sh.disableBalancing()

Description

sh.disableBalancing(namespace)

Disables the balancer for the specified sharded collection. This does not affect the balancing of chunks for other sharded collections in the same cluster.

The sh.disableBalancing() method has the following parameter:

Parameter | Description
namespace | The namespace of the collection.

param string namespace:

The namespace of the collection.

For more information on the balancing process, see Manage Sharded Cluster Balancer and Sharded Collection Balancing.

sh.enableBalancing()

Description

sh.enableBalancing(namespace)

Enables the balancer for the specified namespace of the sharded collection.

The sh.enableBalancing() method has the following parameter:

Parameter | Description
namespace | The namespace of the collection.

param string namespace:

The namespace of the collection.

Important

sh.enableBalancing() does not start balancing. Rather, it allows balancing of this collection the next time the balancer runs.

For more information on the balancing process, see Manage Sharded Cluster Balancer and Sharded Collection Balancing.

sh.enableSharding()

Definition

sh.enableSharding(database)

Enables sharding on the specified database. This does not automatically shard any collections but makes it possible to begin sharding collections using sh.shardCollection().

The sh.enableSharding() method has the following parameter:

Parameter | Description
database | The name of the database shard. Enclose the name in quotation marks.

param string database:

The name of the database shard. Enclose the name in quotation marks.

See also

sh.shardCollection()

sh.getBalancerHost()

sh.getBalancerHost()

Returns:
String in form hostname:port

sh.getBalancerHost() returns the name of the server that is running the balancer.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerState()

sh.isBalancerRunning()

sh.setBalancerState()

sh.startBalancer()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.getBalancerState()

sh.getBalancerState()

Returns:
boolean

sh.getBalancerState() returns true when the balancer is enabled and false if the balancer is disabled. This does not reflect the current state of balancing operations: use sh.isBalancerRunning() to check the balancer’s current state.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.isBalancerRunning()

sh.setBalancerState()

sh.startBalancer()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.help()

sh.help()

Returns:
a basic help text for all sharding related shell functions.

sh.isBalancerRunning()

sh.isBalancerRunning()

Returns:
boolean

Returns true if the balancer process is currently running and migrating chunks and false if the balancer process is not running. Use sh.getBalancerState() to determine if the balancer is enabled or disabled.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.getBalancerState()

sh.setBalancerState()

sh.startBalancer()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.moveChunk()

Definition

sh.moveChunk(namespace, query, destination)

Moves the chunk that contains the document specified by the query to the destination shard. sh.moveChunk() provides a wrapper around the moveChunk database command and takes the following arguments:

Parameter | Description
namespace | The namespace of the sharded collection that contains the chunk to migrate.
query | An equality match on the shard key that selects the chunk to move.
destination | The name of the shard to move.

param string namespace:
| The namespace of the sharded collection that contains the chunk to migrate.
param document query:
| An equality match on the shard key that selects the chunk to move.
param string destination:
| The name of the shard to move.

Important

In most circumstances, allow the balancer to automatically migrate chunks, and avoid calling sh.moveChunk() directly.

See also

moveChunk, sh.splitAt(), sh.splitFind(), Sharding, and chunk migration.

Example

Given the people collection in the records database, the following operation finds the chunk that contains the documents with the zipcode field set to 53187 and then moves that chunk to the shard named shard0019:

sh.moveChunk("records.people", { zipcode: "53187" }, "shard0019")

sh.removeShardTag()

Definition

sh.removeShardTag(shard, tag)

New in version 2.2.

Removes the association between a tag and a shard. Only issue sh.removeShardTag() when connected to a mongos instance.

Parameter | Description
shard | The name of the shard from which to remove a tag.
tag | The name of the tag to remove from the shard.

param string shard:
| The name of the shard from which to remove a tag.
param string tag:
| The name of the tag to remove from the shard.

See also

sh.addShardTag(), sh.addTagRange()

sh.setBalancerState()

Description

sh.setBalancerState(state)

Enables or disables the balancer. Use sh.getBalancerState() to determine if the balancer is currently enabled or disabled and sh.isBalancerRunning() to check its current state.

The sh.getBalancerState() method has the following parameter:

Parameter | Description
state | Set this to true to enable the balancer and false to disable it.

param Boolean state:

Set this to true to enable the balancer and false to disable it.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.getBalancerState()

sh.isBalancerRunning()

sh.startBalancer()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.shardCollection()

Definition

sh.shardCollection(namespace, key, unique)

Shards a collection using the key as a the shard key. sh.shardCollection() takes the following arguments:

Parameter | Description
namespace | The namespace of the collection to shard.
key | A document that specifies the shard key to use to partition and distribute objects among the shards. A shard key may be one field or multiple fields. A shard key with multiple fields is called a “compound shard key.”
unique | When true, ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints.

param string namespace:
| The namespace of the collection to shard.
param document key:
| A document that specifies the shard key to use to partition and distribute objects among the shards. A shard key may be one field or multiple fields. A shard key with multiple fields is called a “compound shard key.”
param Boolean unique:
| When true, ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints.

New in version 2.4: Use the form {field: "hashed"} to create a hashed shard key. Hashed shard keys may not be compound indexes.

Considerations

MongoDB provides no method to deactivate sharding for a collection after calling shardCollection. Additionally, after shardCollection, you cannot change shard keys or modify the value of any field used in your shard key index.

Example

Given the people collection in the records database, the following command shards the collection by the zipcode field:

sh.shardCollection("records.people", { zipcode: 1} )

Additional Information

shardCollection for additional options, Sharding and Sharding Introduction for an overview of sharding, Deploy a Sharded Cluster for a tutorial, and Shard Keys for choosing a shard key.

sh.splitAt()

Definition

sh.splitAt(namespace, query)

Splits a chunk at the shard key value specified by the query.

The method takes the following arguments:

Parameter | Description
namespace | The namespace (i.e. <database>.<collection>) of the sharded collection that contains the chunk to split.
query | A query document that specifies the shard key value at which to split the chunk.

param string namespace:
| The namespace (i.e. <database>.<collection>) of the sharded collection that contains the chunk to split.
param document query:
| A query document that specifies the shard key value at which to split the chunk.

Consideration

In most circumstances, you should leave chunk splitting to the automated processes within MongoDB. However, when initially deploying a sharded cluster, it may be beneficial to pre-split manually an empty collection using methods such as sh.splitAt().

Behavior

sh.splitAt() splits the original chunk into two chunks. One chunk has a shard key range that starts with the original lower bound (inclusive) and ends at the specified shard key value (exclusive). The other chunk has a shard key range that starts with the specified shard key value (inclusive) as the lower bound and ends at the original upper bound (exclusive).

To split a chunk at its median point instead, see sh.splitFind().

sh.splitFind()

Definition

sh.splitFind(namespace, query)

Splits the chunk that contains the shard key value specified by the query at the chunk’s median point. sh.splitFind() creates two roughly equal chunks. To split a chunk at a specific point instead, see sh.splitAt().

The method takes the following arguments:

Parameter | Description
namespace | The namespace (i.e. <database>.<collection>) of the sharded collection that contains the chunk to split.
query | A query document that specifies the shard key value that determines the chunk to split.

param string namespace:
| The namespace (i.e. <database>.<collection>) of the sharded collection that contains the chunk to split.
param document query:
| A query document that specifies the shard key value that determines the chunk to split.

Consideration

In most circumstances, you should leave chunk splitting to the automated processes within MongoDB. However, when initially deploying a sharded cluster, it may be beneficial to pre-split manually an empty collection using methods such as sh.splitFind().

sh.startBalancer()

Definition

sh.startBalancer(timeout, interval)

Enables the balancer in a sharded cluster and waits for balancing to initiate.

Parameter | Description
timeout | Milliseconds to wait.
interval | Milliseconds to sleep each cycle of waiting.

param integer timeout:
| Milliseconds to wait.
param integer interval:
| Milliseconds to sleep each cycle of waiting.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.getBalancerState()

sh.isBalancerRunning()

sh.setBalancerState()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.status()

Definition

sh.status()

Prints a formatted report of the sharding configuration and the information regarding existing chunks in a sharded cluster. The default behavior suppresses the detailed chunk information if the total number of chunks is greater than or equal to 20.

The sh.status() method has the following parameter:

Parameter | Description
verbose | Optional. If true, the method displays details of the document distribution across chunks when you have 20 or more chunks.

param Boolean verbose:

Optional. If true, the method displays details of the document distribution across chunks when you have 20 or more chunks.

See also

db.printShardingStatus()

Output Examples

The Sharding Version section displays information on the config database:

--- Sharding Status ---
  sharding version: {
   "_id" : <num>,
   "version" : <num>,
   "minCompatibleVersion" : <num>,
   "currentVersion" : <num>,
   "clusterId" : <ObjectId>
}

The Shards section lists information on the shard(s). For each shard, the section displays the name, host, and the associated tags, if any.

shards:
 {  "_id" : <shard name1>,
    "host" : <string>,
    "tags" : [ <string> ... ]
 }
 {  "_id" : <shard name2>,
    "host" : <string>,
    "tags" : [ <string> ... ]
 }
 ...

The Databases section lists information on the database(s). For each database, the section displays the name, whether the database has sharding enabled, and the primary shard for the database.

databases:
 {  "_id" : <dbname1>,
    "partitioned" : <boolean>,
    "primary" : <string>
 }
 {  "_id" : <dbname2>,
    "partitioned" : <boolean>,
    "primary" : <string>
 }
 ...

The Sharded Collection section provides information on the sharding details for sharded collection(s). For each sharded collection, the section displays the shard key, the number of chunks per shard(s), the distribution of documents across chunks [1], and the tag information, if any, for shard key range(s).

<dbname>.<collection>
   shard key: { <shard key> : <1 or hashed> }
   chunks:
      <shard name1> <number of chunks>
      <shard name2> <number of chunks>
      ...
   { <shard key>: <min range1> } -->> { <shard key> : <max range1> } on : <shard name> <last modified timestamp>
   { <shard key>: <min range2> } -->> { <shard key> : <max range2> } on : <shard name> <last modified timestamp>
   ...
   tag: <tag1>  { <shard key> : <min range1> } -->> { <shard key> : <max range1> }
   ...

Output Fields

Sharding Version

sh.status.sharding-version._id

The _id is an identifier for the version details.

sh.status.sharding-version.version

The version is the version of the config server for the sharded cluster.

sh.status.sharding-version.minCompatibleVersion

The minCompatibleVersion is the minimum compatible version of the config server.

sh.status.sharding-version.currentVersion

The currentVersion is the current version of the config server.

sh.status.sharding-version.clusterId

The clusterId is the identification for the sharded cluster.

Shards

sh.status.shards._id

The _id displays the name of the shard.

sh.status.shards.host

The host displays the host location of the shard.

sh.status.shards.tags

The tags displays all the tags for the shard. The field only displays if the shard has tags.

Databases

sh.status.databases._id

The _id displays the name of the database.

sh.status.databases.partitioned

The partitioned displays whether the database has sharding enabled. If true, the database has sharding enabled.

sh.status.databases.primary

The primary displays the primary shard for the database.

Sharded Collection

sh.status.databases.shard-key

The shard-key displays the shard key specification document.

sh.status.databases.chunks

The chunks lists all the shards and the number of chunks that reside on each shard.

sh.status.databases.chunk-details

The chunk-details lists the details of the chunks [1]:

The range of shard key values that define the chunk,

The shard where the chunk resides, and

The last modified timestamp for the chunk.

sh.status.databases.tag

The tag lists the details of the tags associated with a range of shard key values.

[1]
(1, 2) The sharded collection section, by default, displays the chunk information if the total number of chunks is less than 20. To display the information when you have 20 or more chunks, call the sh.status() methods with the verbose parameter set to true, i.e. sh.status(true).

sh.stopBalancer()

Definition

sh.stopBalancer(timeout, interval)

Disables the balancer in a sharded cluster and waits for balancing to complete.

Parameter | Description
timeout | Milliseconds to wait.
interval | Milliseconds to sleep each cycle of waiting.

param integer timeout:
| Milliseconds to wait.
param integer interval:
| Milliseconds to sleep each cycle of waiting.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.getBalancerState()

sh.isBalancerRunning()

sh.setBalancerState()

sh.startBalancer()

sh.waitForBalancer()

sh.waitForBalancerOff()

sh.waitForBalancer()

Definition

sh.waitForBalancer(wait, timeout, interval)

Waits for a change in the state of the balancer. sh.waitForBalancer() is an internal method, which takes the following arguments:

Parameter | Description
wait | Optional. Set to true to ensure the balancer is now active. The default is false, which waits until balancing stops and becomes inactive.
timeout | Milliseconds to wait.
interval | Milliseconds to sleep.

param Boolean wait:
| Optional. Set to true to ensure the balancer is now active. The default is false, which waits until balancing stops and becomes inactive.
param integer timeout:
| Milliseconds to wait.
param integer interval:
| Milliseconds to sleep.

sh.waitForBalancerOff()

Definition

sh.waitForBalancerOff(timeout, interval)

Internal method that waits until the balancer is not running.

Parameter | Description
timeout | Milliseconds to wait.
interval | Milliseconds to sleep.

param integer timeout:
| Milliseconds to wait.
param integer interval:
| Milliseconds to sleep.

See also

sh.enableBalancing()

sh.disableBalancing()

sh.getBalancerHost()

sh.getBalancerState()

sh.isBalancerRunning()

sh.setBalancerState()

sh.startBalancer()

sh.stopBalancer()

sh.waitForBalancer()

sh.waitForDLock()

Definition

sh.waitForDLock(lockname, wait, timeout, interval)

Waits until the specified distributed lock changes state. sh.waitForDLock() is an internal method that takes the following arguments:

Parameter | Description
lockname | The name of the distributed lock.
wait | Optional. Set to true to ensure the balancer is now active. Set to false to wait until balancing stops and becomes inactive.
timeout | Milliseconds to wait.
interval | Milliseconds to sleep in each waiting cycle.

param string lockname:
| The name of the distributed lock.
param Boolean wait:
| Optional. Set to true to ensure the balancer is now active. Set to false to wait until balancing stops and becomes inactive.
param integer timeout:
| Milliseconds to wait.
param integer interval:
| Milliseconds to sleep in each waiting cycle.

sh.waitForPingChange()

Definition

sh.waitForPingChange(activePings, timeout, interval)

sh.waitForPingChange() waits for a change in ping state of one of the activepings, and only returns when the specified ping changes state.

Parameter | Description
activePings | An array of active pings from the mongos collection.
timeout | Number of milliseconds to wait for a change in ping state.
interval | Number of milliseconds to sleep in each waiting cycle.

param array activePings:
| An array of active pings from the mongos collection.
param integer timeout:
| Number of milliseconds to wait for a change in ping state.
param integer interval:
| Number of milliseconds to sleep in each waiting cycle.

Subprocess Methods

Name | Description
clearRawMongoProgramOutput() | For internal use.
rawMongoProgramOutput() | For internal use.
run() | For internal use.
runMongoProgram() | For internal use.
runProgram() | For internal use.
startMongoProgram() | For internal use.
stopMongoProgram() | For internal use.
stopMongoProgramByPid() | For internal use.
stopMongod() | For internal use.
waitMongoProgramOnPort() | For internal use.
waitProgram() | For internal use.

clearRawMongoProgramOutput()

rawMongoProgramOutput()

run()

runMongoProgram()

runProgram()

startMongoProgram()

stopMongoProgram()

stopMongoProgramByPid()

stopMongod()

waitMongoProgramOnPort()

waitProgram()

clearRawMongoProgramOutput()

clearRawMongoProgramOutput()

For internal use.

rawMongoProgramOutput()

rawMongoProgramOutput()

For internal use.

run()

run()

For internal use.

runMongoProgram()

runMongoProgram()

For internal use.

runProgram()

runProgram()

For internal use.

startMongoProgram()

_startMongoProgram()

For internal use.

stopMongoProgram()

stopMongoProgram()

For internal use.

stopMongoProgramByPid()

stopMongoProgramByPid()

For internal use.

stopMongod()

stopMongod()

For internal use.

waitMongoProgramOnPort()

waitMongoProgramOnPort()

For internal use.

waitProgram()

waitProgram()

For internal use.

Object Constructors and Methods

Name | Description
Date() | Creates a date object. By default creates a date object including the current date.
UUID() | Converts a 32-byte hexadecimal string to the UUID BSON subtype.
ObjectId.getTimestamp() | Returns the timestamp portion of an ObjectId.
ObjectId.toString() | Displays the string representation of an ObjectId.
ObjectId.valueOf() | Displays the str attribute of an ObjectId as a hexadecimal string.
WriteResult() | Wrapper around the result set from write methods.
WriteResult.hasWriteError() | Returns a boolean specifying whether the results include WriteResult.writeError.
WriteResult.hasWriteConcernError() | Returns a boolean specifying whether whether the results include WriteResult.writeConcernError.
BulkWriteResult() | Wrapper around the result set from Bulk.execute().

Date()

UUID()

ObjectId.getTimestamp()

ObjectId.toString()

ObjectId.valueOf()

WriteResult()

WriteResult.hasWriteError()

WriteResult.hasWriteConcernError()

BulkWriteResult()

Date()

Date()

Returns:
Current date, as a string.

UUID()

Definition

UUID(<string>)

Generates a BSON UUID object.

Parameter | Description
hex | Specify a 32-byte hexadecimal string to convert to the UUID BSON subtype.

param string hex:

Specify a 32-byte hexadecimal string to convert to the UUID BSON subtype.

Returns:
A BSON UUID object.

Example

Create a 32 byte hexadecimal string:

var myuuid = '0123456789abcdeffedcba9876543210'

Convert it to the BSON UUID subtype:

UUID(myuuid)
BinData(3,"ASNFZ4mrze/+3LqYdlQyEA==")

ObjectId.getTimestamp()

ObjectId.getTimestamp()

Returns:
The timestamp portion of the ObjectId() object as a Date.

In the following example, call the getTimestamp() method on an ObjectId (e.g. ObjectId("507c7f79bcf86cd7994f6c0e")):

ObjectId("507c7f79bcf86cd7994f6c0e").getTimestamp()

This will return the following output:

ISODate("2012-10-15T21:26:17Z")

ObjectId.toString()

ObjectId.toString()

Returns:
The string representation of the ObjectId() object. This value has the format of ObjectId(...).

Changed in version 2.2: In previous versions ObjectId.toString() returns the value of the ObjectId as a hexadecimal string.

In the following example, call the toString() method on an ObjectId (e.g. ObjectId("507c7f79bcf86cd7994f6c0e")):

ObjectId("507c7f79bcf86cd7994f6c0e").toString()

This will return the following string:

ObjectId("507c7f79bcf86cd7994f6c0e")

You can confirm the type of this object using the following operation:

typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString()

ObjectId.valueOf()

ObjectId.valueOf()

Returns:
The value of the ObjectId() object as a lowercase hexadecimal string. This value is the str attribute of the ObjectId() object.

Changed in version 2.2: In previous versions ObjectId.valueOf() returns the ObjectId() object.

In the following example, call the valueOf() method on an ObjectId (e.g. ObjectId("507c7f79bcf86cd7994f6c0e")):

ObjectId("507c7f79bcf86cd7994f6c0e").valueOf()

This will return the following string:

507c7f79bcf86cd7994f6c0e

You can confirm the type of this object using the following operation:

typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf()

WriteResult()

Definition

WriteResult()

A wrapper that contains the result status of the mongo shell write methods.

See

db.collection.insert(), db.collection.update(), db.collection.remove(), and db.collection.save().

Properties

The WriteResult has the following properties:

WriteResult.nInserted

The number of documents inserted, excluding upserted documents. See WriteResult.nUpserted for the number of documents inserted through an upsert.

WriteResult.nMatched

The number of documents selected for update. If the update operation results in no change to the document, e.g. $set expression updates the value to the current value, nMatched can be greater than nModified.

WriteResult.nModified

The number of existing documents updated. If the update/replacement operation results in no change to the document, such as setting the value of the field to its current value, nModified can be less than nMatched.

WriteResult.nUpserted

The number of documents inserted by an upsert.

WriteResult._id

The _id of the document inserted by an upsert. Returned only if an upsert results in an insert.

WriteResult.nRemoved

The number of documents removed.

WriteResult.writeError

A document that contains information regarding any error, excluding write concern errors, encountered during the write operation.

WriteResult.writeError.code

An integer value identifying the error.

WriteResult.writeError.errmsg

A description of the error.

WriteResult.writeConcernError

A document that contains information regarding any write concern errors encountered during the write operation.

WriteResult.writeConcernError.code

An integer value identifying the write concern error.

WriteResult.writeConcernError.errInfo

A document identifying the write concern setting related to the error.

WriteResult.writeError.errmsg

A description of the error.

See also

WriteResult.hasWriteError(), WriteResult.hasWriteConcernError()

WriteResult.hasWriteError()

Definition

WriteResult.hasWriteError()

Returns true if the result of a mongo shell write method has WriteResult.writeError. Otherwise, the method returns false.

See also

WriteResult()

WriteResult.hasWriteConcernError()

Definition

WriteResult.hasWriteConcernError()

Returns true if the result of a mongo shell write method has WriteResult.writeConcernError. Otherwise, the method returns false.

See also

WriteResult()

BulkWriteResult()

BulkWriteResult()

New in version 2.6.

A wrapper that contains the results of the Bulk.execute() method.

Properties

The BulkWriteResult has the following properties:

BulkWriteResult.nInserted

The number of documents inserted using the Bulk.insert() method. For documents inserted through operations with the Bulk.find.upsert() option, see the nUpserted field instead.

BulkWriteResult.nMatched

The number of existing documents selected for update or replacement. If the update/replacement operation results in no change to an existing document, e.g. $set expression updates the value to the current value, nMatched can be greater than nModified.

BulkWriteResult.nModified

The number of existing documents updated or replaced. If the update/replacement operation results in no change to an existing document, such as setting the value of the field to its current value, nModified can be less than nMatched. Inserted documents do not affect the number of nModified; refer to the nInserted and nUpserted fields instead.

BulkWriteResult.nRemoved

The number of documents removed.

BulkWriteResult.nUpserted

The number of documents inserted through operations with the Bulk.find.upsert() option.

BulkWriteResult.upserted

An array of documents that contains information for each document inserted through operations with the Bulk.find.upsert() option.

Each document contains the following information:

BulkWriteResult.upserted.index

An integer that identifies the operation in the bulk operations list, which uses a zero-based index.

BulkWriteResult.upserted._id

The _id value of the inserted document.

BulkWriteResult.writeErrors

An array of documents that contains information regarding any error, unrelated to write concerns, encountered during the update operation. The writeErrors array contains an error document for each write operation that errors.

Each error document contains the following fields:

BulkWriteResult.writeErrors.index

An integer that identifies the write operation in the bulk operations list, which uses a zero-based index. See also Bulk.getOperations().

BulkWriteResult.writeErrors.code

An integer value identifying the error.

BulkWriteResult.writeErrors.errmsg

A description of the error.

BulkWriteResult.writeErrors.op

A document identifying the operation that failed. For instance, an update/replace operation error will return a document specifying the query, the update, the multi and the upsert options; an insert operation will return the document the operation tried to insert.

BulkWriteResult.writeConcernError

Document that describe error related to write concern and contains the field:

BulkWriteResult.writeConcernError.code

An integer value identifying the cause of the write concern error.

BulkWriteResult.writeConcernError.errInfo

A document identifying the write concern setting related to the error.

BulkWriteResult.writeConcernError.errmsg

A description of the cause of the write concern error.

Connection Methods

Name | Description
Mongo.getDB() | Returns a database object.
Mongo.getReadPrefMode() | Returns the current read preference mode for the MongoDB connection.
Mongo.getReadPrefTagSet() | Returns the read preference tag set for the MongoDB connection.
Mongo.setReadPref() | Sets the read preference for the MongoDB connection.
Mongo.setSlaveOk() | Allows operations on the current connection to read from secondary members.
Mongo() | Creates a new connection object.
connect() | Connects to a MongoDB instance and to a specified database on that instance.

Mongo.getDB()

Mongo.getReadPrefMode()

Mongo.getReadPrefTagSet()

Mongo.setReadPref()

mongo.setSlaveOk()

Mongo()

connect()

Mongo.getDB()

Description

Mongo.getDB(<database>)

Provides access to database objects from the mongo shell or from a JavaScript file.

The Mongo.getDB() method has the following parameter:

Parameter | Description
database | The name of the database to access.

param string database:

The name of the database to access.

Example

The following example instantiates a new connection to the MongoDB instance running on the localhost interface and returns a reference to "myDatabase":

db = new Mongo().getDB("myDatabase");

See also

Mongo() and connect()

Mongo.getReadPrefMode()

Mongo.getReadPrefMode()

Returns:
The current read preference mode for the Mongo() connection object.

See Read Preference for an introduction to read preferences in MongoDB. Use getReadPrefMode() to return the current read preference mode, as in the following example:

db.getMongo().getReadPrefMode()

Use the following operation to return and print the current read preference mode:

print(db.getMongo().getReadPrefMode());

This operation will return one of the following read preference modes:

primary

primaryPreferred

secondary

secondaryPreferred

nearest

See also

Read Preference, readPref(), setReadPref(), and getReadPrefTagSet().

Mongo.getReadPrefTagSet()

Mongo.getReadPrefTagSet()

Returns:
The current read preference tag set for the Mongo() connection object.

See Read Preference for an introduction to read preferences and tag sets in MongoDB. Use getReadPrefTagSet() to return the current read preference tag set, as in the following example:

db.getMongo().getReadPrefTagSet()

Use the following operation to return and print the current read preference tag set:

printjson(db.getMongo().getReadPrefTagSet());

See also

Read Preference, readPref(), setReadPref(), and getReadPrefTagSet().

Mongo.setReadPref()

Definition

Mongo.setReadPref(mode, tagSet)

Call the setReadPref() method on a Mongo connection object to control how the client will route all queries to members of the replica set.

Parameter | Description
mode | One of the following read preference modes: primary, primaryPreferred, secondary, secondaryPreferred, or nearest.
tagSet | Optional. A tag set used to specify custom read preference modes. For details, see Tag Sets.

param string mode:
| One of the following read preference modes: primary, primaryPreferred, secondary, secondaryPreferred, or nearest.
param array tagSet:
| Optional. A tag set used to specify custom read preference modes. For details, see Tag Sets.

Examples

To set a read preference mode in the mongo shell, use the following operation:

db.getMongo().setReadPref('primaryPreferred')

To set a read preference that uses a tag set, specify an array of tag sets as the second argument to Mongo.setReadPref(), as in the following:

db.getMongo().setReadPref('primaryPreferred', [ { "dc": "east" } ] )

You can specify multiple tag sets, in order of preference, as in the following:

db.getMongo().setReadPref('secondaryPreferred',
                          [ { "dc": "east", "use": "production" },
                            { "dc": "east", "use": "reporting" },
                            { "dc": "east" },
                            {}
                          ] )

If the replica set cannot satisfy the first tag set, the client will attempt to use the second read preference. Each tag set can contain zero or more field/value tag pairs, with an “empty” document acting as a wildcard which matches a replica set member with any tag set or no tag set.

Note

You must call Mongo.setReadPref() on the connection object before retrieving documents using that connection to use that read preference.

mongo.setSlaveOk()

Mongo.setSlaveOk()

For the current session, this command permits read operations from non-master (i.e. slave or secondary) instances. Practically, use this method in the following form:

db.getMongo().setSlaveOk()

Indicates that “eventually consistent” read operations are acceptable for the current application. This function provides the same functionality as rs.slaveOk().

See the readPref() method for more fine-grained control over read preference in the mongo shell.

Mongo()

Description

Mongo(host)

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

The Mongo() method has the following parameter:

Parameter | Description
host | Optional. The host, either in the form of <host> or <host><:port>.

param string host:

Optional. The host, either in the form of <host> or <host><:port>.

Instantiation Options

Use the constructor without a parameter to instantiate a connection to the localhost interface on the default port.

Pass the <host> parameter to the constructor to instantiate a connection to the <host> and the default port.

Pass the <host><:port> parameter to the constructor to instantiate a connection to the <host> and the <port>.

See also

Mongo.getDB() and db.getMongo().

connect()

connect(<hostname><:port>/<database>)

The connect() method creates a connection to a MongoDB instance. However, use the Mongo() object and its getDB() method in most cases.

connect() accepts a string <hostname><:port>/<database> parameter to connect to the MongoDB instance on the <hostname><:port> and return the reference to the database <database>.

The following example instantiates a new connection to the MongoDB instance running on the localhost interface and returns a reference to myDatabase:

db = connect("localhost:27017/myDatabase")

See also

Mongo.getDB()

Native Methods

Name | Description
cat() | Returns the contents of the specified file.
version() | Returns the current version of the mongo shell instance.
cd() | Changes the current working directory to the specified path.
copyDbpath() | Copies a local dbPath. For internal use.
resetDbpath() | Removes a local dbPath. For internal use.
fuzzFile() | For internal use to support testing.
getHostName() | Returns the hostname of the system running the mongo shell.
getMemInfo() | Returns a document that reports the amount of memory used by the shell.
hostname() | Returns the hostname of the system running the shell.
_isWindows() | Returns true if the shell runs on a Windows system; false if a Unix or Linux system.
listFiles() | Returns an array of documents that give the name and size of each object in the directory.
load() | Loads and runs a JavaScript file in the shell.
ls() | Returns a list of the files in the current directory.
md5sumFile() | The md5 hash of the specified file.
mkdir() | Creates a directory at the specified path.
pwd() | Returns the current directory.
quit() | Exits the current shell session.
_rand() | Returns a random number between 0 and 1.
removeFile() | Removes the specified file from the local file system.
_srand() | For internal use.

cat()

version()

cd()

copyDbpath()

resetDbpath()

fuzzFile()

getHostName()

getMemInfo()

hostname()

_isWindows()

listFiles()

load()

ls()

md5sumFile()

mkdir()

pwd()

quit()

rand()

removeFile()

_srand()

cat()

Definition

cat(filename)

Returns the contents of the specified file. The method returns with output relative to the current shell session and does not impact the server.

Parameter | Description
filename | Specify a path and file name on the local file system.

param string filename:

Specify a path and file name on the local file system.

version()

version()

Returns:
The version of the mongo shell as a string.

Changed in version 2.4: In previous versions of the shell, version() would print the version instead of returning a string.

cd()

Definition

cd(path)

Parameter | Description
path | A path on the file system local to the mongo shell context.

param string path:

A path on the file system local to the mongo shell context.

cd() changes the directory context of the mongo shell and has no effect on the MongoDB server.

copyDbpath()

copyDbpath()

For internal use.

resetDbpath()

resetDbpath()

For internal use.

fuzzFile()

Description

fuzzFile(filename)

For internal use.

Parameter | Description
filename | A filename or path to a local file.

param string filename:

A filename or path to a local file.

getHostName()

getHostName()

Returns:
The hostname of the system running the mongo shell process.

getMemInfo()

getMemInfo()

Returns a document with two fields that report the amount of memory used by the JavaScript shell process. The fields returned are resident and virtual.

hostname()

hostname()

Returns:
The hostname of the system running the mongo shell process.

_isWindows()

_isWindows()

Returns:
boolean.

Returns “true” if the mongo shell is running on a system that is Windows, or “false” if the shell is running on a Unix or Linux systems.

listFiles()

listFiles()

Returns an array, containing one document per object in the directory. This function operates in the context of the mongo process. The included fields are:

name

Returns a string which contains the name of the object.

isDirectory

Returns true or false if the object is a directory.

size

Returns the size of the object in bytes. This field is only present for files.

load()

Definition

load(file)

Loads and runs a JavaScript file into the current shell environment.

The load() method has the following parameter:

Parameter | Description
filename | Specifies the path of a JavaScript file to execute.

param string filename:

Specifies the path of a JavaScript file to execute.

Specify filenames with relative or absolute paths. When using relative path names, confirm the current directory using the pwd() method.

After executing a file with load(), you may reference any functions or variables defined the file from the mongo shell environment.

Example

Consider the following examples of the load() method:

load("scripts/myjstest.js")
load("/data/db/scripts/myjstest.js")

ls()

ls()

Returns a list of the files in the current directory.

This function returns with output relative to the current shell session, and does not impact the server.

md5sumFile()

Description

md5sumFile(filename)

Returns a md5 hash of the specified file.

The md5sumFile() method has the following parameter:

Parameter | Description
filename | A file name.

param string filename:

A file name.

Note

The specified filename must refer to a file located on the system running the mongo shell.

mkdir()

Description

mkdir(path)

Creates a directory at the specified path. This method creates the entire path specified if the enclosing directory or directories do not already exit.

This method is equivalent to mkdir -p with BSD or GNU utilities.

The mkdir() method has the following parameter:

Parameter | Description
path | A path on the local filesystem.

param string path:

A path on the local filesystem.

pwd()

pwd()

Returns the current directory.

This function returns with output relative to the current shell session, and does not impact the server.

quit()

quit()

Exits the current shell session.

rand()

_rand()

Returns:
A random number between 0 and 1.

This function provides functionality similar to the Math.rand() function from the standard library.

removeFile()

Description

removeFile(filename)

Removes the specified file from the local file system.

The removeFile() method has the following parameter:

Parameter | Description
filename | A filename or path to a local file.

param string filename:

A filename or path to a local file.

_srand()

_srand()

For internal use.

MongoDB Package Components

Core Processes

The core components in the MongoDB package are: mongod, the core database process; mongos the controller and query router for sharded clusters; and mongo the interactive MongoDB Shell.

mongod

mongos

mongo

Windows Services

The mongod.exe and mongos.exe describe the options available for configuring MongoDB when running as a Windows Service. The mongod.exe and mongos.exe binaries provide a superset of the mongod and mongos options.

mongod.exe

mongos.exe

Binary Import and Export Tools

mongodump provides a method for creating BSON dump files from the mongod instances, while mongorestore makes it possible to restore these dumps. bsondump converts BSON dump files into JSON. The mongooplog utility provides the ability to stream oplog entries outside of normal replication.

mongodump

mongorestore

bsondump

mongooplog

Data Import and Export Tools

mongoimport provides a method for taking data in JSON, CSV, or TSV and importing it into a mongod instance. mongoexport provides a method to export data from a mongod instance into JSON, CSV, or TSV.

Note

The conversion between BSON and other formats lacks full type fidelity. Therefore you cannot use mongoimport and mongoexport for round-trip import and export operations.

mongoimport

mongoexport

Diagnostic Tools

mongostat, mongotop, and mongosniff provide diagnostic information related to the current operation of a mongod instance.

Note

Because mongosniff depends on libpcap, most distributions of MongoDB do not include mongosniff.

mongostat

mongotop

mongosniff

mongoperf

GridFS

mongofiles provides a command-line interact to a MongoDB GridFS storage system.

mongofiles

mongod

Synopsis

mongod is the primary daemon process for the MongoDB system. It handles data requests, manages data access, and performs background management operations.

This document provides a complete overview of all command line options for mongod. These command line options are primarily useful for testing: In common operation, use the configuration file options to control the behavior of your database.

Options

mongod

Core Options

mongod

--help, -h

Returns information on the options and use of mongod.

--version

Returns the mongod release number.

--config <filename>, -f <filename>

Specifies a configuration file for runtime configuration options. The configuration file is the preferred method for runtime configuration of mongod. The options are equivalent to the command-line configuration options. See Configuration File Options for more information.

Ensure the configuration file uses ASCII encoding. The mongod instance does not support configuration files with non-ASCII encoding, including UTF-8.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongod in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--bind_ip <ip address>

Default: All interfaces.

Changed in version 2.6.0: The deb and rpm packages include a default configuration file that sets --bind_ip to 127.0.0.1.

Specifies the IP address that mongod binds to in order to listen for connections from applications. You may attach mongod to any interface. When attaching mongod to a publicly accessible interface, ensure that you have implemented proper authentication and firewall restrictions to protect the integrity of your database.

--maxConns <number>

The maximum number of simultaneous connections that mongod will accept. This setting has no effect if it is higher than your operating system’s configured maximum connection tracking threshold.

Changed in version 2.6: MongoDB removed the upward limit on the maxIncomingConnections setting.

--syslog

Sends all logging output to the host’s syslog system rather than to standard output or to a log file. , as with --logpath.

The --syslog option is not supported on Windows.

--syslogFacility <string>

Default: user

Specifies the facility level used when logging messages to syslog. The value you specify must be supported by your operating system’s implementation of syslog. To use this option, you must enable the --syslog option.

--logpath <path>

Sends all diagnostic logging information to a log file instead of to standard output or to the host’s syslog system. MongoDB creates the log file at the path you specify.

By default, MongoDB overwrites the log file when the process restarts. To instead append to the log file, set the --logappend option.

--logappend

Appends new entries to the end of the log file rather than overwriting the content of the log when the mongod instance restarts.

--timeStampFormat <string>

Default: iso8601-local

The time format for timestamps in log messages. Specify one of the following values:

Value | Description
ctime | Displays timestamps as Wed Dec 31 18:17:54.811.
iso8601-utc | Displays timestamps in Coordinated Universal Time (UTC) in the ISO-8601 format. For example, for New York at the start of the Epoch: 1970-01-01T00:00:00.000Z
iso8601-local | Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: 1969-12-31T19:00:00.000+0500

--diaglog <value>

Default: 0

Deprecated since version 2.6.

--diaglog is for internal use and not intended for most users.

Creates a very verbose diagnostic log for troubleshooting and recording various errors. MongoDB writes these log files in the dbPath directory in a series of files that begin with the string diaglog and end with the initiation time of the logging as a hex string.

The specified value configures the level of verbosity:

Value | Setting
0 | Off. No logging.
1 | Log write operations.
2 | Log read operations.
3 | Log both read and write operations.
7 | Log write and some read operations.

You can use the mongosniff tool to replay this output for investigation. Given a typical diaglog file located at /data/db/diaglog.4f76a58c, you might use a command in the following form to read these files:

mongosniff --source DIAGLOG /data/db/diaglog.4f76a58c

Warning

Setting the diagnostic level to 0 will cause mongod to stop writing data to the diagnostic log file. However, the mongod instance will continue to keep the file open, even if it is no longer writing data to the file. If you want to rename, move, or delete the diagnostic log you must cleanly shut down the mongod instance before doing so.

--traceExceptions

For internal diagnostic use only.

--pidfilepath <path>

Specifies a file location to hold the process ID of the mongod process where mongod will write its PID. This is useful for tracking the mongod process in combination with the --fork option. Without a specified --pidfilepath option, the process creates no PID file.

--keyFile <file>

Specifies the path to a key file that stores the shared secret that MongoDB instances use to authenticate to each other in a sharded cluster or replica set. --keyFile implies --auth. See Authentication Between MongoDB Instances for more information.

--setParameter <options>

Specifies one of the MongoDB parameters described in MongoDB Server Parameters. You can specify multiple setParameter fields.

--httpinterface

New in version 2.6.

Enables the HTTP interface. Enabling the interface can increase network exposure.

Leave the HTTP interface disabled for production deployments. If you do enable this interface, you should only allow trusted clients to access this port. See Firewalls.

Note

In MongoDB Enterprise, the HTTP Console does not support Kerberos Authentication.

--nohttpinterface

Deprecated since version 2.6: MongoDB disables the HTTP interface by default.

Disables the HTTP interface.

Do not use in conjunction with --rest or --jsonp.

Note

In MongoDB Enterprise, the HTTP Console does not support Kerberos Authentication.

--nounixsocket

Disables listening on the UNIX domain socket. The mongod process always listens on the UNIX socket unless one of the following is true:

--nounixsocket is set

bindIp is not set

bindIp does not specify 127.0.0.1

New in version 2.6: mongod installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

--unixSocketPrefix <path>

Default: /tmp

The path for the UNIX socket. If this option has no value, the mongod process creates a socket with /tmp as a prefix. MongoDB creates and listens on a UNIX socket unless one of the following is true:

--nounixsocket is set

bindIp is not set

bindIp does not specify 127.0.0.1

--fork

Enables a daemon mode that runs the mongod process in the background. By default mongod does not run as a daemon: typically you will run mongod as a daemon, either by using --fork or by using a controlling process that handles the daemonization process (e.g. as with upstart and systemd).

--auth

Enables authorization to control user’s access to database resources and operations. When authorization is enabled, MongoDB requires all clients to authenticate themselves first in order to determine the access for the client.

Configure users via the mongo shell. If no users exist, the localhost interface will continue to have access to the database until you create the first user.

See Security for more information.

--noauth

Disables authentication. Currently the default. Exists for future compatibility and clarity.

--ipv6

Enables IPv6 support and allows the mongod to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--jsonp

Permits JSONP access via an HTTP interface. Enabling the interface can increase network exposure. The --jsonp option enables the HTTP interface, even if the HTTP interface option is disabled.

--rest

Enables the simple REST API. Enabling the REST API enables the HTTP interface, even if the HTTP interface option is disabled, and as a result can increase network exposure.

--slowms <integer>

Default: 100

The threshold in milliseconds at which the database profiler considers a query slow. MongoDB records all slow queries to the log, even when the database profiler is off. When the profiler is on, it writes to the system.profile collection. See the profile command for more information on the database profiler.

--profile <level>

Default: 0

Changes the level of database profiling, which inserts information about operation performance into standard output or a log file. Specify one of the following levels:

Level | Setting
0 | Off. No profiling.
1 | On. Only includes slow operations.
2 | On. Includes all operations.

Database profiling can impact database performance. Enable this option only after careful consideration.

--cpu

Forces the mongod process to report the percentage of CPU time in write lock, every four seconds.

--sysinfo

Returns diagnostic system information and then exits. The information provides the page size, the number of physical pages, and the number of available physical pages.

--dbpath <path>

Default: /data/db on Linux and OS X, \data\db on Windows

The directory where the mongod instance stores its data.

If you installed MongoDB using a package management system, check the /etc/mongodb.conf file provided by your packages to see the directory is specified.

--directoryperdb

Stores each database’s files in its own folder in the data directory. When applied to an existing system, the directoryPerDB option alters the storage pattern of the data directory.

Use this option in conjunction with your file system and device configuration so that MongoDB will store data on a number of distinct disk devices to increase write throughput or disk capacity.

Warning

To enable this option for an existing system, migrate the database-specific data files to the new directory structure before enabling directoryPerDB. Database-specific data files begin with the name of an existing database and end with either “ns” or a number. For example, the following data directory includes files for the local and test databases:

journal
mongod.lock
local.0
local.1
local.ns
test.0
test.1
test.ns

After migration, the data directory would have the following structure:

journal
mongod.lock
local/local.0
local/local.1
local/local.ns
test/test.0
test/test.1
test/test.ns

--noIndexBuildRetry

Stops the mongod from rebuilding incomplete indexes on the next start up. This applies in cases where the mongod restarts after it has shut down or stopped in the middle of an index build. In such cases, the mongod always removes any incomplete indexes, and then also, by default, attempts to rebuild them. To stop the mongod from rebuilding incomplete indexes on start up, include this option on the command-line.

--noprealloc

Deprecated since version 2.6.

Disables the preallocation of data files. Currently the default. Exists for future compatibility and clarity.

--nssize <value>

Default: 16

Specifies the default size for namespace files, which are files that end in .ns. Each collection and index counts as a namespace.

Use this setting to control size for newly created namespace files. This option has no impact on existing files. The maximum size for a namespace file is 2047 megabytes. The default value of 16 megabytes provides for approximately 24,000 namespaces.

--quota

Enables a maximum limit for the number data files each database can have. When running with the --quota option, MongoDB has a maximum of 8 data files per database. Adjust the quota with --quotaFiles.

--quotaFiles <number>

Default: 8

Modifies the limit on the number of data files per database. --quotaFiles option requires that you set --quota.

--smallfiles

Sets MongoDB to use a smaller default file size. The --smallfiles option reduces the initial size for data files and limits the maximum size to 512 megabytes. --smallfiles also reduces the size of each journal file from 1 gigabyte to 128 megabytes. Use --smallfiles if you have a large number of databases that each holds a small quantity of data.

The --smallfiles option can lead the mongod instance to create a large number of files, which can affect performance for larger databases.

--syncdelay <value>

Default: 60

Controls how much time can pass before MongoDB flushes data to the data files via an fsync operation. Do not set this value on production systems. In almost every situation, you should use the default setting.

Warning

If you set --syncdelay to 0, MongoDB will not sync the memory mapped files to disk.

The mongod process writes data very quickly to the journal and lazily to the data files. syncPeriodSecs has no effect on the journal files or journaling.

The serverStatus command reports the background flush thread’s status via the backgroundFlushing field.

--upgrade

Upgrades the on-disk data format of the files specified by the --dbpath to the latest version, if needed.

This option only affects the operation of the mongod if the data files are in an old format.

In most cases you should not set this value, so you can exercise the most control over your upgrade process. See the MongoDB release notes [http://www.mongodb.org/downloads] (on the download page) for more information about the upgrade process.

--repair

Runs a repair routine on all databases. This is equivalent to shutting down and running the repairDatabase database command on all databases.

Warning

During normal operations, only use the repairDatabase command and wrappers including db.repairDatabase() in the mongo shell and mongod --repair, to compact database files and/or reclaim disk space. Be aware that these operations remove and do not save any corrupt data during the repair process.

If you are trying to repair a replica set member, and you have access to an intact copy of your data (e.g. a recent backup or an intact member of the replica set), you should restore from that intact copy, and not use repairDatabase.

When using journaling, there is almost never any need to run repairDatabase. In the event of an unclean shutdown, the server will be able to restore the data files to a pristine state automatically.

Changed in version 2.1.2.

If you run the repair option and have data in a journal file, the mongod instance refuses to start. In these cases you should start the mongod without the --repair option, which allows the mongod to recover data from the journal. This completes more quickly and is more likely to produce valid data files. To continue the repair operation despite the journal files, shut down the mongod cleanly and restart with the --repair option.

The --repair option copies data from the source data files into new data files in the repairPath and then replaces the original data files with the repaired data files.

--repairpath <path>

Default: A _tmp directory within the path specified by the dbPath option.

Specifies a working directory that MongoDB will use during the --repair operation. After --repair completes, the data files in dbPath and the --repairpath directory is empty.

The --repairpath must be within the dbPath. You can specify a symlink to --repairpath to use a path on a different file system.

--objcheck

Forces the mongod to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database. For objects with a high degree of sub-document nesting, the --objcheck option can have a small impact on performance. You can set --noobjcheck to disable object checking at runtime.

Changed in version 2.4: MongoDB enables the --objcheck option by default in order to prevent any client from inserting malformed or invalid BSON into a MongoDB database.

--noobjcheck

New in version 2.4.

Disables the default document validation that MongoDB performs on all incoming BSON documents.

--noscripting

Disables the scripting engine.

--notablescan

Forbids operations that require a table scan. See notablescan for additional information.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongod enables journaling by default on 64-bit builds of versions after 2.0.

--nojournal

Disables the durability journaling. The mongod instance enables journaling by default in 64-bit versions after v2.0.

--journalOptions <arguments>

Provides functionality for testing. Not for general use, and will affect data file integrity in the case of abnormal system shutdown.

--journalCommitInterval <value>

Default: 100 or 30

The maximum amount of time the mongod process allows between journal operations. Values can range from 2 to 300 milliseconds. Lower values increase the durability of the journal, at the expense of disk performance.

The default journal commit interval is 100 milliseconds if a single block device (e.g. physical volume, RAID device, or LVM volume) contains both the journal and the data files.

If the journal is on a different block device than the data files the default journal commit interval is 30 milliseconds.

To force mongod to commit to the journal more frequently, you can specify j:true. When a write operation with j:true is pending, mongod will reduce commitIntervalMs to a third of the set value.

--shutdown

The --shutdown option cleanly and safely terminates the mongod process. When invoking mongod with this option you must set the --dbpath option either directly or by way of the configuration file and the --config option.

The --shutdown option is available only on Linux systems.

Replication Options

--replSet <setname>

Configures replication. Specify a replica set name as an argument to this set. All hosts in the replica set must have the same set name.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

--oplogSize <value>

Specifies a maximum size in megabytes for the replication operation log (i.e., the oplog). The mongod process creates an oplog based on the maximum amount of space available. For 64-bit systems, the oplog is typically 5% of available disk space. Once the mongod has created the oplog for the first time, changing the --oplogSize option will not affect the size of the oplog.

See Oplog Size for more information.

--replIndexPrefetch

Default: all

New in version 2.2.

Determines which indexes secondary members of a replica set load into memory before applying operations from the oplog. By default secondaries load all indexes related to an operation into memory before applying operations from the oplog. This option can have one of the following values:

Value | Description
none | Secondaries do not load indexes into memory.
all | Secondaries load all indexes related to an operation.
_id_only | Secondaries load no additional indexes into memory beyond the already existing _id index.

Master-Slave Replication

These options provide access to conventional master-slave database replication. While this functionality remains accessible in MongoDB, replica sets are the preferred configuration for database replication.

--master

Configures the mongod to run as a replication master.

--slave

Configures the mongod to run as a replication slave.

--source <host><:port>

For use with the --slave option, the --source option designates the server that this instance will replicate.

--only <arg>

For use with the --slave option, the --only option specifies only a single database to replicate.

--slavedelay <value>

For use with the --slave option, the --slavedelay option configures a “delay” in seconds, for this slave to wait to apply operations from the master node.

--autoresync

For use with the --slave option. When set, the --autoresync option allows this slave to automatically resync if it is more than 10 seconds behind the master. This setting may be problematic if the --oplogSize specifies a too small oplog.

If the oplog is not large enough to store the difference in changes between the master’s current state and the state of the slave, this instance will forcibly resync itself unnecessarily. If you don’t specify --autoresync, the slave will not attempt an automatic resync more than once in a ten minute period.

--fastsync

In the context of replica set replication, set this option if you have seeded this member with an up-to-date copy of the entire dbPath of another member of the set. Otherwise the mongod will attempt to perform an initial sync, as though the member were a new member.

Warning

If the data is not perfectly synchronized and the mongod starts with fastsync, then the secondary or slave will be permanently out of sync with the primary, which may cause significant consistency problems.

Sharded Cluster Options

--configsvr

Declares that this mongod instance serves as the config database of a sharded cluster. When running with this option, clients (i.e. other cluster components) will not be able to write data to any database other than config and admin. The default port for a mongod with this option is 27019 and the default --dbpath directory is /data/configdb, unless specified.

Changed in version 2.2: The --configsvr option also sets --smallfiles.

Changed in version 2.4: The --configsvr option creates a local oplog.

Do not use the --configsvr option with --replSet or --shardsvr. Config servers cannot be a shard server or part of a replica set.

--shardsvr

Configures this mongod instance as a shard in a partitioned cluster. The default port for these instances is 27018. The only effect of --shardsvr is to change the port number.

SSL Options

See

Configure mongod and mongos for SSL for full documentation of MongoDB’s support.

--sslOnNormalPorts

Deprecated since version 2.6.

Enables SSL for mongod.

With --sslOnNormalPorts, a mongod requires SSL encryption for all connections on the default MongoDB port, or the port specified by --port. By default, --sslOnNormalPorts is disabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslMode <mode>

New in version 2.6.

Enables SSL or mixed SSL used for all network connections. The argument to the --sslMode option can be one of the following:

Value | Description
disabled | The server does not use SSL.
allowSSL | Connections between servers do not use SSL. For incoming connections, the server accepts both SSL and non-SSL.
preferSSL | Connections between servers use SSL. For incoming connections, the server accepts both SSL and non-SSL.
requireSSL | The server uses and accepts only SSL encrypted connections.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyFile <filename>

New in version 2.2.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

When SSL is enabled, you must specify --sslPEMKeyFile.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.2.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongod will redact the password from all logging and reporting output.

Changed in version 2.6: If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongod will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--clusterAuthMode <option>

Default: keyFile

New in version 2.6.

The authentication mode used for cluster authentication. If you use internal x.509 authentication, specify so here. This option can have one of the following values:

Value | Description
keyFile | Use a keyfile for authentication. Accept only keyfiles.
sendKeyFile | For rolling upgrade purposes. Send a keyfile for authentication but can accept both keyfiles and x.509 certificates.
sendX509 | For rolling upgrade purposes. Send the x.509 certificate for authentication but can accept both keyfiles and x.509 certificates.
x509 | Recommended. Send the x.509 certificate for authentication and accept only x.509 certificates.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslClusterFile <filename>

New in version 2.6.

Specifies the .pem file that contains the x.509 certificate-key file for membership authentication for the cluster or replica set.

If --sslClusterFile does not specify the .pem file for internal cluster authentication, the cluster uses the .pem file specified in the --sslPEMKeyFile option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslClusterPassword <value>

New in version 2.6.

Specifies the password to de-crypt the x.509 certificate-key file specified with --sslClusterFile. Use the --sslClusterPassword option only if the certificate-key file is encrypted. In all cases, the mongod will redact the password from all logging and reporting output.

If the x.509 key file is encrypted and you do not specify the --sslClusterPassword option, the mongod will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.4.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

--sslCRLFile <filename>

New in version 2.4.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.4.

Bypasses the validation checks for SSL certificates on other servers in the cluster and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslWeakCertificateValidation

New in version 2.4.

Disables the requirement for SSL certificate validation that --sslCAFile enables. With the --sslWeakCertificateValidation option, the mongod will accept connections when the client does not present a certificate when establishing the connection.

If the client presents a certificate and the mongod has --sslWeakCertificateValidation enabled, the mongod will validate the certificate using the root certificate chain specified by --sslCAFile and reject clients with invalid certificates.

Use the --sslWeakCertificateValidation option if you have a mixed deployment that includes clients that do not or cannot present certificates to the mongod.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.4.

Directs the mongod to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Audit Options

--auditDestination

New in version 2.6.

Enables auditing. The --auditDestination option can have one of the following values:

Value
Description

syslog

Output the audit events to syslog in JSON format. Not available on Windows. Audit messages have a syslog severity level of info and a facility level of user.

The syslog message limit can result in the truncation of audit messages. The auditing system will neither detect the truncation nor error upon its occurrence.

console
Output the audit events to stdout in JSON format.

file
Output the audit events to the file specified in --auditPath in the format specified in --auditFormat.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditFormat

New in version 2.6.

Specifies the format of the output file for auditing if --auditDestination is file. The --auditFormat option can have one of the following values:

Value | Description
JSON | Output the audit events in JSON format to the file specified in --auditPath.
BSON | Output the audit events in BSON binary format to the file specified in --auditPath.

Printing audit events to a file in JSON format degrades server performance more than printing to a file in BSON format.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditPath

New in version 2.6.

Specifies the output file for auditing if --auditDestination has value of file. The --auditPath option can take either a full path name or a relative path name.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditFilter

New in version 2.6.

Specifies the filter to limit the types of operations the audit system records. The option takes a string representation of a query document of the form:

{ <field1>: <expression1>, ... }

The <field> can be any field in the audit message, including fields returned in the param document. The <expression> is a query condition expression.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

SNMP Options

--snmp-subagent

Runs SNMP as a subagent. For more information, see Monitor MongoDB With SNMP on Linux.

--snmp-master

Runs SNMP as a master. For more information, see Monitor MongoDB With SNMP on Linux.

mongos

Synopsis

mongos for “MongoDB Shard,” is a routing service for MongoDB shard configurations that processes queries from the application layer, and determines the location of this data in the sharded cluster, in order to complete these operations. From the perspective of the application, a mongos instance behaves identically to any other MongoDB instance.

Considerations

Never change the name of the mongos binary.

Options

mongos

Core Options

mongos

--help, -h

Returns information on the options and use of mongos.

--version

Returns the mongos release number.

--config <filename>, -f <filename>

Specifies a configuration file for runtime configuration options. The configuration file is the preferred method for runtime configuration of mongos. The options are equivalent to the command-line configuration options. See Configuration File Options for more information.

Ensure the configuration file uses ASCII encoding. The mongos instance does not support configuration files with non-ASCII encoding, including UTF-8.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongos in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--bind_ip <ip address>

Default: All interfaces.

Changed in version 2.6.0: The deb and rpm packages include a default configuration file that sets --bind_ip to 127.0.0.1.

Specifies the IP address that mongos binds to in order to listen for connections from applications. You may attach mongos to any interface. When attaching mongos to a publicly accessible interface, ensure that you have implemented proper authentication and firewall restrictions to protect the integrity of your database.

--maxConns <number>

Specifies the maximum number of simultaneous connections that mongos will accept. This setting will have no effect if the value of this setting is higher than your operating system’s configured maximum connection tracking threshold.

This setting is particularly useful for mongos if you have a client that creates a number of connections but allows them to timeout rather than close the connections. When you set maxIncomingConnections, ensure the value is slightly higher than the size of the connection pool or the total number of connections to prevent erroneous connection spikes from propagating to the members of a sharded cluster.

Changed in version 2.6: MongoDB removed the upward limit on the maxIncomingConnections setting.

--syslog

Sends all logging output to the host’s syslog system rather than to standard output or to a log file. , as with --logpath.

The --syslog option is not supported on Windows.

--syslogFacility <string>

Default: user

Specifies the facility level used when logging messages to syslog. The value you specify must be supported by your operating system’s implementation of syslog. To use this option, you must enable the --syslog option.

--logpath <path>

Sends all diagnostic logging information to a log file instead of to standard output or to the host’s syslog system. MongoDB creates the log file at the path you specify.

By default, MongoDB overwrites the log file when the process restarts. To instead append to the log file, set the --logappend option.

--logappend

Appends new entries to the end of the log file rather than overwriting the content of the log when the mongos instance restarts.

--timeStampFormat <string>

Default: iso8601-local

The time format for timestamps in log messages. Specify one of the following values:

Value | Description
ctime | Displays timestamps as Wed Dec 31 18:17:54.811.
iso8601-utc | Displays timestamps in Coordinated Universal Time (UTC) in the ISO-8601 format. For example, for New York at the start of the Epoch: 1970-01-01T00:00:00.000Z
iso8601-local | Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: 1969-12-31T19:00:00.000+0500

--pidfilepath <path>

Specifies a file location to hold the process ID of the mongos process where mongos will write its PID. This is useful for tracking the mongos process in combination with the --fork option. Without a specified --pidfilepath option, the process creates no PID file.

--keyFile <file>

Specifies the path to a key file that stores the shared secret that MongoDB instances use to authenticate to each other in a sharded cluster or replica set. --keyFile implies --auth. See Authentication Between MongoDB Instances for more information.

--setParameter <options>

Specifies one of the MongoDB parameters described in MongoDB Server Parameters. You can specify multiple setParameter fields.

--httpinterface

New in version 2.6.

Enables the HTTP interface. Enabling the interface can increase network exposure.

Leave the HTTP interface disabled for production deployments. If you do enable this interface, you should only allow trusted clients to access this port. See Firewalls.

Note

In MongoDB Enterprise, the HTTP Console does not support Kerberos Authentication.

--nounixsocket

Disables listening on the UNIX domain socket. The mongos process always listens on the UNIX socket unless one of the following is true:

--nounixsocket is set

bindIp is not set

bindIp does not specify 127.0.0.1

New in version 2.6: mongos installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

--unixSocketPrefix <path>

Default: /tmp

The path for the UNIX socket. If this option has no value, the mongos process creates a socket with /tmp as a prefix. MongoDB creates and listens on a UNIX socket unless one of the following is true:

--nounixsocket is set

bindIp is not set

bindIp does not specify 127.0.0.1

--fork

Enables a daemon mode that runs the mongos process in the background. By default mongos does not run as a daemon: typically you will run mongos as a daemon, either by using --fork or by using a controlling process that handles the daemonization process (e.g. as with upstart and systemd).

Sharded Cluster Options

--configdb <config1>,<config2>,<config3>

Specifies the configuration database for the sharded cluster. You must specify either 1 or 3 configuration servers, in a comma separated list. Always use 3 config servers in production environments.

All mongos instances must specify the exact same value for --configdb

If your configuration databases reside in more that one data center, order the hosts so that first config sever in the list is the closest to the majority of your mongos instances.

Warning

Never remove a config server from this setting, even if the config server is not available or offline.

--localThreshold

Default: 15

Affects the logic that mongos uses when selecting replica set members to pass read operations from clients. Specify a value in milliseconds. The default value of 15 corresponds to the default value in all of the client drivers.

When mongos receives a request that permits reads to secondary members, the mongos will:

Find the member of the set with the lowest ping time.

Construct a list of replica set members that is within a ping time of 15 milliseconds of the nearest suitable member of the set.

If you specify a value for the --localThreshold option, mongos will construct the list of replica members that are within the latency allowed by this value.

Select a member to read from at random from this list.

The ping time used for a member compared by the --localThreshold setting is a moving average of recent ping times, calculated at most every 10 seconds. As a result, some queries may reach members above the threshold until the mongos recalculates the average.

See the Member Selection section of the read preference documentation for more information.

--upgrade

Updates the meta data format used by the config database.

--chunkSize <value>

Default: 64

Determines the size in megabytes of each chunk in the sharded cluster. A size of 64 megabytes is ideal in most deployments: larger chunk size can lead to uneven data distribution; smaller chunk size can lead to inefficient movement of chunks between nodes.

This option affects chunk size only when you initialize the cluster for the first time. If you later modify the option, the new value has no effect. See the Modify Chunk Size in a Sharded Cluster procedure if you need to change the chunk size on an existing sharded cluster.

--noAutoSplit

Prevents mongos from automatically inserting metadata splits in a sharded collection. If set on all mongos instances, this prevents MongoDB from creating new chunks as the data in a collection grows.

Because any mongos in a cluster can create a split, to totally disable splitting in a cluster you must set --noAutoSplit on all mongos.

Warning

With --noAutoSplit enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution.

SSL Options

See

Configure mongod and mongos for SSL for full documentation of MongoDB’s support.

--sslOnNormalPorts

Deprecated since version 2.6.

Enables SSL for mongos.

With --sslOnNormalPorts, a mongos requires SSL encryption for all connections on the default MongoDB port, or the port specified by --port. By default, --sslOnNormalPorts is disabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslMode <mode>

New in version 2.6.

Enables SSL or mixed SSL used for all network connections. The argument to the --sslMode option can be one of the following:

Value | Description
disabled | The server does not use SSL.
allowSSL | Connections between servers do not use SSL. For incoming connections, the server accepts both SSL and non-SSL.
preferSSL | Connections between servers use SSL. For incoming connections, the server accepts both SSL and non-SSL.
requireSSL | The server uses and accepts only SSL encrypted connections.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyFile <filename>

New in version 2.2.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

When SSL is enabled, you must specify --sslPEMKeyFile.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.2.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongos will redact the password from all logging and reporting output.

Changed in version 2.6: If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongos will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--clusterAuthMode <option>

Default: keyFile

New in version 2.6.

The authentication mode used for cluster authentication. If you use internal x.509 authentication, specify so here. This option can have one of the following values:

Value | Description
keyFile | Use a keyfile for authentication. Accept only keyfiles.
sendKeyFile | For rolling upgrade purposes. Send a keyfile for authentication but can accept both keyfiles and x.509 certificates.
sendX509 | For rolling upgrade purposes. Send the x.509 certificate for authentication but can accept both keyfiles and x.509 certificates.
x509 | Recommended. Send the x.509 certificate for authentication and accept only x.509 certificates.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslClusterFile <filename>

New in version 2.6.

Specifies the .pem file that contains the x.509 certificate-key file for membership authentication for the cluster or replica set.

If --sslClusterFile does not specify the .pem file for internal cluster authentication, the cluster uses the .pem file specified in the --sslPEMKeyFile option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslClusterPassword <value>

New in version 2.6.

Specifies the password to de-crypt the x.509 certificate-key file specified with --sslClusterFile. Use the --sslClusterPassword option only if the certificate-key file is encrypted. In all cases, the mongos will redact the password from all logging and reporting output.

If the x.509 key file is encrypted and you do not specify the --sslClusterPassword option, the mongos will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.4.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

--sslCRLFile <filename>

New in version 2.4.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslWeakCertificateValidation

New in version 2.4.

Disables the requirement for SSL certificate validation that --sslCAFile enables. With the --sslWeakCertificateValidation option, the mongos will accept connections when the client does not present a certificate when establishing the connection.

If the client presents a certificate and the mongos has --sslWeakCertificateValidation enabled, the mongos will validate the certificate using the root certificate chain specified by --sslCAFile and reject clients with invalid certificates.

Use the --sslWeakCertificateValidation option if you have a mixed deployment that includes clients that do not or cannot present certificates to the mongos.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.4.

Bypasses the validation checks for SSL certificates on other servers in the cluster and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.4.

Directs the mongos to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Audit Options

--auditDestination

New in version 2.6.

Enables auditing. The --auditDestination option can have one of the following values:

Value
Description

syslog

Output the audit events to syslog in JSON format. Not available on Windows. Audit messages have a syslog severity level of info and a facility level of user.

The syslog message limit can result in the truncation of audit messages. The auditing system will neither detect the truncation nor error upon its occurrence.

console
Output the audit events to stdout in JSON format.

file
Output the audit events to the file specified in --auditPath in the format specified in --auditFormat.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditFormat

New in version 2.6.

Specifies the format of the output file for auditing if --auditDestination is file. The --auditFormat option can have one of the following values:

Value | Description
JSON | Output the audit events in JSON format to the file specified in --auditPath.
BSON | Output the audit events in BSON binary format to the file specified in --auditPath.

Printing audit events to a file in JSON format degrades server performance more than printing to a file in BSON format.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditPath

New in version 2.6.

Specifies the output file for auditing if --auditDestination has value of file. The --auditPath option can take either a full path name or a relative path name.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--auditFilter

New in version 2.6.

Specifies the filter to limit the types of operations the audit system records. The option takes a string representation of a query document of the form:

{ <field1>: <expression1>, ... }

The <field> can be any field in the audit message, including fields returned in the param document. The <expression> is a query condition expression.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

Additional Options

--ipv6

Enables IPv6 support and allows the mongos to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--jsonp

Permits JSONP access via an HTTP interface. Enabling the interface can increase network exposure. The --jsonp option enables the HTTP interface, even if the HTTP interface option is disabled.

--noscripting

Disables the scripting engine.

mongo

Description

mongo

mongo is an interactive JavaScript shell interface to MongoDB, which provides a powerful interface for systems administrators as well as a way for developers to test queries and operations directly with the database. mongo also provides a fully functional JavaScript environment for use with a MongoDB. This document addresses the basic invocation of the mongo shell and an overview of its usage.

Options

Core Options

mongo

--shell

Enables the shell interface. If you invoke the mongo command and specify a JavaScript file as an argument, or use --eval to specify JavaScript on the command line, the --shell option provides the user with a shell prompt after the file finishes executing.

--nodb

Prevents the shell from connecting to any database instances. Later, to connect to a database within the shell, see Opening New Connections.

--norc

Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up.

--quiet

Silences output from the shell during the connection process.

--port <port>

Specifies the port where the mongod or mongos instance is listening. If --port is not specified, mongo attempts to connect to port 27017.

--host <hostname>

Specifies the name of the host machine where the mongod or mongos is running. If this is not specified, mongo attempts to connect to a MongoDB process running on the localhost.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

--eval <javascript>

Evaluates a JavaScript expression that is specified as an argument. mongo does not load its own environment when evaluating code. As a result many options of the shell environment are not available.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options. To force mongo to prompt for a password, enter the --password option as the last option and leave out the argument.

--help, -h

Returns information on the options and use of mongo.

--version

Returns the mongo release number.

--verbose

Increases the verbosity of the output of the shell during the connection process.

--ipv6

Enables IPv6 support and allows the mongo to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

<db address>

Specifies the “database address” of the database to connect to. For example:

mongo admin

The above command will connect the mongo shell to the admin database on the local machine. You may specify a remote database instance, with the resolvable hostname or IP address. Separate the database name from the hostname using a / character. See the following examples:

mongo mongodb1.example.net
mongo mongodb1/admin
mongo 10.8.8.10/test

This syntax is the only way to connect to a specific database.

To specify alternate hosts and a database, you must use this syntax and cannot use --host or --port.

<file.js>

Specifies a JavaScript file to run and then exit. Generally this should be the last option specified.

Optional

To specify a JavaScript file to execute and allow mongo to prompt you for a password using --password, pass the filename as the first parameter with --username and --password as the last options, as in the following:

mongo file.js --username username --password

Use the --shell option to return to a shell after the file finishes running.

Authentication Options

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

If you do not specify a value for --authenticationDatabase, mongo uses the database specified in the connection string.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongo instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

SSL Options

--ssl

New in version 2.2.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyFile <filename>

New in version 2.4.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.4.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongo will redact the password from all logging and reporting output.

Changed in version 2.6: If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongo will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.4.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslCRLFile <filename>

New in version 2.4.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.4.

Directs the mongo to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Files

~/.dbshell

mongo maintains a history of commands in the .dbshell file.

Note

mongo does not recorded interaction related to authentication in the history file, including authenticate and db.addUser().

Warning

Versions of Windows mongo.exe earlier than 2.2.0 will save the .dbshell file in the mongo.exe working directory.

~/.mongorc.js

mongo will read the .mongorc.js file from the home directory of the user invoking mongo. In the file, users can define variables, customize the mongo shell prompt, or update information that they would like updated every time they launch a shell. If you use the shell to evaluate a JavaScript file or expression either on the command line with --eval or by specifying a .js file to mongo, mongo will read the .mongorc.js file after the JavaScript has finished processing.

Specify the --norc option to disable reading .mongorc.js.

/etc/mongorc.js

Global mongorc.js file which the mongo shell evaluates upon start-up. If a user also has a .mongorc.js file located in the HOME directory, the mongo shell evaluates the global /etc/mongorc.js file before evaluating the user’s .mongorc.js file.

/etc/mongorc.js must have read permission for the user running the shell. The --norc option for mongo suppresses only the user’s .mongorc.js file.

On Windows, the global mongorc.js </etc/mongorc.js> exists in the %ProgramData%\MongoDB directory.

/tmp/mongo_edit<time_t>.js

Created by mongo when editing a file. If the file exists, mongo will append an integer from 1 to 10 to the time value to attempt to create a unique file.

%TEMP%mongo_edit<time_t>.js

Created by mongo.exe on Windows when editing a file. If the file exists, mongo will append an integer from 1 to 10 to the time value to attempt to create a unique file.

Environment

EDITOR

Specifies the path to an editor to use with the edit shell command. A JavaScript variable EDITOR will override the value of EDITOR.

HOME

Specifies the path to the home directory where mongo will read the .mongorc.js file and write the .dbshell file.

HOMEDRIVE

On Windows systems, HOMEDRIVE specifies the path the directory where mongo will read the .mongorc.js file and write the .dbshell file.

HOMEPATH

Specifies the Windows path to the home directory where mongo will read the .mongorc.js file and write the .dbshell file.

Keyboard Shortcuts

The mongo shell supports the following keyboard shortcuts: [1]

Keybinding | Function
Up arrow | Retrieve previous command from history
Down-arrow | Retrieve next command from history
Home | Go to beginning of the line
End | Go to end of the line
Tab | Autocomplete method/command
Left-arrow | Go backward one character
Right-arrow | Go forward one character
Ctrl-left-arrow | Go backward one word
Ctrl-right-arrow | Go forward one word
Meta-left-arrow | Go backward one word
Meta-right-arrow | Go forward one word
Ctrl-A | Go to the beginning of the line
Ctrl-B | Go backward one character
Ctrl-C | Exit the mongo shell
Ctrl-D | Delete a char (or exit the mongo shell)
Ctrl-E | Go to the end of the line
Ctrl-F | Go forward one character
Ctrl-G | Abort
Ctrl-J | Accept/evaluate the line
Ctrl-K | Kill/erase the line
Ctrl-L or type cls | Clear the screen
Ctrl-M | Accept/evaluate the line
Ctrl-N | Retrieve next command from history
Ctrl-P | Retrieve previous command from history
Ctrl-R | Reverse-search command history
Ctrl-S | Forward-search command history
Ctrl-T | Transpose characters
Ctrl-U | Perform Unix line-discard
Ctrl-W | Perform Unix word-rubout
Ctrl-Y | Yank
Ctrl-Z | Suspend (job control works in linux)
Ctrl-H | Backward-delete a character
Ctrl-I | Complete, same as Tab
Meta-B | Go backward one word
Meta-C | Capitalize word
Meta-D | Kill word
Meta-F | Go forward one word
Meta-L | Change word to lowercase
Meta-U | Change word to uppercase
Meta-Y | Yank-pop
Meta-Backspace | Backward-kill word
Meta-< | Retrieve the first command in command history
Meta-> | Retrieve the last command in command history

[1]
MongoDB accommodates multiple keybinding. Since 2.0, mongo includes support for basic emacs keybindings.

Use

Typically users invoke the shell with the mongo command at the system prompt. Consider the following examples for other scenarios.

To connect to a database on a remote host using authentication and a non-standard port, use the following form:

mongo --username <user> --password <pass> --host <host> --port 28015

Alternatively, consider the following short form:

mongo -u <user> -p <pass> --host <host> --port 28015

Replace <user>, <pass>, and <host> with the appropriate values for your situation and substitute or omit the --port as needed.

To execute a JavaScript file without evaluating the ~/.mongorc.js file before starting a shell session, use the following form:

mongo --shell --norc alternate-environment.js

To execute a JavaScript file with authentication, with password prompted rather than provided on the command-line, use the following form:

mongo script-file.js -u <user> -p

To print return a query as JSON, from the system prompt using the --eval option, use the following form:

mongo --eval 'db.collection.find().forEach(printjson)'

Use single quotes (e.g. ') to enclose the JavaScript, as well as the additional JavaScript required to generate this output.

Additional Information

mongo Shell Quick Reference

mongo Shell Methods

Access the mongo Shell Help Information

Getting Started with the mongo Shell

Data Types in the mongo Shell

Write Scripts for the mongo Shell

mongod.exe

Synopsis

mongod.exe is the build of the MongoDB daemon (i.e. mongod) for the Windows platform. mongod.exe has all of the features of mongod on Unix-like platforms and is completely compatible with the other builds of mongod. In addition, mongod.exe provides several options for interacting with the Windows platform itself.

This document only references options that are unique to mongod.exe. All mongod options are available. See the mongod and the Configuration File Options documents for more information regarding mongod.exe.

To install and use mongod.exe, read the Install MongoDB on Windows document.

Options

mongod.exe

mongod.exe

--install

Installs mongod.exe as a Windows Service and exits.

If needed, you can install services for multiple instances of mongod.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

--remove

Removes the mongod.exe Windows Service. If mongod.exe is running, this operation will stop and then remove the service.

--remove requires the --serviceName if you configured a non-default --serviceName during the --install operation.

--reinstall

Removes mongod.exe and reinstalls mongod.exe as a Windows Service.

--serviceName name

Default: MongoDB

Set the service name of mongod.exe when running as a Windows Service. Use this name with the net start <name> and net stop <name> operations.

You must use --serviceName in conjunction with either the --install or --remove install option.

--serviceDisplayName <name>

Default: MongoDB

Sets the name listed for MongoDB on the Services administrative application.

--serviceDescription <description>

Default: MongoDB Server

Sets the mongod.exe service description.

You must use --serviceDescription in conjunction with the --install option.

For descriptions that contain spaces, you must enclose the description in quotes.

--serviceUser <user>

Runs the mongod.exe service in the context of a certain user. This user must have “Log on as a service” privileges.

You must use --serviceUser in conjunction with the --install option.

--servicePassword <password>

Sets the password for <user> for mongod.exe when running with the --serviceUser option.

You must use --servicePassword in conjunction with the --install option.

mongos.exe

Synopsis

mongos.exe is the build of the MongoDB Shard (i.e. mongos) for the Windows platform. mongos.exe has all of the features of mongos on Unix-like platforms and is completely compatible with the other builds of mongos. In addition, mongos.exe provides several options for interacting with the Windows platform itself.

This document only references options that are unique to mongos.exe. All mongos options are available. See the mongos and the Configuration File Options documents for more information regarding mongos.exe.

To install and use mongos.exe, read the Install MongoDB on Windows document.

Options

mongos.exe

mongos.exe

--install

Installs mongos.exe as a Windows Service and exits.

If needed, you can install services for multiple instances of mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

--remove

Removes the mongos.exe Windows Service. If mongos.exe is running, this operation will stop and then remove the service.

--remove requires the --serviceName if you configured a non-default --serviceName during the --install operation.

--reinstall

Removes mongos.exe and reinstalls mongos.exe as a Windows Service.

--serviceName name

Default: MongoS

Set the service name of mongos.exe when running as a Windows Service. Use this name with the net start <name> and net stop <name> operations.

You must use --serviceName in conjunction with either the --install or --remove install option.

--serviceDisplayName <name>

Default: Mongo DB Router

Sets the name listed for MongoDB on the Services administrative application.

--serviceDescription <description>

Default: Mongo DB Sharding Router

Sets the mongos.exe service description.

You must use --serviceDescription in conjunction with the --install option.

For descriptions that contain spaces, you must enclose the description in quotes.

--serviceUser <user>

Runs the mongos.exe service in the context of a certain user. This user must have “Log on as a service” privileges.

You must use --serviceUser in conjunction with the --install option.

--servicePassword <password>

Sets the password for <user> for mongos.exe when running with the --serviceUser option.

You must use --servicePassword in conjunction with the --install option.

mongodump

Synopsis

mongodump is a utility for creating a binary export of the contents of a database. Consider using this utility as part of an effective backup strategy. Use mongodump in conjunction with mongorestore to restore databases.

mongodump can read data from either mongod or mongos instances, in addition to reading directly from MongoDB data files without an active mongod.

See also

mongorestore, Backup a Sharded Cluster with Database Dumps and MongoDB Backup Methods.

Behavior

mongodump does not dump the content of the local database.

The data format used by mongodump from version 2.2 or later is incompatible with earlier versions of mongod. Do not use recent versions of mongodump to back up older data stores.

When running mongodump against a mongos instance where the sharded cluster consists of replica sets, the read preference of the operation will prefer reads from secondary members of the set.

Changed in version 2.2: When used in combination with fsync or db.fsyncLock(), mongod will block reads, including those from mongodump, when queued write operation waits behind the fsync lock. Do not use mongodump with db.fsyncLock().

mongodump overwrites output files if they exist in the backup data folder. Before running the mongodump command multiple times, either ensure that you no longer need the files in the output folder (the default is the dump/ folder) or rename the folders or files.

Required Access

Backup Collections

To backup all the databases in a cluster via mongodump, you should have the backup role. The backup role provides all the needed privileges for backing up all database. The role confers no additional access, in keeping with the policy of least privilege.

To backup a given database, you must have read access on the database. Several roles provide this access, including the backup role.

To backup the system.profile collection in a database, you must have read access on certain system collections in the database. Several roles provide this access, including the clusterAdmin and dbAdmin roles.

Backup Users

Changed in version 2.6.

To backup users and user-defined roles for a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to backup a given database’s users, you must have the find action on the admin database’s admin.system.users collection. The backup and userAdminAnyDatabase roles both provide this privilege.

To backup the user-defined roles on a database, you must have the find action on the admin database’s admin.system.roles collection. Both the backup and userAdminAnyDatabase roles provide this privilege.

Options

mongodump

mongodump

--help

Returns information on the options and use of mongodump.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongodump in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongodump release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongodump attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongodump to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongodump will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongodump will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongodump to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongodump will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

If you do not specify an authentication database, mongodump assumes that the database specified to export holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongodump instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies the directory of the MongoDB data files. The --dbpath option lets the mongodump attach directly to the local data files without going through a running mongod. When run with --dbpath, the mongodump locks access to the data files. No mongod can access the files while the mongodump process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows the mongodump to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongodump enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies a database to backup. If you do not specify a database, mongodump copies all databases in this instance into the dump files.

--collection <collection>, -c <collection>

Specifies a collection to backup. If you do not specify a collection, this option copies all collections in the specified database or instance to the dump files.

--out <path>, -o <path>

Specifies the directory where mongodump will write BSON files for the dumped databases. By default, mongodump saves output files in a directory named dump in the current working directory.

To send the database dump to standard output, specify “-” instead of a path. Write to standard output if you want process the output before saving it, such as to use gzip to compress the dump. When writing standard output, mongodump does not write the metadata that writes in a <dbname>.metadata.json file when writing to files directly.

--query <json>, -q <json>

Provides a JSON document as a query that optionally limits the documents included in the output of mongodump.

--oplog

Creates a file named oplog.bson as part of the mongodump output. The oplog.bson file, located in the top level of the output directory, contains oplog entries that occur during the mongodump operation. This file provides an effective point-in-time snapshot of the state of a mongod instance. To restore to a specific point-in-time backup, use the output created with this option in conjunction with mongorestore --oplogReplay.

Without --oplog, if there are write operations during the dump operation, the dump will not reflect a single moment in time. Changes made to the database during the update process can affect the output of the backup.

--oplog has no effect when running mongodump against a mongos instance to dump the entire contents of a sharded cluster. However, you can use --oplog to dump individual shards.

--oplog only works against nodes that maintain an oplog. This includes all members of a replica set, as well as master nodes in master/slave replication deployments.

--oplog does not dump the oplog collection.

--repair

Runs a repair option in addition to dumping the database. The repair option attempts to repair a database that may be in an invalid state as a result of an improper shutdown or mongod crash.

The --repair option uses aggressive data-recovery algorithms that may produce a large amount of duplication.

--forceTableScan

Forces mongodump to scan the data store directly: typically, mongodump saves entries as they appear in the index of the _id field. If you specify a query --query, mongodump will use the most appropriate index to support that query.

Use --forceTableScan to skip the index and scan the data directly. Typically there are two cases where this behavior is preferable to the default:

If you have key sizes over 800 bytes that would not be present in the _id index.

Your database uses a custom _id field.

When you run with --forceTableScan, mongodump does not use $snapshot. As a result, the dump produced by mongodump can reflect the state of the database at many different points in time.

Important

Use --forceTableScan with extreme caution and consideration.

--dumpDbUsersAndRoles

Includes user and role definitions in the database’s dump directory when performing mongodump on a specific database. This option applies only when you specify a database in the --db option. MongoDB always includes user and role definitions when mongodump applies to an entire instance and not just a specific database.

Use

See the Back Up and Restore with MongoDB Tools for a larger overview of mongodump usage. Also see the mongorestore document for an overview of the mongorestore, which provides the related inverse functionality.

The following command creates a dump file that contains only the collection named collection in the database named test. In this case the database is running on the local interface on port 27017:

mongodump  --db test --collection collection

In the next example, mongodump creates a backup of the database instance stored in the /srv/mongodb directory on the local machine. This requires that no mongod instance is using the /srv/mongodb directory.

mongodump --dbpath /srv/mongodb

In the final example, mongodump creates a database dump located at /opt/backup/mongodump-2011-10-24, from a database running on port 37017 on the host mongodb1.example.net and authenticating using the username user and the password pass, as follows:

mongodump --host mongodb1.example.net --port 37017 --username user --password pass --out /opt/backup/mongodump-2011-10-24

Additional Resources

Backup and it’s Role in Disaster Recovery White Paper [https://www.mongodb.com/lp/white-paper/backup-disaster-recovery]

Cloud Backup through MongoDB Management Service [http://mms.mongodb.com]

Blog Post: Backup vs. Replication, Why you Need Both [http://www.mongodb.com/blog/post/backup-vs-replication-why-do-you-need-both]

mongorestore

Synopsis

The mongorestore program writes data from a binary database dump created by mongodump to a MongoDB instance. mongorestore can create a new database or add data to an existing database.

mongorestore can write data to either mongod or mongos instances, in addition to writing directly to MongoDB data files without an active mongod.

Behavior

If you restore to an existing database, mongorestore will only insert into the existing database, and does not perform updates of any kind. If existing documents have the same value _id field in the target database and collection, mongorestore will not overwrite those documents.

Remember the following properties of mongorestore behavior:

mongorestore recreates indexes recorded by mongodump.

all operations are inserts, not updates.

mongorestore does not wait for a response from a mongod to ensure that the MongoDB process has received or recorded the operation.

The mongod will record any errors to its log that occur during a restore operation, but mongorestore will not receive errors.

The data format used by mongodump from version 2.2 or later is incompatible with earlier versions of mongod. Do not use recent versions of mongodump to back up older data stores.

Required Access to Restore User Data

Changed in version 2.6.

To restore users and user-defined roles on a given database, you must have access to the admin database. MongoDB stores the user data and role definitions for all databases in the admin database.

Specifically, to restore users to a given database, you must have the insert action on the admin database’s admin.system.users collection. The restore role provides this privilege.

To restore user-defined roles to a database, you must have the insert action on the admin database’s admin.system.roles collection. The restore role provides this privilege.

Options

mongorestore

mongorestore

--help

Returns information on the options and use of mongorestore.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongorestore in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongorestore release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongorestore attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongorestore to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongorestore will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongorestore will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongorestore to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongorestore will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongorestore instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies the directory of the MongoDB data files. The --dbpath option lets the mongorestore attach directly to the local data files without going through a running mongod. When run with --dbpath, the mongorestore locks access to the data files. No mongod can access the files while the mongorestore process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows the mongorestore to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongorestore enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies a database for mongorestore to restore data into. If the database does not exist, mongorestore creates the database. If you do not specify a <db>, mongorestore creates new databases that correspond to the databases where data originated and data may be overwritten. Use this option to restore data into a MongoDB instance that already has data.

--db does not control which BSON files mongorestore restores. You must use the mongorestore path option to limit that restored data.

--collection <collection>, -c <collection>

Specifies a single collection for mongorestore to restore. If you do not specify --collection, mongorestore takes the collection name from the input filename. If the input file has an extension, MongoDB omits the extension of the file from the collection name.

--objcheck

Forces mongorestore to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database. For objects with a high degree of sub-document nesting, --objcheck can have a small impact on performance. You can set --noobjcheck to disable object checking at run-time.

Changed in version 2.4: MongoDB enables --objcheck by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database.

--noobjcheck

New in version 2.4.

Disables the default document validation that MongoDB performs on all incoming BSON documents.

--filter <JSON>

Limits the documents that mongorestore imports to only those documents that match the JSON document specified as '<JSON>'. Be sure to include the document in single quotes to avoid interaction with your system’s shell environment. For an example of --filter, see Restore a Subset of data from a Binary Database Dump.

--drop

Modifies the restoration procedure to drop every collection from the target database before restoring the collection from the dumped backup.

With --drop specified, mongorestore removes all user credentials and replaces them with users defined in the dump file. Therefore, in systems with authorization enabled, mongorestore must be able to authenticate to an existing user and to a user defined in the dump file. If mongorestore can’t authenticate to a user defined in the dump file, the restoration process will fail, leaving an empty database.

--oplogReplay

After restoring the database dump, replays the oplog entries from the oplog.bson file located in the top level of the dump directory. When used in conjunction with mongodump --oplog, mongorestore --oplogReplay restores the database to the point-in-time backup captured with the mongodump --oplog command. For an example of --oplogReplay, see Restore Point in Time Oplog Backup.

mongorestore --oplogReplay replays any valid oplog.bson file found in the top level of the dump directory. That is, if you have a bson file that contains valid oplog entries, you can name the file oplog.bson and move it to the top level of the dump directory for mongorestore --oplogReplay to replay.

--oplogLimit <timestamp>

New in version 2.2.

Prevents mongorestore from applying oplog entries with timestamp newer than or equal to <timestamp>. Specify <timestamp> values in the form of <time_t>:<ordinal>, where <time_t> is the seconds since the UNIX epoch, and <ordinal> represents a counter of operations in the oplog that occurred in the specified second.

You must use --oplogLimit in conjunction with the --oplogReplay option.

--keepIndexVersion

Prevents mongorestore from upgrading the index to the latest version during the restoration process.

--noIndexRestore

New in version 2.2.

Prevents mongorestore from restoring and building indexes as specified in the corresponding mongodump output.

--noOptionsRestore

New in version 2.2.

Prevents mongorestore from setting the collection options, such as those specified by the collMod database command, on restored collections.

--restoreDbUsersAndRoles

Restore user and role definitions for the given database. See system.roles Collection and system.users Collection for more information.

--w <number of replicas per write>

New in version 2.2.

Specifies the write concern for each write operation that mongorestore writes to the target database. By default, mongorestore does not wait for a response for write acknowledgment.

<path>

The final argument of the mongorestore command is a directory path. This argument specifies the location of the database dump from which to restore.

Use

See Back Up and Restore with MongoDB Tools for a larger overview of mongorestore usage. Also see the mongodump document for an overview of the mongodump, which provides the related inverse functionality.

Consider the following example:

mongorestore --collection people --db accounts dump/accounts/people.bson

Here, mongorestore reads the database dump in the dump/ sub-directory of the current directory, and restores only the documents in the collection named people from the database named accounts. mongorestore restores data to the instance running on the localhost interface on port 27017.

In the next example, mongorestore restores a backup of the database instance located in dump to a database instance stored in the /srv/mongodb on the local machine. This requires that there are no active mongod instances attached to /srv/mongodb data directory.

mongorestore --dbpath /srv/mongodb

In the final example, mongorestore restores a database dump located at /opt/backup/mongodump-2011-10-24, to a database running on port 37017 on the host mongodb1.example.net. The mongorestore command authenticates to the MongoDB instance using the username user and the password pass, as follows:

mongorestore --host mongodb1.example.net --port 37017 --username user --password pass /opt/backup/mongodump-2011-10-24

Additional Resources

Backup and it’s Role in Disaster Recovery White Paper [https://www.mongodb.com/lp/white-paper/backup-disaster-recovery]

Cloud Backup through MongoDB Management Service [http://mms.mongodb.com]

Blog Post: Backup vs. Replication, Why you Need Both [http://www.mongodb.com/blog/post/backup-vs-replication-why-do-you-need-both]

bsondump

Synopsis

The bsondump converts BSON files into human-readable formats, including JSON. For example, bsondump is useful for reading the output files generated by mongodump.

Important

bsondump is a diagnostic tool for inspecting BSON files, not a tool for data ingestion or other application use.

Options

bsondump

bsondump

--help

Returns information on the options and use of bsondump.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the bsondump in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the bsondump release number.

--objcheck

Validates each BSON object before outputting it in JSON format. By default, bsondump enables --objcheck. For objects with a high degree of sub-document nesting, --objcheck can have a small impact on performance. You can set --noobjcheck to disable object checking.

Changed in version 2.4: MongoDB enables --objcheck by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database.

--noobjcheck

New in version 2.4.

Disables the default document validation that MongoDB performs on all incoming BSON documents.

--filter <JSON>

Limits the documents that bsondump exports to only those documents that match the JSON document specified as '<JSON>'. Be sure to include the document in single quotes to avoid interaction with your system’s shell environment.

--type <=json|=debug>

Changes the operation of bsondump from outputting “JSON” (the default) to a debugging format.

<bsonFilename>

The final argument to bsondump is a document containing BSON. This data is typically generated by bsondump or by MongoDB in a rollback operation.

Use

By default, bsondump outputs data to standard output. To create corresponding JSON files, you will need to use the shell redirect. See the following command:

bsondump collection.bson > collection.json

Use the following command (at the system shell) to produce debugging output for a BSON file:

bsondump --type=debug collection.bson

mongooplog

New in version 2.2.

Synopsis

mongooplog is a simple tool that polls operations from the replication oplog of a remote server, and applies them to the local server. This capability supports certain classes of real-time migrations that require that the source server remain online and in operation throughout the migration process.

Typically this command will take the following form:

mongooplog  --from mongodb0.example.net --host mongodb1.example.net

This command copies oplog entries from the mongod instance running on the host mongodb0.example.net and duplicates operations to the host mongodb1.example.net. If you do not need to keep the --from host running during the migration, consider using mongodump and mongorestore or another backup operation, which may be better suited to your operation.

Note

If the mongod instance specified by the --from argument is running with authentication, then mongooplog will not be able to copy oplog entries.

See also

mongodump, mongorestore, MongoDB Backup Methods, Replica Set Oplog.

Options

mongooplog

mongooplog

--help

Returns information on the options and use of mongooplog.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongooplog in a quiet mode that attempts to limit the amount of output.

This option suppresses:

connection accepted events

connection closed events

--version

Returns the mongooplog release number.

--host <hostname><:port>, -h <hostname><:port>

Specifies a resolvable hostname for the mongod instance to which mongooplog will apply oplog operations retrieved from the server specified by the --from option.

By default mongooplog attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port

Specifies the port number of the mongod instance where mongooplog will apply oplog entries. Specify this option only if the MongoDB instance to connect to is not running on the standard port of 27017. You may also specify a port number using the --host command.

--ipv6

Enables IPv6 support and allows the mongooplog to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongooplog will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongooplog will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongooplog to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongooplog will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongooplog instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies a directory, containing MongoDB data files, to which mongooplog will apply operations from the oplog of the database specified with the --from option.

When used, the --dbpath option enables mongo to attach directly to local data files and write data without a running mongod instance.

To run with --dbpath, mongooplog needs to restrict access to the data directory: as a result, no mongod can be access the same path while the process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows the mongooplog to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongooplog enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies the name of the database on which to run the mongooplog.

--collection <collection>, -c <collection>

Specifies the collection to export.

--seconds <number>, -s <number>

Specify a number of seconds of operations for mongooplog to pull from the remote host. Unless specified the default value is 86400 seconds, or 24 hours.

--from <host[:port]>

Specify the host for mongooplog to retrieve oplog operations from. mongooplog requires this option.

Unless you specify the --host option, mongooplog will apply the operations collected with this option to the oplog of the mongod instance running on the localhost interface connected to port 27017.

--oplogns <namespace>

Specify a namespace in the --from host where the oplog resides. The default value is local.oplog.rs, which is the where replica set members store their operation log. However, if you’ve copied oplog entries into another database or collection or are pulling oplog entries from a master-slave deployment, use --oplogns to apply oplog entries stored in another location. Namespaces take the form of [database].[collection].

Use

Consider the following prototype mongooplog command:

mongooplog  --from mongodb0.example.net --host mongodb1.example.net

Here, entries from the oplog of the mongod running on port 27017. This only pull entries from the last 24 hours.

Use the --seconds argument to capture a greater or smaller amount of time. Consider the following example:

mongooplog  --from mongodb0.example.net --seconds 172800

In this operation, mongooplog captures 2 full days of operations. To migrate 12 hours of oplog entries, use the following form:

mongooplog  --from mongodb0.example.net --seconds 43200

For the previous two examples, mongooplog migrates entries to the mongod process running on the localhost interface connected to the 27017 port. mongooplog can also operate directly on MongoDB’s data files if no mongod is running on the target host. Consider the following example:

mongooplog  --from mongodb0.example.net --dbpath /srv/mongodb --journal

Here, mongooplog imports oplog operations from the mongod host connected to port 27017. This migrates operations to the MongoDB data files stored in the /srv/mongodb directory. Additionally mongooplog will use the durability journal to ensure that the data files remain valid.

mongoimport

Synopsis

The mongoimport tool provides a route to import content from a JSON, CSV, or TSV export created by mongoexport, or potentially, another third-party export tool. See the Import and Export MongoDB Data document for a more in depth usage overview, and the mongoexport document for more information regarding mongoexport, which provides the inverse “exporting” capability.

Considerations

Do not use mongoimport and mongoexport for full instance, production backups because they will not reliably capture data type information. Use mongodump and mongorestore as described in MongoDB Backup Methods for this kind of functionality.

mongoimport is single-threaded and inserts one document at a time into MongoDB. Custom import tools for data ingestion may have better performance for specific workloads.

Options

mongoimport

mongoimport

--help

Returns information on the options and use of mongoimport.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongoimport in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongoimport release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongoimport attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongoimport to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongoimport will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongoimport will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongoimport to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongoimport will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongoimport instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies the directory of the MongoDB data files. The --dbpath option lets the mongoimport attach directly to the local data files without going through a running mongod. When run with --dbpath, the mongoimport locks access to the data files. No mongod can access the files while the mongoimport process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows the mongoimport to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongoimport enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies the name of the database on which to run the mongoimport.

--collection <collection>, -c <collection>

Specifies the collection to import.

New in version 2.6: If you do not specify --collection, mongoimport takes the collection name from the input filename. MongoDB omits the extension of the file from the collection name, if the input file has an extension.

--fields <field1[,field2]>, -f <field1[,field2]>

Specify a comma separated list of field names when importing csv or tsv files that do not have field names in the first (i.e. header) line of the file.

--fieldFile <filename>

As an alternative to --fields, the --fieldFile option allows you to specify a file that holds a list of field names if your csv or tsv file does not include field names in the first line of the file (i.e. header). Place one field per line.

--ignoreBlanks

Ignores empty fields in csv and tsv exports. If not specified, mongoimport creates fields without values in imported documents.

--type <json|csv|tsv>

Specifies the file type to import. The default format is JSON, but it’s possible to import csv and tsv files.

The csv parser accepts that data that complies with RFC RFC 4180 [http://tools.ietf.org/html/rfc4180.html]. As a result, backslashes are not a valid escape character. If you use double-quotes to enclose fields in the CSV data, you must escape internal double-quote marks by prepending another double-quote.

--file <filename>

Specifies the location and name of a file containing the data to import. If you do not specify a file, mongoimport reads data from standard input (e.g. “stdin”).

--drop

Modifies the import process so that the target instance drops the collection before importing the data from the input.

--headerline

If using --type csv or --type tsv, uses the first line as field names. Otherwise, mongoimport will import the first line as a distinct document.

--upsert

Modifies the import process to update existing objects in the database if they match an imported object, while inserting all other objects.

If you do not specify a field or fields using the --upsertFields mongoimport will upsert on the basis of the _id field.

--upsertFields <field1[,field2]>

Specifies a list of fields for the query portion of the upsert. Use this option if the _id fields in the existing documents don’t match the field in the document, but another field or field combination can uniquely identify documents as a basis for performing upsert operations.

To ensure adequate performance, indexes should exist for this field or fields.

--stopOnError

New in version 2.2.

Forces mongoimport to halt the import operation at the first error rather than continuing the operation despite errors.

--jsonArray

Accepts the import of data expressed with multiple MongoDB documents within a single JSON array. Limited to imports of 16 MB or smaller.

Use --jsonArray in conjunction with mongoexport --jsonArray.

Use

In this example, mongoimport imports the csv formatted data in the /opt/backups/contacts.csv into the collection contacts in the users database on the MongoDB instance running on the localhost port numbered 27017. mongoimport determines the name of files using the first line in the CSV file, because of the --headerline:

mongoimport --db users --collection contacts --type csv --headerline --file /opt/backups/contacts.csv

Since mongoimport uses the input file name, without the extension, as the collection name if -c or --collection is unspecified. The following example is equivalent:

mongoimport --db users --type csv --headerline --file /opt/backups/contacts.csv

In the following example, mongoimport imports the data in the JSON formatted file contacts.json into the collection contacts on the MongoDB instance running on the localhost port number 27017.

mongoimport --db users --collection contacts --file contacts.json

In the next example, mongoimport takes data passed to it on standard input (i.e. with a | pipe.) and imports it into the MongoDB datafiles located at /srv/mongodb/. if the import process encounters an error, the mongoimport will halt because of the --stopOnError option.

mongoimport --db sales --collection contacts --stopOnError --dbpath /srv/mongodb/

In the final example, mongoimport imports data from the file /opt/backups/mdb1-examplenet.json into the collection contacts within the database marketing on a remote MongoDB database. This mongoimport accesses the mongod instance running on the host mongodb1.example.net over port 37017, which requires the username user and the password pass.

mongoimport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --db marketing --file /opt/backups/mdb1-examplenet.json

Type Fidelity

Warning

mongoimport and mongoexport do not reliably preserve all rich BSON data types because JSON can only represent a subset of the types supported by BSON. As a result, data exported or imported with these tools may lose some measure of fidelity. See the Extended JSON reference for more information.

JSON can only represent a subset of the types supported by BSON. To preserve type information, mongoimport accepts strict mode representation for certain types.

For example, to preserve type information for BSON types data_date and data_numberlong during mongoimport, the data should be in strict mode representation, as in the following:

{ "_id" : 1, "volume" : { "$numberLong" : "2980000" }, "date" : { "$date" : "2014-03-13T13:47:42.483-0400" } }

For the data_numberlong type, mongoimport converts into a float during the import.

See MongoDB Extended JSON for a complete list of these types and the representations used.

mongoexport

Synopsis

mongoexport is a utility that produces a JSON or CSV export of data stored in a MongoDB instance. See the Import and Export MongoDB Data document for a more in depth usage overview, and the mongoimport document for more information regarding the mongoimport utility, which provides the inverse “importing” capability.

Considerations

Do not use mongoimport and mongoexport for full-scale production backups because they may not reliably capture data type information. Use mongodump and mongorestore as described in MongoDB Backup Methods for this kind of functionality.

Options

mongoexport

mongoexport

--help

Returns information on the options and use of mongoexport.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongoexport in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongoexport release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongoexport attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongoexport to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongoexport will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongoexport will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongoexport to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongoexport will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

If you do not specify an authentication database, mongoexport assumes that the database specified to export holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongoexport instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies the directory of the MongoDB data files. The --dbpath option lets the mongoexport attach directly to the local data files without going through a running mongod. When run with --dbpath, the mongoexport locks access to the data files. No mongod can access the files while the mongoexport process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows mongoexport to export data from MongoDB instances that have every database’s files saved in discrete directories on the disk. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongoexport enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies the name of the database on which to run the mongoexport.

--collection <collection>, -c <collection>

Specifies the collection to export.

--fields <field1[,field2]>, -f <field1[,field2]>

Specifies a field or fields to include in the export. Use a comma separated list of fields to specify multiple fields.

For --csv output formats, mongoexport includes only the specified field(s), and the specified field(s) can be a field within a sub-document.

For JSON output formats, mongoexport includes only the specified field(s) and the _id field, and if the specified field(s) is a field within a sub-document, the mongoexport includes the sub-document with all its fields, not just the specified field within the document.

--fieldFile <filename>

An alternative to --fields. The --fieldFile option allows you to specify in a file the field or fields to include in the export and is only valid with the --csv option. The file must have only one field per line, and the line(s) must end with the LF character (0x0A).

mongoexport includes only the specified field(s). The specified field(s) can be a field within a sub-document.

--query <JSON>, -q <JSON>

Provides a JSON document as a query that optionally limits the documents returned in the export. Specify JSON in strict format.

For example, given a collection named records in the database test with the following documents:

{ "_id" : ObjectId("51f0188846a64a1ed98fde7c"), "a" : 1 }
{ "_id" : ObjectId("520e61b0c6646578e3661b59"), "a" : 1, "b" : 2 }
{ "_id" : ObjectId("520e642bb7fa4ea22d6b1871"), "a" : 2, "b" : 3, "c" : 5 }
{ "_id" : ObjectId("520e6431b7fa4ea22d6b1872"), "a" : 3, "b" : 3, "c" : 6 }
{ "_id" : ObjectId("520e6445b7fa4ea22d6b1873"), "a" : 5, "b" : 6, "c" : 8 }

The following mongoexport uses the -q option to export only the documents with the field a greater than or equal to ($gte) to 3:

mongoexport -d test -c records -q "{ a: { \$gte: 3 } }" --out exportdir/myRecords.json

The resulting file contains the following documents:

{ "_id" : { "$oid" : "520e6431b7fa4ea22d6b1872" }, "a" : 3, "b" : 3, "c" : 6 }
{ "_id" : { "$oid" : "520e6445b7fa4ea22d6b1873" }, "a" : 5, "b" : 6, "c" : 8 }

You can sort the results with the --sort option to mongoexport.

--csv

Changes the export format to a comma-separated-values (CSV) format. By default mongoexport writes data using one JSON document for every MongoDB document.

If you specify --csv, then you must also use either the --fields or the --fieldFile option to declare the fields to export from the collection.

--out <file>, -o <file>

Specifies a file to write the export to. If you do not specify a file name, the mongoexport writes data to standard output (e.g. stdout).

--jsonArray

Modifies the output of mongoexport to write the entire contents of the export as a single JSON array. By default mongoexport writes data using one JSON document for every MongoDB document.

--slaveOk, -k

Allows mongoexport to read data from secondary or slave nodes when using mongoexport with a replica set. This option is only available if connected to a mongod or mongos and is not available when used with the “mongoexport --dbpath” option.

This is the default behavior.

--forceTableScan

New in version 2.2.

Forces mongoexport to scan the data store directly: typically, mongoexport saves entries as they appear in the index of the _id field. Use --forceTableScan to skip the index and scan the data directly. Typically there are two cases where this behavior is preferable to the default:

If you have key sizes over 800 bytes that would not be present in the _id index.

Your database uses a custom _id field.

When you run with --forceTableScan, mongoexport does not use $snapshot. As a result, the export produced by mongoexport can reflect the state of the database at many different points in time.

Warning

Use --forceTableScan with extreme caution and consideration.

--skip <number>

Use --skip to control where mongoexport begins exporting documents. See skip() for information about the underlying operation.

--limit <number>

Specifies a maximum number of documents to include in the export. See limit() for information about the underlying operation.

--sort <JSON>

Specifies an ordering for exported results. If an index does not exist that can support the sort operation, the results must be less than 32 megabytes.

Use --sort conjunction with --skip and --limit to limit number of exported documents.

mongoexport -d test -c records --sort '{a: 1}' --limit 100 --out export.0.json
mongoexport -d test -c records --sort '{a: 1}' --limit 100 --skip 100 --out export.1.json
mongoexport -d test -c records --sort '{a: 1}' --limit 100 --skip 200 --out export.2.json

See sort() for information about the underlying operation.

Use

Export in CSV Format

In the following example, mongoexport exports data from the collection contacts in the users database in CSV format to the file /opt/backups/contacts.csv. The mongod instance that mongoexport connects to is running on the localhost port number 27017.

To export in CSV format, you must specify the fields in the documents to export. The operation specifies the name and address fields to export.

mongoexport --db users --collection contacts --csv --fields name,address --out /opt/backups/contacts.csv

For CSV exports only, you can also specify the fields in a file containing the line-separated list of fields to export. The file must have only one field per line.

For example, you can specify the name and address fields in a file fields.txt:

name
address

Then, by using the --fieldFile option, you can specify the fields to export with the file:

mongoexport --db users --collection contacts --csv --fieldFile fields.txt --out /opt/backups/contacts.csv

Export in JSON Format

The next example creates an export of the collection contacts from the MongoDB instance running on the localhost port number 27017, with journaling explicitly enabled. This writes the export to the contacts.json file in JSON format.

mongoexport --db sales --collection contacts --out contacts.json --journal

Export Collection Directly From Data Files

The following example exports the collection contacts from the sales database located in the MongoDB data files located at /srv/mongodb/. This operation writes the export to standard output in JSON format.

mongoexport --db sales --collection contacts --dbpath /srv/mongodb/

Warning

The above example will only succeed if there is no mongod connected to the data files located in the /srv/mongodb/ directory.

Export from Remote Host Running with Authentication

The following example exports the collection contacts from the database marketing . This data resides on the MongoDB instance located on the host mongodb1.example.net running on port 37017, which requires the username user and the password pass.

mongoexport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --db marketing --out mdb1-examplenet.json

Type Fidelity

Warning

mongoimport and mongoexport do not reliably preserve all rich BSON data types because JSON can only represent a subset of the types supported by BSON. As a result, data exported or imported with these tools may lose some measure of fidelity. See the Extended JSON reference for more information.

JSON can only represent a subset of the types supported by BSON. To preserve type information, mongoexport uses the strict mode representation for certain types.

For example, the following insert operation in the mongo shell uses the mongoShell mode representation for the BSON types data_date and data_numberlong:

use test
db.traffic.insert( { _id: 1, volume: NumberLong(2980000), date: new Date() } )

Use mongoexport to export the data:

mongoexport --db test --collection traffic --out traffic.json

The exported data is in strict mode representation to preserve type information:

{ "_id" : 1, "volume" : { "$numberLong" : "2980000" }, "date" : { "$date" : "2014-03-13T13:47:42.483-0400" } }

See MongoDB Extended JSON for a complete list of these types and the representations used.

mongostat

Synopsis

The mongostat utility provides a quick overview of the status of a currently running mongod or mongos instance. mongostat is functionally similar to the UNIX/Linux file system utility vmstat, but provides data regarding mongod and mongos instances.

See also

For more information about monitoring MongoDB, see Monitoring for MongoDB.

For more background on various other MongoDB status outputs see:

serverStatus

replSetGetStatus

dbStats

collStats

For an additional utility that provides MongoDB metrics see mongotop.

Access Control Requirements

In order to connect to a mongod that enforces authorization with the --auth option, specify the --username and --password options, and the user specified must have the serverStatus privilege action on the cluster resources.

The built-in role clusterMonitor provides this privilege as well as other privileges. To create a role with just the privilege to run mongostat, see Create a Role to Run mongostat.

Options

mongostat

mongostat

--help

Returns information on the options and use of mongostat.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--version

Returns the mongostat release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongostat attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongostat to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongostat will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongostat will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongostat to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongostat will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationDatabase is required for mongod and mongos instances that use Authentication.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongostat instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--noheaders

Disables the output of column or field names.

--rowcount <number>, -n <number>

Controls the number of rows to output. Use in conjunction with the sleeptime argument to control the duration of a mongostat operation.

Unless --rowcount is specified, mongostat will return an infinite number of rows (e.g. value of 0.)

--http

Configures mongostat to collect data using the HTTP interface rather than a raw database connection.

--discover

Discovers and reports on statistics from all members of a replica set or sharded cluster. When connected to any member of a replica set, --discover all non-hidden members of the replica set. When connected to a mongos, mongostat will return data from all shards in the cluster. If a replica set provides a shard in the sharded cluster, mongostat will report on non-hidden members of that replica set.

The mongostat --host option is not required but potentially useful in this case.

Changed in version 2.6: When running with --discover, mongostat now respects :option:–rowcount`.

--all

Configures mongostat to return all optional fields.

<sleeptime>

The final argument is the length of time, in seconds, that mongostat waits in between calls. By default mongostat returns one call every second.

mongostat returns values that reflect the operations over a 1 second period. For values of <sleeptime> greater than 1, mongostat averages data to reflect average operations per second.

Fields

mongostat returns values that reflect the operations over a 1 second period. When mongostat <sleeptime> has a value greater than 1, mongostat averages the statistics to reflect average operations per second.

mongostat outputs the following fields:

inserts

The number of objects inserted into the database per second. If followed by an asterisk (e.g. *), the datum refers to a replicated operation.

query

The number of query operations per second.

update

The number of update operations per second.

delete

The number of delete operations per second.

getmore

The number of get more (i.e. cursor batch) operations per second.

command

The number of commands per second. On slave and secondary systems, mongostat presents two values separated by a pipe character (e.g. |), in the form of local|replicated commands.

flushes

The number of fsync operations per second.

mapped

The total amount of data mapped in megabytes. This is the total data size at the time of the last mongostat call.

size

The amount of virtual memory in megabytes used by the process at the time of the last mongostat call.

non-mapped

The total amount of virtual memory excluding all mapped memory at the time of the last mongostat call.

res

The amount of resident memory in megabytes used by the process at the time of the last mongostat call.

faults

Changed in version 2.1.

The number of page faults per second.

Before version 2.1 this value was only provided for MongoDB instances running on Linux hosts.

locked

The percent of time in a global write lock.

Changed in version 2.2: The locked db field replaces the locked % field to more appropriate data regarding the database specific locks in version 2.2.

locked db

New in version 2.2.

The percent of time in the per-database context-specific lock. mongostat will report the database that has spent the most time since the last mongostat call with a write lock.

This value represents the amount of time that the listed database spent in a locked state combined with the time that the mongod spent in the global lock. Because of this, and the sampling method, you may see some values greater than 100%.

idx miss

The percent of index access attempts that required a page fault to load a btree node. This is a sampled value.

qr

The length of the queue of clients waiting to read data from the MongoDB instance.

qw

The length of the queue of clients waiting to write data from the MongoDB instance.

ar

The number of active clients performing read operations.

aw

The number of active clients performing write operations.

netIn

The amount of network traffic, in bytes, received by the MongoDB instance.

This includes traffic from mongostat itself.

netOut

The amount of network traffic, in bytes, sent by the MongoDB instance.

This includes traffic from mongostat itself.

conn

The total number of open connections.

set

The name, if applicable, of the replica set.

repl

The replication status of the member.

Value | Replication Type
M | master
SEC | secondary
REC | recovering
UNK | unknown
SLV | slave
RTR | mongos process (“router”)

Usage

In the first example, mongostat will return data every second for 20 seconds. mongostat collects data from the mongod instance running on the localhost interface on port 27017. All of the following invocations produce identical behavior:

mongostat --rowcount 20 1
mongostat --rowcount 20
mongostat -n 20 1
mongostat -n 20

In the next example, mongostat returns data every 5 minutes (or 300 seconds) for as long as the program runs. mongostat collects data from the mongod instance running on the localhost interface on port 27017. Both of the following invocations produce identical behavior.

mongostat --rowcount 0 300
mongostat -n 0 300
mongostat 300

In the following example, mongostat returns data every 5 minutes for an hour (12 times.) mongostat collects data from the mongod instance running on the localhost interface on port 27017. Both of the following invocations produce identical behavior.

mongostat --rowcount 12 300
mongostat -n 12 300

In many cases, using the --discover will help provide a more complete snapshot of the state of an entire group of machines. If a mongos process connected to a sharded cluster is running on port 27017 of the local machine, you can use the following form to return statistics from all members of the cluster:

mongostat --discover

mongotop

Synopsis

mongotop provides a method to track the amount of time a MongoDB instance spends reading and writing data. mongotop provides statistics on a per-collection level. By default, mongotop returns values every second.

Important

In order to connect to a mongod that enforces authorization with the --auth option, the --username and --password options must be used, and the user specified must have the serverStatus and top privileges.

The most appropriate built-in role that has these privileges is clusterMonitor.

See also

For more information about monitoring MongoDB, see Monitoring for MongoDB.

For additional background on various other MongoDB status outputs see:

serverStatus

replSetGetStatus

dbStats

collStats

For an additional utility that provides MongoDB metrics see mongostat.

Options

mongotop

mongotop

--help

Returns information on the options and use of mongotop.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongotop in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongotop release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongotop attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongotop to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongotop will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongotop will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongotop to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongotop will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationDatabase is required for mongod and mongos instances that use Authentication.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongotop instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--locks

Toggles the mode of mongotop to report on use of per-database locks. These data are useful for measuring concurrent operations and lock percentage.

<sleeptime>

The final argument is the length of time, in seconds, that mongotop waits in between calls. By default mongotop returns data every second.

Fields

mongotop returns time values specified in milliseconds (ms.)

mongotop only reports active namespaces or databases, depending on the --locks option. If you don’t see a database or collection, it has received no recent activity. You can issue a simple operation in the mongo shell to generate activity to affect the output of mongotop.

mongotop.ns

Contains the database namespace, which combines the database name and collection.

Changed in version 2.2: If you use the --locks, the ns field does not appear in the mongotop output.

mongotop.db

New in version 2.2.

Contains the name of the database. The database named . refers to the global lock, rather than a specific database.

This field does not appear unless you have invoked mongotop with the --locks option.

mongotop.total

Provides the total amount of time that this mongod spent operating on this namespace.

mongotop.read

Provides the amount of time that this mongod spent performing read operations on this namespace.

mongotop.write

Provides the amount of time that this mongod spent performing write operations on this namespace.

mongotop.<timestamp>

Provides a time stamp for the returned data.

Use

By default mongotop connects to the MongoDB instance running on the localhost port 27017. However, mongotop can optionally connect to remote mongod instances. See the mongotop options for more information.

To force mongotop to return less frequently specify a number, in seconds at the end of the command. In this example, mongotop will return every 15 seconds.

mongotop 15

This command produces the following output:

connected to: 127.0.0.1

                    ns       total        read       write           2012-08-13T15:45:40
test.system.namespaces         0ms         0ms         0ms
  local.system.replset         0ms         0ms         0ms
  local.system.indexes         0ms         0ms         0ms
  admin.system.indexes         0ms         0ms         0ms
                admin.         0ms         0ms         0ms

                    ns       total        read       write           2012-08-13T15:45:55
test.system.namespaces         0ms         0ms         0ms
  local.system.replset         0ms         0ms         0ms
  local.system.indexes         0ms         0ms         0ms
  admin.system.indexes         0ms         0ms         0ms
                admin.         0ms         0ms         0ms

To return a mongotop report every 5 minutes, use the following command:

mongotop 300

To report the use of per-database locks, use mongotop --locks, which produces the following output:

$ mongotop --locks
connected to: 127.0.0.1

                  db       total        read       write          2012-08-13T16:33:34
               local         0ms         0ms         0ms
               admin         0ms         0ms         0ms
                   .         0ms         0ms         0ms

mongosniff

Synopsis

mongosniff provides a low-level operation tracing/sniffing view into database activity in real time. Think of mongosniff as a MongoDB-specific analogue of tcpdump for TCP/IP network traffic. Typically, mongosniff is most frequently used in driver development.

Note

mongosniff requires libpcap and is only available for Unix-like systems.

As an alternative to mongosniff, Wireshark, a popular network sniffing tool is capable of inspecting and parsing the MongoDB wire protocol.

Options

mongosniff

mongosniff

--help

Returns information on the options and use of mongosniff.

--forward <host><:port>

Declares a host to forward all parsed requests that the mongosniff intercepts to another mongod instance and issue those operations on that database instance.

Specify the target host name and port in the <host><:port> format.

To connect to a replica set, specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

--source <NET [interface]>

Specifies source material to inspect. Use --source NET [interface] to inspect traffic from a network interface (e.g. eth0 or lo.) Use --source FILE [filename] to read captured packets in pcap format.

You may use the --source DIAGLOG [filename] option to read the output files produced by the --diaglog option.

--objcheck

Displays invalid BSON objects only and nothing else. Use this option for troubleshooting driver development. This option has some performance impact on the performance of mongosniff.

<port>

Specifies alternate ports to sniff for traffic. By default, mongosniff watches for MongoDB traffic on port 27017. Append multiple port numbers to the end of mongosniff to monitor traffic on multiple ports.

Use

Use the following command to connect to a mongod or mongos running on port 27017 and 27018 on the localhost interface:

mongosniff --source NET lo 27017 27018

Use the following command to only log invalid BSON objects for the mongod or mongos running on the localhost interface and port 27018, for driver development and troubleshooting:

mongosniff --objcheck --source NET lo 27018

Build mongosniff

To build mongosniff yourself, Linux users can use the following procedure:

Obtain prerequisites using your operating systems package management software. Dependencies include:

libpcap - to capture network packets.

git - to download the MongoDB source code.

scons and a C++ compiler - to build mongosniff.

Download a copy of the MongoDB source code using git:

git clone git://github.com/mongodb/mongo.git

Issue the following sequence of commands to change to the mongo/ directory and build mongosniff:

cd mongo
scons mongosniff

Note

If you run scons mongosniff before installing libpcap you must run scons clean before you can build mongosniff.

mongoperf

Synopsis

mongoperf is a utility to check disk I/O performance independently of MongoDB.

It times tests of random disk I/O and presents the results. You can use mongoperf for any case apart from MongoDB. The mmf true mode is completely generic. In that mode it is somewhat analogous to tools such as bonnie++ [http://sourceforge.net/projects/bonnie/] (albeit mongoperf is simpler).

Specify options to mongoperf using a JavaScript document.

See also

bonnie [http://www.textuality.com/bonnie/]

bonnie++ [http://sourceforge.net/projects/bonnie/]

Output from an example run [https://gist.github.com/1694664]

Checking Disk Performance with the mongoperf Utility [http://blog.mongodb.org/post/40769806981/checking-disk-performance-with-the-mongoperf-utility]

Options

mongoperf

mongoperf

--help, -h

Returns information on the options and use of mongoperf.

<jsonconfig>

mongoperf accepts configuration options in the form of a file that holds a JSON document. You must stream the content of this file into mongoperf, as in the following operation:

mongoperf < config

In this example config is the name of a file that holds a JSON document that resembles the following example:

{
  nThreads:<n>,
  fileSizeMB:<n>,
  sleepMicros:<n>,
  mmf:<bool>,
  r:<bool>,
  w:<bool>,
  recSizeKB:<n>,
  syncDelay:<n>
}

See the Configuration Fields section for documentation of each of these fields.

Configuration Fields

mongoperf.nThreads

Type: Integer.

Default: 1

Defines the number of threads mongoperf will use in the test. To saturate your system’s storage system you will need multiple threads. Consider setting nThreads to 16.

mongoperf.fileSizeMB

Type: Integer.

Default: 1 megabyte (i.e. 1024² bytes)

Test file size.

mongoperf.sleepMicros

Type: Integer.

Default: 0

mongoperf will pause for the number of specified sleepMicros divided by the nThreads between each operation.

mongoperf.mmf

Type: Boolean.

Default: false

Set mmf to true to use memory mapped files for the tests.

Generally:

when mmf is false, mongoperf tests direct, physical, I/O, without caching. Use a large file size to test heavy random I/O load and to avoid I/O coalescing.

when mmf is true, mongoperf runs tests of the caching system, and can use normal file system cache. Use mmf in this mode to test file system cache behavior with memory mapped files.

mongoperf.r

Type: Boolean.

Default: false

Set r to true to perform reads as part of the tests.

Either r or w must be true.

mongoperf.w

Type: Boolean.

Default: false

Set w to true to perform writes as part of the tests.

Either r or w must be true.

mongoperf.recSizeKB

New in version 2.4.

Type: Integer.

Default: 4 kb

The size of each write operation.

mongoperf.syncDelay

Type: Integer.

Default: 0

Seconds between disk flushes. mongoperf.syncDelay is similar to --syncdelay for mongod.

The syncDelay controls how frequently mongoperf performs an asynchronous disk flush of the memory mapped file used for testing. By default, mongod performs this operation every 60 seconds. Use syncDelay to test basic system performance of this type of operation.

Only use syncDelay in conjunction with mmf set to true.

The default value of 0 disables this.

Use

mongoperf < jsonconfigfile

Replace jsonconfigfile with the path to the mongoperf configuration. You may also invoke mongoperf in the following form:

echo "{nThreads:16,fileSizeMB:10000,r:true,w:true}" | mongoperf

In this operation:

mongoperf tests direct physical random read and write io’s, using 16 concurrent reader threads.

mongoperf uses a 10 gigabyte test file.

Consider using iostat, as invoked in the following example to monitor I/O performance during the test.

iostat -xtm 1

mongofiles

mongofiles

Synopsis

The mongofiles utility makes it possible to manipulate files stored in your MongoDB instance in GridFS objects from the command line. It is particularly useful as it provides an interface between objects stored in your file system and GridFS.

All mongofiles commands have the following form:

mongofiles <options> <commands> <filename>

The components of the mongofiles command are:

Options. You may use one or more of these options to control the behavior of mongofiles.

Commands. Use one of these commands to determine the action of mongofiles.

A filename which is either: the name of a file on your local’s file system, or a GridFS object.

mongofiles, like mongodump, mongoexport, mongoimport, and mongorestore, can access data stored in a MongoDB data directory without requiring a running mongod instance, if no other mongod is running.

Important

For replica sets, mongofiles can only read from the set’s ‘primary.

Options

mongofiles

--help

Returns information on the options and use of mongofiles.

--verbose, -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--quiet

Runs the mongofiles in a quiet mode that attempts to limit the amount of output.

This option suppresses:

output from database commands

replication activity

connection accepted events

connection closed events

--version

Returns the mongofiles release number.

--host <hostname><:port>

Specifies a resolvable hostname for the mongod that holds your GridFS system. By default mongofiles attempts to connect to a MongoDB process running on the localhost port number 27017.

Optionally, specify a port number to connect a MongoDB instance running on a port other than 27017.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ipv6

Enables IPv6 support and allows the mongofiles to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

--ssl

New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCAFile <filename>

New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the mongo shell or any other tool that connects to mongos or mongod is run without --sslCAFile, it will not attempt to validate server certificates. This results in vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has CAFile enabled without weakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslPEMKeyPassword <value>

New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongofiles will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --sslPEMKeyPassword option, the mongofiles will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslCRLFile <filename>

New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslAllowInvalidCertificates

New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--sslFIPSMode

New in version 2.6.

Directs the mongofiles to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

If you do not specify an argument for --password, mongofiles will prompt interactively for a password on the console.

--authenticationDatabase <dbname>

New in version 2.4.

Specifies the database that holds the user’s credentials.

--authenticationMechanism <name>

Default: MONGODB-CR

New in version 2.4.

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the authentication mechanism the mongofiles instance uses to authenticate to the mongod or mongos.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

--gssapiServiceName

New in version 2.6.

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName

New in version 2.6.

Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--dbpath <path>

Specifies the directory of the MongoDB data files. The --dbpath option lets the mongofiles attach directly to the local data files without going through a running mongod. When run with --dbpath, the mongofiles locks access to the data files. No mongod can access the files while the mongofiles process runs.

--directoryperdb

When used in conjunction with the corresponding option in mongod, allows the mongofiles to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the --dbpath option.

--journal

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongofiles enables journaling by default on 64-bit builds of versions after 2.0.

--db <database>, -d <database>

Specifies the name of the database on which to run the mongofiles.

--collection <collection>, -c <collection>

This option has no use in this context and a future release may remove it. See SERVER-4931 [https://jira.mongodb.org/browse/SERVER-4931] for more information.

--local <filename>, -l <filename>

Specifies the local filesystem name of a file for get and put operations.

In the mongofiles put and mongofiles get commands, the required <filename> modifier refers to the name the object will have in GridFS. mongofiles assumes that this reflects the file’s name on the local file system. This setting overrides this default.

--type <MIME>

Provides the ability to specify a MIME type to describe the file inserted into GridFS storage. mongofiles omits this option in the default operation.

Use only with mongofiles put operations.

--replace, -r

Alters the behavior of mongofiles put to replace existing GridFS objects with the specified local file, rather than adding an additional object with the same name.

In the default operation, files will not be overwritten by a mongofiles put option.

Commands

list <prefix>

Lists the files in the GridFS store. The characters specified after list (e.g. <prefix>) optionally limit the list of returned items to files that begin with that string of characters.

search <string>

Lists the files in the GridFS store with names that match any portion of <string>.

put <filename>

Copy the specified file from the local file system into GridFS storage.

Here, <filename> refers to the name the object will have in GridFS, and mongofiles assumes that this reflects the name the file has on the local file system. If the local filename is different use the mongofiles --local option.

get <filename>

Copy the specified file from GridFS storage to the local file system.

Here, <filename> refers to the name the object will have in GridFS, and mongofiles assumes that this reflects the name the file has on the local file system. If the local filename is different use the mongofiles --local option.

delete <filename>

Delete the specified file from GridFS storage.

Examples

To return a list of all files in a GridFS collection in the records database, use the following invocation at the system shell:

mongofiles -d records list

This mongofiles instance will connect to the mongod instance running on the 27017 localhost interface to specify the same operation on a different port or hostname, and issue a command that resembles one of the following:

mongofiles --port 37017 -d records list
mongofiles --hostname db1.example.net -d records list
mongofiles --hostname db1.example.net --port 37017 -d records list

Modify any of the following commands as needed if you’re connecting the mongod instances on different ports or hosts.

To upload a file named 32-corinth.lp to the GridFS collection in the records database, you can use the following command:

mongofiles -d records put 32-corinth.lp

To delete the 32-corinth.lp file from this GridFS collection in the records database, you can use the following command:

mongofiles -d records delete 32-corinth.lp

To search for files in the GridFS collection in the records database that have the string corinth in their names, you can use following command:

mongofiles -d records search corinth

To list all files in the GridFS collection in the records database that begin with the string 32, you can use the following command:

mongofiles -d records list 32

To fetch the file from the GridFS collection in the records database named 32-corinth.lp, you can use the following command:

mongofiles -d records get 32-corinth.lp

Configuration File Options

Important

Changed in version 2.6: MongoDB introduces a YAML-based configuration file format. The 2.4 configuration file format [http://docs.mongodb.org/v2.4/reference/configuration-options] remains for backward compatibility.

Overview

You can control mongod and mongos instances at runtime using a configuration file. The configuration file contains settings that are functionally equivalent to the mongod and mongos command-line arguments but are easier to manage, especially on large-scale deployments. Configuration files allow commenting to describe the reasoning behind a server’s settings.

If you installed from a package and have started MongoDB using your system’s control script, you are already using a configuration file.

Specifying the Configuration File when Starting MongoDB

To start mongod or mongos using a config file, specify the config file with the --config option.

For example, the following specifies a config file for a mongod:

mongod --config /etc/mongodb.conf

The following specifies a config file for a mongos using the -f alias:

mongos -f /etc/mongodb.conf

Config File Format

The configuration file is in YAML [http://www.yaml.org] format. The following is an example of several settings in a configuration file:

systemLog:
   destination: file
   path: "/var/log/mongodb/mongodb.log"
   logAppend: true
storage:
   journal:
      enabled: true
processManagement:
   fork: true
net:
   bindIp: 127.0.0.1
   port: 27017
...

Settings

Core Options

systemLog

systemLog.verbosity

Type: integer

Increases the amount of internal reporting returned on standard output or in log files. To increase the amount of information reported, increase the number.

systemLog.quiet

Type: boolean

Runs the mongos or mongod in a quiet mode that attempts to limit the amount of output.

This option is not recommended for production systems as it may make tracking problems during particular connections much more difficult.

systemLog.traceAllExceptions

Type: boolean

Prints verbose information for debugging. Used for additional logging in support-related troubleshooting.

systemLog.syslogFacility

Type: string

Default: user

Specifies the facility level used when logging messages to syslog. The value you specify must be supported by your operating system’s implementation of syslog. To use this option, you must enable the --syslog option.

systemLog.path

Type: string

Sends all diagnostic logging information to a log file instead of to standard output or to the host’s syslog system. MongoDB creates the log file at the path you specify.

By default, MongoDB overwrites the log file when the process restarts. To instead append to the log file, set the --logappend option.

systemLog.logAppend

Type: boolean

Default: False

Appends new entries to the end of the log file rather than overwriting the content of the log when the mongos or mongod instance restarts.

systemLog.destination

Type: string

Specify either file or syslog. If you specify file you must also specify systemLog.path. If you do not specify systemLog.destination, MongoDB will send all log output to standard output.

systemLog.timeStampFormat

Type: string

Default: iso8601-local

The time format for timestamps in log messages. Specify one of the following values:

Value | Description
ctime | Displays timestamps as Wed Dec 31 18:17:54.811.
iso8601-utc | Displays timestamps in Coordinated Universal Time (UTC) in the ISO-8601 format. For example, for New York at the start of the Epoch: 1970-01-01T00:00:00.000Z
iso8601-local | Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: 1969-12-31T19:00:00.000+0500

processManagement

processManagement.pidFilePath

Type: string

Specifies a file location to hold the process ID of the mongos or mongod process where mongos or mongod will write its PID. This is useful for tracking the mongos or mongod process in combination with the --fork option. Without a specified processManagement.pidFilePath option, the process creates no PID file.

processManagement.fork

Type: boolean

Default: False

Enables a daemon mode that runs the mongos or mongod process in the background. By default mongos or mongod does not run as a daemon: typically you will run mongos or mongod as a daemon, either by using processManagement.fork or by using a controlling process that handles the daemonization process (e.g. as with upstart and systemd).

net

net.port

Type: integer

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

net.bindIp

Type: string

Default: All interfaces.

Changed in version 2.6.0: The deb and rpm packages include a default configuration file that sets net.bindIp to 127.0.0.1.

Specifies the IP address that mongos or mongod binds to in order to listen for connections from applications. You may attach mongos or mongod to any interface. When attaching mongos or mongod to a publicly accessible interface, ensure that you have implemented proper authentication and firewall restrictions to protect the integrity of your database.

To bind to multiple IP addresses, enter a list of comma separated values.

net.maxIncomingConnections

Type: integer

Default: 1000000

The maximum number of simultaneous connections that mongos or mongod will accept. This setting has no effect if it is higher than your operating system’s configured maximum connection tracking threshold.

Changed in version 2.6: MongoDB removed the upward limit on the maxIncomingConnections setting.

This is particularly useful for a mongos if you have a client that creates a number of connections but allows them to timeout rather than close the connections. When you set this option, ensure the value is slightly higher than the size of the connection pool or the total number of connections, to prevent erroneous connection spikes from propagating to the members of a sharded cluster.

net.wireObjectCheck

Type: boolean

Default: True

Forces the mongod or mongos instance to validate all requests from clients upon receipt to prevent clients from inserting malformed or invalid BSON into a MongoDB database.

For objects with a high degree of sub-document nesting, net.wireObjectCheck can have a small impact on performance.

net.http.enabled

Type: boolean

Default: False

New in version 2.6.

Enables the HTTP interface. Enabling the interface can increase network exposure.

Leave the HTTP interface disabled for production deployments. If you do enable this interface, you should only allow trusted clients to access this port. See Firewalls.

Note

In MongoDB Enterprise, the HTTP Console does not support Kerberos Authentication.

net.unixDomainSocket.enabled

Type: boolean

Default: False

Disables listening on the UNIX domain socket. The mongos or mongod process always listens on the UNIX socket unless one of the following is true:

net.unixDomainSocket.enabled is set

bindIp is not set

bindIp does not specify 127.0.0.1

New in version 2.6: mongos or mongod installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

net.unixDomainSocket.pathPrefix

Type: string

Default: /tmp

The path for the UNIX socket. If this option has no value, the mongos or mongod process creates a socket with /tmp as a prefix. MongoDB creates and listens on a UNIX socket unless one of the following is true:

--nounixsocket is set

bindIp is not set

bindIp does not specify 127.0.0.1

net.ipv6

Type: boolean

Default: False

Enables IPv6 support and allows the mongos or mongod to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.

net.http.JSONPEnabled

Type: boolean

Default: False

Permits JSONP access via an HTTP interface. Enabling the interface can increase network exposure. The net.http.JSONPEnabled option enables the HTTP interface, even if the HTTP interface option is disabled.

The net.http.JSONPEnabled option is available only for mongod.

net.http.RESTInterfaceEnabled

Type: boolean

Default: False

Enables the simple REST API. Enabling the REST API enables the HTTP interface, even if the HTTP interface option is disabled, and as a result can increase network exposure.

The net.http.RESTInterfaceEnabled option is available only for mongod.

net.ssl.sslOnNormalPorts

Type: boolean

Deprecated since version 2.6.

Enables SSL for mongos or mongod.

With net.ssl.sslOnNormalPorts, a mongos or mongod requires SSL encryption for all connections on the default MongoDB port, or the port specified by --port. By default, --sslOnNormalPorts is disabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.mode

Type: string

New in version 2.6.

Enables SSL or mixed SSL used for all network connections. The argument to the net.ssl.mode option can be one of the following:

Value | Description
disabled | The server does not use SSL.
allowSSL | Connections between servers do not use SSL. For incoming connections, the server accepts both SSL and non-SSL.
preferSSL | Connections between servers use SSL. For incoming connections, the server accepts both SSL and non-SSL.
requireSSL | The server uses and accepts only SSL encrypted connections.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.PEMKeyFile

Type: string

New in version 2.2.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

When SSL is enabled, you must specify net.ssl.PEMKeyFile.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.PEMKeyPassword

Type: string

New in version 2.2.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the net.ssl.PEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongos or mongod will redact the password from all logging and reporting output.

Changed in version 2.6: If the private key in the PEM file is encrypted and you do not specify the net.ssl.PEMKeyPassword option, the mongos or mongod will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.clusterFile

Type: string

New in version 2.6.

Specifies the .pem file that contains the x.509 certificate-key file for membership authentication for the cluster or replica set.

If net.ssl.clusterFile does not specify the .pem file for internal cluster authentication, the cluster uses the .pem file specified in the PEMKeyFile option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.clusterPassword

Type: string

New in version 2.6.

Specifies the password to de-crypt the x.509 certificate-key file specified with --sslClusterFile. Use the net.ssl.clusterPassword option only if the certificate-key file is encrypted. In all cases, the mongos or mongod will redact the password from all logging and reporting output.

If the x.509 key file is encrypted and you do not specify the net.ssl.clusterPassword option, the mongos or mongod will prompt for a passphrase. See SSL Certificate Passphrase.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.CAFile

Type: string

New in version 2.4.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

net.ssl.CRLFile

Type: string

New in version 2.4.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.weakCertificateValidation

Type: boolean

New in version 2.4.

Disables the requirement for SSL certificate validation that --sslCAFile enables. With the net.ssl.weakCertificateValidation option, the mongos or mongod will accept connections when the client does not present a certificate when establishing the connection.

If the client presents a certificate and the mongos or mongod has net.ssl.weakCertificateValidation enabled, the mongos or mongod will validate the certificate using the root certificate chain specified by --sslCAFile and reject clients with invalid certificates.

Use the net.ssl.weakCertificateValidation option if you have a mixed deployment that includes clients that do not or cannot present certificates to the mongos or mongod.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.allowInvalidCertificates

Type: boolean

New in version 2.6.4.

Bypasses the validation checks for SSL certificates on other servers in the cluster and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

net.ssl.FIPSMode

Type: boolean

New in version 2.4.

Directs the mongos or mongod to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the net.ssl.FIPSMode option.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

setParameter

Type: document

Specifies one of the MongoDB parameters described in MongoDB Server Parameters. You can specify multiple setParameter fields.

security

security.keyFile

Type: string

Specifies the path to a key file that stores the shared secret that MongoDB instances use to authenticate to each other in a sharded cluster or replica set. keyFile implies security.authorization. See Authentication Between MongoDB Instances for more information.

security.clusterAuthMode

Type: string

Default: keyFile

New in version 2.6.

The authentication mode used for cluster authentication. If you use internal x.509 authentication, specify so here. This option can have one of the following values:

Value | Description
keyFile | Use a keyfile for authentication. Accept only keyfiles.
sendKeyFile | For rolling upgrade purposes. Send a keyfile for authentication but can accept both keyfiles and x.509 certificates.
sendX509 | For rolling upgrade purposes. Send the x.509 certificate for authentication but can accept both keyfiles and x.509 certificates.
x509 | Recommended. Send the x.509 certificate for authentication and accept only x.509 certificates.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see Configure mongod and mongos for SSL.

security.authorization

Type: string

Default: disabled

Enables Role-Based Access Control (RBAC) to govern each user’s access to database resources and operations.

Set this option to one of the following:

Value | Description
enabled | A user can access only the database resources and actions for which they have been granted privileges.
disabled | A user can access any database and perform any action.

See Authorization for more information.

The security.authorization option is available only for mongod.

security.sasl.hostName

Type: string

A fully qualified server domain name for the purpose of configuring SASL and Kerberos authentication. The SASL hostname overrides the hostname only for the configuration of SASL and Kerberos.

For mongo shell and other MongoDB tools to connect to the new hostName, see the gssapiHostName option in the mongo shell and other tools.

security.sasl.serviceName

Type: string

Registered name of the service using SASL. This option allows you to override the default Kerberos service name component of the Kerberos principal name, on a per-instance basis. If unspecified, the default value is mongodb.

MongoDB permits setting this option only at startup. The setParameter can not change this setting.

This option is available only in MongoDB Enterprise.

Important

Ensure that your driver supports alternate service names. For mongo shell and other MongoDB tools to connect to the new serviceName, see the gssapiServiceName option.

security.sasl.saslauthdSocketPath

Type: string

The path to the UNIX domain socket file for saslauthd.

security.javascriptEnabled

Type: boolean

Default: True

Enables or disables the JavaScript execution engine. When disabled, $where, mapReduce, group and any other operation that requires a mongod instance to execute JavaScript.

operationProfiling

operationProfiling.slowOpThresholdMs

Type: integer

Default: 100

The threshold in milliseconds at which the database profiler considers a query slow. MongoDB records all slow queries to the log, even when the database profiler is off. When the profiler is on, it writes to the system.profile collection. See the profile command for more information on the database profiler.

The operationProfiling.slowOpThresholdMs option is available only for mongod.

operationProfiling.mode

Type: string

Default: off

Changes the level of database profiling, which inserts information about operation performance into standard output or a log file. Specify one of the following levels:

Level | Setting
off | Off. No profiling.
slowOp | On. Only includes slow operations.
all | On. Includes all operations.

Database profiling can impact database performance. Enable this option only after careful consideration.

The operationProfiling.mode option is available only for mongod.

storage

storage.dbPath

Type: string

Default: /data/db on Linux and OS X, \data\db on Windows

The directory where the mongod instance stores its data.

If you installed MongoDB using a package management system, check the /etc/mongodb.conf file provided by your packages to see the directory is specified.

The storage.dbPath option is available only for mongod.

storage.directoryPerDB

Type: boolean

Default: False

Stores each database’s files in its own folder in the data directory. When applied to an existing system, the directoryPerDB option alters the storage pattern of the data directory.

Use this option in conjunction with your file system and device configuration so that MongoDB will store data on a number of distinct disk devices to increase write throughput or disk capacity.

Warning

To enable this option for an existing system, migrate the database-specific data files to the new directory structure before enabling directoryPerDB. Database-specific data files begin with the name of an existing database and end with either “ns” or a number. For example, the following data directory includes files for the local and test databases:

journal
mongod.lock
local.0
local.1
local.ns
test.0
test.1
test.ns

After migration, the data directory would have the following structure:

journal
mongod.lock
local/local.0
local/local.1
local/local.ns
test/test.0
test/test.1
test/test.ns

The storage.directoryPerDB option is available only for mongod.

storage.indexBuildRetry

Type: boolean

Default: True

Selects whether mongod rebuilds incomplete indexes on the next start up. This applies in cases where mongod restarts after it has shut down or stopped in the middle of an index build. In such cases, mongod always removes any incomplete indexes, and then, by default, attempts to rebuild them. To stop mongod from rebuilding indexes, set this option to false.

The storage.indexBuildRetry option is available only for mongod.

storage.preallocDataFiles

Type: boolean

Default: True

Enables or disables data file preallocation.

Do not disable data file preallocation in production systems. Only use this option for testing and with small data sets where you frequently drop databases.

storage.nsSize

Type: integer

Default: 16

Specifies the default size for namespace files, which are files that end in .ns. Each collection and index counts as a namespace.

Use this setting to control size for newly created namespace files. This option has no impact on existing files. The maximum size for a namespace file is 2047 megabytes. The default value of 16 megabytes provides for approximately 24,000 namespaces.

The storage.nsSize option is available only for mongod.

storage.quota.enforced

Type: Boolean

Default: false

Enables a maximum limit for the number data files each database can have. When running with the storage.quota.enforced option, MongoDB has a maximum of 8 data files per database. Adjust the quota with storage.quota.maxFilesPerDB.

The storage.quota.enforced option is available only for mongod.

storage.quota.maxFilesPerDB

Type: integer

Default: 8

Modifies the limit on the number of data files per database. storage.quota.maxFilesPerDB option requires that you set storage.quota.enforced.

The storage.quota.maxFilesPerDB option is available only for mongod.

storage.smallFiles

Type: boolean

Default: False

Sets MongoDB to use a smaller default file size. The storage.smallFiles option reduces the initial size for data files and limits the maximum size to 512 megabytes. storage.smallFiles also reduces the size of each journal file from 1 gigabyte to 128 megabytes. Use storage.smallFiles if you have a large number of databases that each holds a small quantity of data.

The storage.smallFiles option can lead the mongod instance to create a large number of files, which can affect performance for larger databases.

The storage.smallFiles option is available only for mongod.

storage.syncPeriodSecs

Type: number

Default: 60

Controls how much time can pass before MongoDB flushes data to the data files via an fsync operation. Do not set this value on production systems. In almost every situation, you should use the default setting.

Warning

If you set storage.syncPeriodSecs to 0, MongoDB will not sync the memory mapped files to disk.

The mongod process writes data very quickly to the journal and lazily to the data files. syncPeriodSecs has no effect on the journal files or journaling.

The serverStatus command reports the background flush thread’s status via the backgroundFlushing field.

The storage.syncPeriodSecs option is available only for mongod.

storage.repairPath

Type: string

Default: A _tmp directory within the path specified by the dbPath option.

Specifies a working directory that MongoDB will use during the --repair operation. After --repair completes, the data files in dbPath and the storage.repairPath directory is empty.

The storage.repairPath option is available only for mongod.

storage.journal.enabled

Type: boolean

Default: true on 64-bit systems, false on 32-bit systems

Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the --dbpath option. The mongod enables journaling by default on 64-bit builds of versions after 2.0.

The storage.journal.enabled option is available only for mongod.

storage.journal.debugFlags

Type: integer

Provides functionality for testing. Not for general use, and will affect data file integrity in the case of abnormal system shutdown.

The storage.journal.debugFlags option is available only for mongod.

storage.journal.commitIntervalMs

Type: number

Default: 100 or 30

The maximum amount of time the mongod process allows between journal operations. Values can range from 2 to 300 milliseconds. Lower values increase the durability of the journal, at the expense of disk performance.

The default journal commit interval is 100 milliseconds if a single block device (e.g. physical volume, RAID device, or LVM volume) contains both the journal and the data files.

If the journal is on a different block device than the data files the default journal commit interval is 30 milliseconds.

To force mongod to commit to the journal more frequently, you can specify j:true. When a write operation with j:true is pending, mongod will reduce commitIntervalMs to a third of the set value.

The storage.journal.commitIntervalMs option is available only for mongod.

replication

replication.oplogSizeMB

Type: integer

Specifies a maximum size in megabytes for the replication operation log (i.e., the oplog). The mongod process creates an oplog based on the maximum amount of space available. For 64-bit systems, the oplog is typically 5% of available disk space. Once the mongod has created the oplog for the first time, changing the replication.oplogSizeMB option will not affect the size of the oplog.

See Oplog Size for more information.

The replication.oplogSizeMB option is available only for mongod.

replication.replSetName

Type: string

Configures replication. Specify a replica set name as an argument to this set. All hosts in the replica set must have the same set name.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The replication.replSetName option is available only for mongod.

replication.secondaryIndexPrefetch

Type: string

Default: all

New in version 2.2.

Determines which indexes secondary members of a replica set load into memory before applying operations from the oplog. By default secondaries load all indexes related to an operation into memory before applying operations from the oplog. This option can have one of the following values:

Value | Description
none | Secondaries do not load indexes into memory.
all | Secondaries load all indexes related to an operation.
_id_only | Secondaries load no additional indexes into memory beyond the already existing _id index.

The replication.secondaryIndexPrefetch option is available only for mongod.

sharding

sharding.clusterRole

Type: string

Selects the role the mongod instance has in the sharded cluster. Set this option to one of the following:

Value | Description
configsvr | Start this instance as a config server. The instance starts on port 27019 by default.
shardsvr | Start this instance as a shard. The instance starts on port 27018 by default.

The sharding.clusterRole option is available only for mongod.

sharding.archiveMovedChunks

Type: boolean

New in version 2.4.

Changed in version 2.6: sharding.archiveMovedChunks is now the default behavior of MongoDB.

When true, the sharding.archiveMovedChunks option forces the mongod instances to save all documents migrated from this shard during chunk migrations to the moveChunk directory of the storage.dbPath. MongoDB does not delete data stored in moveChunk.

auditLog

auditLog.destination

Type: string

New in version 2.6.

Enables auditing. The auditLog.destination option can have one of the following values:

Value
Description

syslog

Output the audit events to syslog in JSON format. Not available on Windows. Audit messages have a syslog severity level of info and a facility level of user.

The syslog message limit can result in the truncation of audit messages. The auditing system will neither detect the truncation nor error upon its occurrence.

console
Output the audit events to stdout in JSON format.

file
Output the audit events to the file specified in --auditPath in the format specified in --auditFormat.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

auditLog.format

Type: string

New in version 2.6.

Specifies the format of the output file for auditing if --auditDestination is file. The auditLog.format option can have one of the following values:

Value | Description
JSON | Output the audit events in JSON format to the file specified in --auditPath.
BSON | Output the audit events in BSON binary format to the file specified in --auditPath.

Printing audit events to a file in JSON format degrades server performance more than printing to a file in BSON format.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

auditLog.path

Type: string

New in version 2.6.

Specifies the output file for auditing if --auditDestination has value of file. The auditLog.path option can take either a full path name or a relative path name.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

auditLog.filter

Type: string representation of a document

New in version 2.6.

Specifies the filter to limit the types of operations the audit system records. The option takes a string representation of a query document of the form:

{ <field1>: <expression1>, ... }

The <field> can be any field in the audit message, including fields returned in the param document. The <expression> is a query condition expression.

To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.

To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

snmp

snmp.subagent

Type: boolean

Runs SNMP as a subagent. For more information, see Monitor MongoDB With SNMP on Linux.

The snmp.subagent option is available only for mongod.

snmp.master

Type: boolean

Runs SNMP as a master. For more information, see Monitor MongoDB With SNMP on Linux.

The snmp.master option is available only for mongod.

mongos-only Options

replication.localPingThresholdMs

Type: integer

Default: 15

Affects the logic that mongos uses when selecting replica set members to pass read operations from clients. Specify a value in milliseconds. The default value of 15 corresponds to the default value in all of the client drivers.

When mongos receives a request that permits reads to secondary members, the mongos will:

Find the member of the set with the lowest ping time.

Construct a list of replica set members that is within a ping time of 15 milliseconds of the nearest suitable member of the set.

If you specify a value for the replication.localPingThresholdMs option, mongos will construct the list of replica members that are within the latency allowed by this value.

Select a member to read from at random from this list.

The ping time used for a member compared by the replication.localPingThresholdMs setting is a moving average of recent ping times, calculated at most every 10 seconds. As a result, some queries may reach members above the threshold until the mongos recalculates the average.

See the Member Selection section of the read preference documentation for more information.

sharding.autoSplit

Type: boolean

Prevents mongos from automatically inserting metadata splits in a sharded collection. If set on all mongos instances, this prevents MongoDB from creating new chunks as the data in a collection grows.

Because any mongos in a cluster can create a split, to totally disable splitting in a cluster you must set sharding.autoSplit on all mongos.

Warning

With sharding.autoSplit enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution.

sharding.configDB

Type: string

Specifies the configuration database for the sharded cluster. You must specify either 1 or 3 configuration servers, in a comma separated list. Always use 3 config servers in production environments.

All mongos instances must specify the exact same value for sharding.configDB

If your configuration databases reside in more that one data center, order the hosts so that first config sever in the list is the closest to the majority of your mongos instances.

Warning

Never remove a config server from this setting, even if the config server is not available or offline.

sharding.chunkSize

Type: integer

Default: 64

Determines the size in megabytes of each chunk in the sharded cluster. A size of 64 megabytes is ideal in most deployments: larger chunk size can lead to uneven data distribution; smaller chunk size can lead to inefficient movement of chunks between nodes.

This option affects chunk size only when you initialize the cluster for the first time. If you later modify the option, the new value has no effect. See the Modify Chunk Size in a Sharded Cluster procedure if you need to change the chunk size on an existing sharded cluster.

Windows Service Options

processManagement.windowsService.serviceName

Type: string

Default: MongoDB

Set the service name of mongos or mongod when running as a Windows Service. Use this name with the net start <name> and net stop <name> operations.

You must use processManagement.windowsService.serviceName in conjunction with either the --install or --remove install option.

processManagement.windowsService.displayName

Type: string

Default: MongoDB

Sets the name listed for MongoDB on the Services administrative application.

processManagement.windowsService.description

Type: string

Default: MongoDB Server

Sets the mongos or mongod service description.

You must use processManagement.windowsService.description in conjunction with the --install option.

For descriptions that contain spaces, you must enclose the description in quotes.

processManagement.windowsService.serviceUser

Type: string

Runs the mongos or mongod service in the context of a certain user. This user must have “Log on as a service” privileges.

You must use processManagement.windowsService.serviceUser in conjunction with the --install option.

processManagement.windowsService.servicePassword

Type: string

Sets the password for <user> for mongos or mongod when running with the --serviceUser option.

You must use processManagement.windowsService.servicePassword in conjunction with the --install option.

MongoDB Server Parameters

Synopsis

MongoDB provides a number of configuration options that are accessible via the --setParameter option to mongod. This document documents all of these options.

For additional run time configuration options, see Configuration File Options and Manual Page for mongod.

Parameters

enableLocalhostAuthBypass

New in version 2.4.

Specify 0 to disable localhost authentication bypass. Enabled by default.

enableLocalhostAuthBypass is not available using setParameter database command. Use the setParameter option in the configuration file or the --setParameter option on the command line.

enableTestCommands

New in version 2.4.

enableTestCommands enables a set of internal commands useful for internal testing operations. enableTestCommands is only available when starting mongod and you cannot use setParameter to modify this parameter. Consider the following mongod invocation, which sets enableTestCommands:

mongod --setParameter enableTestCommands=1

enableTestCommands provides access to the following internal commands:

captrunc

configureFailPoint

emptycapped

godinsert

_hashBSONElement

journalLatencyTest

replSetTest

_skewClockCommand

sleep

_testDistLockWithSkew

_testDistLockWithSyncCluster

journalCommitInterval

Specify an integer between 1 and 500 signifying the number of milliseconds (ms) between journal commits.

Consider the following example which sets the journalCommitInterval to 200 ms:

db.getSiblingDB("admin").runCommand( { setParameter: 1, journalCommitInterval: 200 } )

See also

commitIntervalMs.

logUserIds

New in version 2.4.

Specify 1 to enable logging of userids.

Disabled by default.

logLevel

Specify an integer between 0 and 5 signifying the verbosity of the logging, where 5 is the most verbose.

Consider the following example which sets the logLevel to 2:

use admin
db.runCommand( { setParameter: 1, logLevel: 2 } )

See also

verbosity.

notablescan

Specify whether all queries must use indexes. If 1, MongoDB will not execute queries that require a table scan and will return an error.

Consider the following example which sets notablescan to 1 or true:

db.getSiblingDB("admin").runCommand( { setParameter: 1, notablescan: 1 } )

Setting notablescan to 1 can be useful for testing application queries, for example, to identify queries that scan an entire collection and cannot use an index.

To detect unindexed queries without notablescan, consider reading the Evaluate Performance of Current Operations and Optimize Query Performance sections and using the logLevel parameter, mongostat and profiling.

Don’t run production mongod instances with notablescan because preventing table scans can potentially affect queries in all databases, including administrative queries.

replIndexPrefetch

New in version 2.2.

Use replIndexPrefetch in conjunction with replSetName when configuring a replica set. The default value is all and available options are:

none

all

_id_only

By default secondary members of a replica set will load all indexes related to an operation into memory before applying operations from the oplog. You can modify this behavior so that the secondaries will only load the _id index. Specify _id_only or none to prevent the mongod from loading any index into memory.

replApplyBatchSize

New in version 1.6.

Specify the number of oplog entries to apply as a single batch. replApplyBatchSize must be an integer between 1 and 1024. The default value is 1. This option only applies to master/slave configurations and is valid only on a mongod started with the --slave command line option.

Batch sizes must be 1 for members with slavedelay configured.

saslHostName

New in version 2.4.

saslHostName overrides MongoDB’s default hostname detection for the purpose of configuring SASL and Kerberos authentication.

saslHostName does not affect the hostname of the mongod or mongos instance for any purpose beyond the configuration of SASL and Kerberos.

You can only set saslHostName during start-up, and cannot change this setting using the setParameter database command.

Note

saslHostName supports Kerberos authentication and is only included in MongoDB Enterprise. For Linux systems, see Configure MongoDB with Kerberos Authentication on Linux for more information.

supportCompatibilityFormPrivilegeDocuments

New in version 2.4.

Deprecated since version 2.6: supportCompatibilityFormPrivilegeDocuments has no effect in 2.6 and will be removed in 2.8.

supportCompatibilityFormPrivilegeDocuments is not available using setParameter database command. Use the setParameter option in the configuration file or the --setParameter option on the command line.

syncdelay

Specify the interval in seconds between fsync operations where mongod flushes its working memory to disk. By default, mongod flushes memory to disk every 60 seconds. In almost every situation you should not set this value and use the default setting.

Consider the following example which sets the syncdelay to 60 seconds:

db.getSiblingDB("admin").runCommand( { setParameter: 1, syncdelay: 60 } )

See also

syncPeriodSecs and journalCommitInterval.

traceExceptions

New in version 2.2.

Configures mongod to log full source code stack traces for every database and socket C++ exception, for use with debugging. If true, mongod will log full stack traces.

Consider the following example which sets the traceExceptions to true:

db.getSiblingDB("admin").runCommand( { setParameter: 1, traceExceptions: true } )

See also

systemLog.traceAllExceptions

quiet

Sets quiet logging mode. If 1, mongod will go into a quiet logging mode which will not log the following events/activities:

connection events;

the drop command, the dropIndexes command, the diagLogging command, the validate command, and the clean command; and

replication synchronization activities.

Consider the following example which sets the quiet to 1:

db = db.getSiblingDB("admin")
db.runCommand( { setParameter: 1, quiet: 1 } )

See also

quiet

textSearchEnabled

Deprecated since version 2.6: MongoDB enables the text search feature by default. Manual enabling of this feature is unnecessary.

Enables the text search feature. When manually enabling, you must enable on each and every mongod for replica sets.

releaseConnectionsAfterResponse

New in version 2.2.4: and 2.4.2

Changes the behavior of the connection pool that mongos uses to connect to the shards. As a result, each mongos should need to maintain fewer connections to each shard. When enabled, the mongos will release a connection into the thread pool after each read operation or command.

Warning

For applications that do not use the default, journaled, or replica acknowledged write concern modes of the driver, releaseConnectionsAfterResponse will affect the meaning of getLastError.

If an application allows read operations in between write operations and getLastError calls, the resulting getLastError will not report on the success of the proceeding write operation.

Use with caution.

To enable, use the following command while connected to a mongos:

db.getSiblingDB('admin').runCommand( { setParameter: 1, releaseConnectionsAfterResponse: true } )

Alternately, you may start the mongos instance with the following run-time option:

mongos --setParameter releaseConnectionsAfterResponse=true

To change this policy for the entire cluster, you must set releaseConnectionsAfterResponse on each mongos instance in the cluster.

connPoolMaxShardedConnectionsPerHost

New in version 2.6.

Default: 200

mongos instances reuse connections to the shards to service multiple requests. However, in some situations very active mongos instances may need to maintain a pool larger than the default maximum of 200 connections.

The connPoolMaxShardedConnectionsPerHost value defines the size of the largest connection pool that mongos instances will maintain for communication to the shards. The size of a pool does not prevent mongos instances from creating additional connections, but does prevent the connection pools from retaining connections above this limit.

Increase the connPoolMaxShardedConnectionsPerHost value only if the number of connections in a connection pool has a high level of churn, or if the total number of created connections increase.

connPoolMaxShardedConnectionsPerHost only applies for mongos instances. You can only set connPoolMaxShardedConnectionsPerHost during start up in the config file or on the command line, as follows to increase the size of the connection pool:

mongos --setParameter connPoolMaxShardedConnectionsPerHost=250

connPoolMaxConnectionsPerHost

New in version 2.6.

Default: 200

mongod maintains connection pools for outgoing connections to other mongod instances to maximize connection reuse.

The connPoolMaxConnectionsPerHost value defines the size of the largest connection pool that mongod instances will maintain for inter-process communication. The size of a pool does not prevent a mongod from creating additional connections, but does prevent a connection pool from retaining connections in excess of the value of connPoolMaxConnectionsPerHost.

Only adjust this setting if your driver does not pool connections and you’re using authentication in the context of a sharded cluster.

connPoolMaxShardedConnectionsPerHost applies to mongod instances only. You can only set connPoolMaxShardedConnectionsPerHost during start up in the config file or on the command line, as follows to increase the size of the connection pool:

mongos --setParameter connPoolMaxConnectionsPerHost=250

authenticationMechanisms

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specifies the list of authentication mechanisms the server accepts. Set this to one or more of the following values. If you specify multiple values, use a comma-separated list and no spaces. For descriptions of the authentication mechanisms, see Authentication.

Value | Description
MONGODB-CR | MongoDB challenge/response authentication.
MONGODB-X509 | MongoDB SSL certificate authentication.
PLAIN | External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].
GSSAPI | External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

For example, to specify PLAIN as the authentication mechanism, use the following command:

mongod --setParameter authenticationMechanisms=PLAIN --auth

saslauthdPath

Note

Available only in MongoDB Enterprise (except MongoDB Enterprise for Windows).

Specify the path to the Unix Domain Socket of the saslauthd instance to use for proxy authentication.

sslMode

New in version 2.6.

Set the net.ssl.mode to either preferSSL or requireSSL. Useful during rolling upgrade to SSL to minimize downtime.

The default distribution of MongoDB [http://www.mongodb.org/downloads] does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Configure mongod and mongos for SSL for more information about SSL and MongoDB.

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "preferSSL" } )

clusterAuthMode

New in version 2.6.

Set the clusterAuthMode to either sendX509 or x509. Useful during rolling upgrade to use x509 for membership authentication to minimize downtime.

The default distribution of MongoDB [http://www.mongodb.org/downloads] does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Configure mongod and mongos for SSL for more information about SSL and MongoDB.

db.getSiblingDB('admin').runCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

ttlMonitorEnabled

New in version 2.4.6.

To support TTL Indexes, mongod instances have a background thread that is responsible for deleting documents from collections with TTL indexes.

To disable this worker thread for a mongod, set ttlMonitorEnabled to false, as in the following operations:

db.getSiblingDB('admin').runCommand( { setParameter: 1, ttlMonitorEnabled: false } )

Alternately, you may disable the thread at run-time by starting the mongod instance with the following option:

mongod --setParameter ttlMonitorEnabled=false

saslServiceName

New in version 2.4.6.

Allows users to override the default Kerberos service name component of the Kerberos principal name, on a per-instance basis. If unspecified, the default value is mongodb.

MongoDB only permits setting saslServiceName at startup. The setParameter command can not change this setting.

saslServiceName is only available in MongoDB Enterprise.

Important

Ensure that your driver supports alternate service names.

newCollectionsUsePowerOf2Sizes

New in version 2.6.

Default: true.

mongod uses an allocation strategy called usePowerOf2Sizes where each record has a size, in bytes that is a power of 2 (e.g. 32, 64, 128, 256, 512...16777216.) The minimum allocation for a document is 32 bytes.

MongoDB stores documents in contiguous spaces on disk, and each record includes both the document itself and some additional space to allow the document to grow slightly through updates.

By default, all new collections, created after 2.6 use the usePowerOf2Sizes strategy. To revert to the prior exact fit allocation strategy, set newCollectionsUsePowerOf2Sizes to false.

New collections include those: created during initial sync, as well as those created by the mongorestore and mongoimport tools, by running mongod with the --repair option, as well as the restoreDatabase command.

Issue the following command to change the allocation strategy for a running mongod instance:

db.getSiblingDB('admin').runCommand( { setParameter: 1, newCollectionsUsePowerOf2Sizes: false } )

You can also set newCollectionsUsePowerOf2Sizes at run-time with the following operation.

mongod --setParameter newCollectionsUsePowerOf2Sizes=false

userCacheInvalidationIntervalSecs

New in version 2.6.

Default: 600.

On a mongos instance, this specifies the amount of time in seconds to allow before the mongos instance purges the in-memory cache of user objects. The cache includes the users’ credentials and roles.

This parameter has a minimum value of 30 seconds and a maximum value of 86400 seconds (24 hours).

failIndexKeyTooLong

New in version 2.6.

In MongoDB 2.6, if you attempt to insert or update a document so that the value of an indexed field is longer than the Index Key Length Limit, the operation will fail and return an error to the client. In previous versions of MongoDB, these operations would successfully insert or modify a document but the index or indexes would not include references to the document.

To avoid this issue, consider using hashed indexes or indexing a computed value. If you have an existing data set and want to disable this behavior so you can upgrade and then gradually resolve these indexing issues, you can use:parameter:failIndexKeyTooLong to disable this behavior.

failIndexKeyTooLong defaults to true. When false, a 2.6 mongod instance will provide the 2.4 behavior.

Issue the following command to disable the index key length validation: for a running:program:mongod instance:

db.getSiblingDB('admin').runCommand( { setParameter: 1, failIndexKeyTooLong: false } )

You can also set failIndexKeyTooLong at run-time with the following operation.

mongod --setParameter failIndexKeyTooLong=false

auditAuthorizationSuccess

Note

Available only in MongoDB Enterprise [http://www.mongodb.com/products/mongodb-enterprise].

New in version 2.6.5.

Default: false

Enables the auditing of authorization successes for the authCheck action.

When auditAuthorizationSuccess is false, the audit system only logs the authorization failures for authCheck.

To enable the audit of authorization successes, issue the following command:

db.runAdminCommand( { setParameter: 1, auditAuthorizationSuccess: true } )

Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

MongoDB Limits and Thresholds

This document provides a collection of hard and soft limitations of the MongoDB system.

BSON Documents

BSON Document Size

The maximum BSON document size is 16 megabytes.

The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See mongofiles and the documentation for your driver for more information about GridFS.

Nested Depth for BSON Documents

Changed in version 2.2.

MongoDB supports no more than 100 levels of nesting for BSON documents.

Namespaces

Namespace Length

Each namespace, including database and collection name, must be shorter than 123 bytes.

Number of Namespaces

The limitation on the number of namespaces is the size of the namespace file divided by 628.

A 16 megabyte namespace file can support approximately 24,000 namespaces. Each collection and index is a namespace.

Size of Namespace File

Namespace files can be no larger than 2047 megabytes.

By default namespace files are 16 megabytes. You can configure the size using the nsSize option.

Indexes

Index Key Limit

The total size of an index entry, which can include structural overhead depending on the BSON type, must be less than 1024 bytes.

Changed in version 2.6: MongoDB 2.6 implements a stronger enforcement of the limit on index key:

MongoDB will not create an index on a collection if the index entry for an existing document exceeds the index key limit. Previous versions of MongoDB would create the index but not index such documents.

Reindexing operations will error if the index entry for an indexed field exceeds the index key limit. Reindexing operations occur as part of compact and repairDatabase commands as well as the db.collection.reIndex() method.

Because these operations drop all the indexes from a collection and then recreate them sequentially, the error from the index key limit prevents these operations from rebuilding any remaining indexes for the collection and, in the case of the repairDatabase command, from continuing with the remainder of the process.

MongoDB will not insert into an indexed collection any document with an indexed field whose corresponding index entry would exceed the index key limit, and instead, will return an error. Previous versions of MongoDB would insert but not index such documents.

Updates to the indexed field will error if the updated value causes the index entry to exceed the index key limit.

If an existing document contains an indexed field whose index entry exceeds the limit, any update that results in the relocation of that document on disk will error.

mongorestore and mongoimport will not insert documents that contain an indexed field whose corresponding index entry would exceed the index key limit.

In MongoDB 2.6, secondary members of replica sets will continue to replicate documents with an indexed field whose corresponding index entry exceeds the index key limit on initial sync but will print warnings in the logs.

Secondary members also allow index build and rebuild operations on a collection that contains an indexed field whose corresponding index entry exceeds the index key limit but with warnings in the logs.

With mixed version replica sets where the secondaries are version 2.6 and the primary is version 2.4, secondaries will replicate documents inserted or updated on the 2.4 primary, but will print error messages in the log if the documents contain an indexed field whose corresponding index entry exceeds the index key limit.

For existing sharded collections, chunk migration will fail if the chunk has a document that contains an indexed field whose index entry exceeds the index key limit.

Number of Indexes per Collection

A single collection can have no more than 64 indexes.

Index Name Length

Fully qualified index names, which includes the namespace and the dot separators (i.e. <database name>.<collection name>.$<index name>), cannot be longer than 128 characters.

By default, <index name> is the concatenation of the field names and index type. You can explicitly specify the <index name> to the ensureIndex() method to ensure that the fully qualified index name does not exceed the limit.

Number of Indexed Fields in a Compound Index

There can be no more than 31 fields in a compound index.

Queries cannot use both text and Geospatial Indexes

You cannot combine the text command, which requires a special text index, with a query operator that requires a different type of special index. For example you cannot combine text command with the $near operator.

Fields with 2dsphere Indexes can only hold Geometries

Fields with 2dsphere indexes must hold geometry data in the form of coordinate pairs or GeoJSON data. If you attempt to insert a document with non-geometry data in a 2dsphere indexed field, or build a 2dsphere index on a collection where the indexed field has non-geometry data, the operation will fail.

See also

The unique indexes limit in Sharding Operational Restrictions.

Data

Maximum Number of Documents in a Capped Collection

Changed in version 2.4.

If you specify a maximum number of documents for a capped collection using the max parameter to create, the limit must be less than 2³² documents. If you do not specify a maximum number of documents when creating a capped collection, there is no limit on the number of documents.

Data Size

A single mongod instance cannot manage a data set that exceeds maximum virtual memory address space provided by the underlying operating system.

Virtual Memory Limitations

Operating System | Journaled | Not Journaled
Linux | 64 terabytes | 128 terabytes
Windows Server 2012 R2 and Windows 8.1 | 64 terabytes | 128 terabytes
Windows (otherwise) | 4 terabytes | 8 terabytes

Number of Collections in a Database

The maximum number of collections in a database is a function of the size of the namespace file and the number of indexes of collections in the database.

See Number of Namespaces for more information.

Replica Sets

Number of Members of a Replica Set

Replica sets can have no more than 12 members.

Number of Voting Members of a Replica Set

Replica sets can have up to 7 voting members. For replica sets with more than 7 total members, see Non-Voting Members.

Maximum Size of Auto-Created Oplog

Changed in version 2.6.

If you do not explicitly specify an oplog size (i.e. with oplogSizeMB or --oplogSize) MongoDB will create an oplog that is no larger than 50 gigabytes.

Sharded Clusters

Sharded clusters have the restrictions and thresholds described here.

Sharding Operational Restrictions

Operations Unavailable in Sharded Environments

The group does not work with sharding. Use mapReduce or aggregate instead.

db.eval() is incompatible with sharded collections. You may use db.eval() with un-sharded collections in a shard cluster.

$where does not permit references to the db object from the $where function. This is uncommon in un-sharded collections.

The $isolated update modifier does not work in sharded environments.

$snapshot queries do not work in sharded environments.

The geoSearch command is not supported in sharded environments.

Covered Queries in Sharded Clusters

MongoDB does not support covered queries for sharded collections.

Sharding Existing Collection Data Size

For existing collections that hold documents, MongoDB supports enabling sharding on any collections that contains less than 256 gigabytes of data. MongoDB may be able to shard collections with as many as 400 gigabytes depending on the distribution of document sizes. The precise size of the limitation is a function of the chunk size and the data size. Consider the following table:

Shard Key Size | 512 bytes | 200 bytes
Number of Splits | 31,558 | 85,196
Max Collection Size (1 MB Chunk Size) | 31 GB | 83 GB
Max Collection Size (64 MB Chunk Size) | 1.9 TB | 5.3 TB

The data in this chart reflects documents with no data other than the shard key values and therefore represents the smallest possible data size that could reach this limit.

Important

Sharded collections may have any size, after successfully enabling sharding.

Single Document Modification Operations in Sharded Collections

All update() and remove() operations for a sharded collection that specify the justOne or multi: false option must include the shard key or the _id field in the query specification. update() and remove() operations specifying justOne or multi: false in a sharded collection without the shard key or the _id field return an error.

Unique Indexes in Sharded Collections

MongoDB does not support unique indexes across shards, except when the unique index contains the full shard key as a prefix of the index. In these situations MongoDB will enforce uniqueness across the full key, not a single field.

See

Enforce Unique Keys for Sharded Collections for an alternate approach.

Maximum Number of Documents Per Chunk to Migrate

MongoDB cannot move a chunk if the number of documents in the chunk exceeds either 250000 documents or 1.3 times the number of average sized documents that the maximum chunk size can hold.

Shard Key Limitations

Shard Key Size

A shard key cannot exceed 512 bytes.

Shard Key Index Type

A shard key index can be an ascending index on the shard key, a compound index that start with the shard key and specify ascending order for the shard key, or a hashed index.

A shard key index cannot be an index that specifies a multikey index, a text index or a geospatial index on the shard key fields.

Shard Key is Immutable

You cannot change a shard key after sharding the collection. If you must change a shard key:

Dump all data from MongoDB into an external format.

Drop the original sharded collection.

Configure sharding using the new shard key.

Pre-split the shard key range to ensure initial even distribution.

Restore the dumped data into MongoDB.

Shard Key Value in a Document is Immutable

After you insert a document into a sharded collection, you cannot change the document’s value for the field or fields that comprise the shard key. The update() operation will not modify the value of a shard key in an existing document.

Monotonically Increasing Shard Keys Can Limit Insert Throughput

For clusters with high insert volumes, a shard keys with monotonically increasing and decreasing keys can affect insert throughput. If your shard key is the _id field, be aware that the default values of the _id fields are ObjectIds which have generally increasing values.

When inserting documents with monotonically increasing shard keys, all inserts belong to the same chunk on a single shard. The system will eventually divide the chunk range that receives all write operations and migrate its contents to distribute data more evenly. However, at any moment the cluster can direct insert operations only to a single shard, which creates an insert throughput bottleneck.

If the operations on the cluster are predominately read operations and updates, this limitation may not affect the cluster.

To avoid this constraint, use a hashed shard key or select a field that does not increase or decrease monotonically.

Changed in version 2.4: Hashed shard keys and hashed indexes store hashes of keys with ascending values.

Operations

Sorted Documents

MongoDB will only return sorted results on fields without an index if the combined size of all documents in the sort operation, plus a small overhead, is less than 32 megabytes.

Aggregation Pipeline Operation

Changed in version 2.6.

Pipeline stages have a limit of 100 megabytes of RAM. If a stage exceeds this limit, MongoDB will produce an error. To allow for the handling of large datasets, use the allowDiskUse option to enable aggregation pipeline stages to write data to temporary files.

See also

$sort and Memory Restrictions and $group Operator and Memory.

2d Geospatial queries cannot use the $or operator

See

$or and 2d Index Internals.

Area of GeoJSON Polygons

For $geoIntersects or $geoWithin queries, GeoJSON geometries must have an area less than the area of a single hemisphere. For geometries larger than a single hemisphere, MongoDB queries for the smaller of the complementary geometries. For geometries equal to a single hemisphere, MongoDB makes no guarantees as to which geometry (the specified geometry or the complementary) it uses.

Write Command Operation Limit Size

Write commands can accept no more than 1000 operations. The Bulk() operations in the mongo shell and comparable methods in the drivers do not have this limit.

Naming Restrictions

Database Name Case Sensitivity

MongoDB does not permit database names that differ only by the case of the characters.

Restrictions on Database Names for Windows

Changed in version 2.2: Restrictions on Database Names for Windows.

For MongoDB deployments running on Windows, MongoDB will not permit database names that include any of the following characters:

/\. "$*<>:|?

Also, database names cannot contain the null character.

Restrictions on Database Names for Unix and Linux Systems

For MongoDB deployments running on Unix and Linux systems, MongoDB will not permit database names that include any of the following characters:

/\. "$

Also, database names cannot contain the null character.

Length of Database Names

Database names cannot be empty and must have fewer than 64 characters.

Restriction on Collection Names

New in version 2.2.

Collection names should begin with an underscore or a letter character, and cannot:

contain the $.

be an empty string (e.g. "").

contain the null character.

begin with the system. prefix. (Reserved for internal use.)

In the mongo shell, use db.getCollection() to specify collection names that might interact with the shell or are not valid JavaScript.

Restrictions on Field Names

Field names cannot contain dots (i.e. .) or null characters, and they must not start with a dollar sign (i.e. $). See Dollar Sign Operator Escaping for an alternate approach.

Connection String URI Format

This document describes the URI format for defining connections between applications and MongoDB instances in the official MongoDB drivers.

Standard Connection String Format

This section describes the standard format of the MongoDB connection URI used to connect to a MongoDB database server. The format is the same for all official MongoDB drivers. For a list of drivers and links to driver documentation, see MongoDB Drivers and Client Libraries.

The following is the standard URI connection scheme:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

The components of this string are:

mongodb://

A required prefix to identify that this is a string in the standard connection format.

username:password@

Optional. If specified, the client will attempt to log in to the specific database using these credentials after connecting to the mongod instance.

host1

This the only required part of the URI. It identifies a server address to connect to. It identifies either a hostname, IP address, or UNIX domain socket.

:port1

Optional. The default value is :27017 if not specified.

hostX

Optional. You can specify as many hosts as necessary. You would specify multiple hosts, for example, for connections to replica sets.

:portX

Optional. The default value is :27017 if not specified.

/database

Optional. The name of the database to authenticate if the connection string includes authentication credentials in the form of username:password@. If /database is not specified and the connection string includes credentials, the driver will authenticate to the admin database.

?options

Connection specific options. See Connection String Options for a full description of these options.

If the connection string does not specify a database/ you must specify a slash (i.e. /) between the last hostN and the question mark that begins the string of options.

Example

To describe a connection to a replica set named test, with the following mongod hosts:

db1.example.net on port 27017 and

db2.example.net on port 2500.

You would use a connection string that resembles the following:

mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test

Connection String Options

This section lists all connection options used in the Standard Connection String Format.

Connection options are pairs in the following form: name=value. The value is always case sensitive. Separate options with the ampersand (i.e. &) character. In the following example, a connection uses the replicaSet and connectTimeoutMS options:

mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

Semi-colon separator for connection string arguments

To provide backwards compatibility, drivers currently accept semi-colons (i.e. ;) as option separators.

Replica Set Option

uri.replicaSet

Specifies the name of the replica set, if the mongod is a member of a replica set.

When connecting to a replica set it is important to give a seed list of at least two mongod instances. If you only provide the connection point of a single mongod instance, and omit the replicaSet, the client will create a standalone connection.

Connection Options

uri.ssl

true: Initiate the connection with SSL.

false: Initiate the connection without SSL.

The default value is false.

Note

The ssl option is not supported by all drivers. See your driver documentation and the Configure mongod and mongos for SSL document.

uri.connectTimeoutMS

The time in milliseconds to attempt a connection before timing out. The default is never to timeout, though different drivers might vary. See the driver documentation.

uri.socketTimeoutMS

The time in milliseconds to attempt a send or receive on a socket before the attempt times out. The default is never to timeout, though different drivers might vary. See the driver documentation.

Connection Pool Options

Most drivers implement some kind of connection pooling handle this for you behind the scenes. Some drivers do not support connection pools. See your driver documentation for more information on the connection pooling implementation. These options allow applications to configure the connection pool when connecting to the MongoDB deployment.

uri.maxPoolSize

The maximum number of connections in the connection pool. The default value is 100.

uri.minPoolSize

The minimum number of connections in the connection pool. The default value is 0.

Note

The minPoolSize option is not supported by all drivers. For information on your driver, see the drivers documentation.

uri.maxIdleTimeMS

The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed.

This option is not supported by all drivers.

uri.waitQueueMultiple

A number that the driver multiples the maxPoolSize value to, to provide the maximum number of threads allowed to wait for a connection to become available from the pool. For default values, see the MongoDB Drivers and Client Libraries documentation.

uri.waitQueueTimeoutMS

The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the MongoDB Drivers and Client Libraries documentation.

Write Concern Options

Write concern describes the kind of assurances that the mongod and the driver provide to the application regarding the success and durability of the write operation. For a full explanation of write concern and write operations in general, see Write Concern:

uri.w

Defines the level and kind of write concern. This option can take either a number or a string as a value.

Option
Description

0

The driver will not acknowledge write operations but will pass or handle any network and socket errors that it receives to the client.

You can specify the write concern both in the connection string and as a parameter to method calls like insert or update. If the write concern is specified in both places, the method parameter overrides the connection-string setting.

1
Provides basic acknowledgment of write operations. By specifying 1, you require that a standalone mongod instance, or the primary for replica sets, acknowledge all write operations. For drivers released after the default write concern change, this is the default write concern setting.

majority
For replica sets, if you specify the special majority value to w option, write operations will only return successfully after a majority of the configured replica set members have acknowledged the write operation.

n
For replica sets, if you specify a number n greater than 1, operations with this write concern return only after n members of the set have acknowledged the write. If you set n to a number that is greater than the number of available set members or members that hold data, MongoDB will wait, potentially indefinitely, for these members to become available.

tags
For replica sets, you can specify a tag set to require that all members of the set that have these tags configured return confirmation of the write operation. See Replica Set Tag Set Configuration for more information.

option number 0:

The driver will not acknowledge write operations but will pass or handle any network and socket errors that it receives to the client.

You can specify the write concern both in the connection string and as a parameter to method calls like insert or update. If the write concern is specified in both places, the method parameter overrides the connection-string setting.

option number 1:

Provides basic acknowledgment of write operations. By specifying 1, you require that a standalone mongod instance, or the primary for replica sets, acknowledge all write operations. For drivers released after the default write concern change, this is the default write concern setting.

option string majority:

For replica sets, if you specify the special majority value to w option, write operations will only return successfully after a majority of the configured replica set members have acknowledged the write operation.

option number n:

For replica sets, if you specify a number n greater than 1, operations with this write concern return only after n members of the set have acknowledged the write. If you set n to a number that is greater than the number of available set members or members that hold data, MongoDB will wait, potentially indefinitely, for these members to become available.

option string tags:

For replica sets, you can specify a tag set to require that all members of the set that have these tags configured return confirmation of the write operation. See Replica Set Tag Set Configuration for more information.

uri.wtimeoutMS

The time in milliseconds to wait for replication to succeed, as specified in the w option, before timing out. When wtimeoutMS is 0, write operations will never time out.

uri.journal

Controls whether write operations will wait until the mongod acknowledges the write operations and commits the data to the on disk journal.

Option | Description
true | Enables journal commit acknowledgment write concern. Equivalent to specifying a write concern with the j option enabled.
false | Does not require that mongod commit write operations to the journal before acknowledging the write operation. This is the default option for the journal parameter.

option Boolean true:
| Enables journal commit acknowledgment write concern. Equivalent to specifying a write concern with the j option enabled.
option Boolean false:
| Does not require that mongod commit write operations to the journal before acknowledging the write operation. This is the default option for the journal parameter.

If you set journal to true, and specify a w value less than 1, journal prevails.

Changed in version 2.6: If you set journal to true, and the mongod does not have journaling enabled, as with storage.journal.enabled, then MongoDB will error. In previous versions, MongoDB would provide basic receipt acknowledgment (i.e. w:1), ignore journal, and include a jnote field in its return document.

Read Preference Options

Read preferences describe the behavior of read operations with regards to replica sets. These parameters allow you to specify read preferences on a per-connection basis in the connection string:

uri.readPreference

Specifies the replica set read preference for this connection. The read preference values are the following:

primary

primaryPreferred

secondary

secondaryPreferred

nearest

For descriptions of each value, see Read Preference Modes.

The default value is primary, which sends all read operations to the replica set’s primary.

uri.readPreferenceTags

Specifies a tag set as a comma-separated list of colon-separated key-value pairs. For example:

dc:ny,rack:1

To specify a list of tag sets, use multiple readPreferenceTags. The following specifies two tag sets and an empty tag set:

readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=

Order matters when using multiple readPreferenceTags.

Authentication Options

uri.authSource

New in version 2.4.

Specify the database name associated with the user’s credentials, if the users collection do not exist in the database where the client is connecting. authSource defaults to the database specified in the connection string.

For authentication mechanisms that delegate credential storage to other services, the authSource value should be $external as with the PLAIN (LDAP) and GSSAPI (Kerberos) authentication mechanisms.

MongoDB will ignore authSource values if the connection string specifies no user name.

uri.authMechanism

New in version 2.4.

Changed in version 2.6: Support for the PLAIN and MONGODB-X509 authentication mechanisms.

Specify the authentication mechanism that MongoDB will use to authenticate the connection. Possible values include:

MONGODB-CR

MONGODB-X509

GSSAPI

PLAIN

Only MongoDB Enterprise mongod and mongos instances provide GSSAPI (Kerberos) and PLAIN (LDAP) mechanisms. To use MONGODB-X509, you must have SSL Enabled.

See Authentication for more information about the authentication system in MongoDB. Also consider Use x.509 Certificates to Authenticate Clients for more information on x509 authentication.

uri.gssapiServiceName

Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances.

gssapiServiceName defaults to mongodb for all clients and for MongoDB instance. If you change saslServiceName setting on a MongoDB instance, you will need to set gssapiServiceName to the same value.

Miscellaneous Configuration

uri.uuidRepresentation

Option | Description
standard | The standard binary representation.
csharpLegacy | The default representation for the C# driver.
javaLegacy | The default representation for the Java driver.
pythonLegacy | The default representation for the Python driver.

option standard:
| The standard binary representation.
option csharpLegacy:
| The default representation for the C# driver.
option javaLegacy:
| The default representation for the Java driver.
option pythonLegacy:
| The default representation for the Python driver.

For the default, see the drivers documentation for your driver.

Note

Not all drivers support the uuidRepresentation option. For information on your driver, see the drivers documentation.

Examples

The following provide example URI strings for common connection targets.

Database Server Running Locally

The following connects to a database server running locally on the default port:

mongodb://localhost

admin Database

The following connects and logs in to the admin database as user sysop with the password moon:

mongodb://sysop:moon@localhost

records Database

The following connects and logs in to the records database as user sysop with the password moon:

mongodb://sysop:moon@localhost/records

UNIX Domain Socket

The following connects to a UNIX domain socket:

mongodb:///tmp/mongodb-27017.sock

Note

Not all drivers support UNIX domain sockets. For information on your driver, see the drivers documentation.

Replica Set with Members on Different Machines

The following connects to a replica set with two members, one on db1.example.net and the other on db2.example.net:

mongodb://db1.example.net,db2.example.com

Replica Set with Members on localhost

The following connects to a replica set with three members running on localhost on ports 27017, 27018, and 27019:

mongodb://localhost,localhost:27018,localhost:27019

Replica Set with Read Distribution

The following connects to a replica set with three members and distributes reads to the secondaries:

mongodb://example1.com,example2.com,example3.com/?readPreference=secondary

Replica Set with a High Level of Write Concern

The following connects to a replica set with write concern configured to wait for replication to succeed on at least two members, with a two-second timeout.

mongodb://example1.com,example2.com,example3.com/?w=2&wtimeoutMS=2000

MongoDB Extended JSON

JSON can only represent a subset of the types supported by BSON. To preserve type information, MongoDB adds the following extensions to the JSON format:

Strict mode. Strict mode representations of BSON types conform to the JSON RFC [http://www.json.org]. Any JSON parser can parse these strict mode representations as key/value pairs; however, only the MongoDB’s internal JSON parser also recognizes the type information conveyed by the format.

mongo Shell mode. The MongoDB’s internal JSON parser and the mongo shell can parse this mode.

The representation used for the various data types depends on the context in which the JSON is parsed.

Parsers and Supported Format

Input in Strict Mode

The following can parse representations in strict mode with recognition of the type information.

REST Interfaces [http://docs.mongodb.org/ecosystem/tools/http-interfaces]

mongoimport

--query option of various MongoDB tools

Other JSON parsers, including mongo shell and db.eval(), can parse strict mode representations as key/value pairs, but without recognition of the type information.

Input in mongo Shell Mode

The following can parse representations in mongo shell mode with recognition of the type information.

REST Interfaces [http://docs.mongodb.org/ecosystem/tools/http-interfaces]

mongoimport

--query option of various MongoDB tools

mongo shell

Output in Strict mode

mongoexport and REST and HTTP Interfaces [http://docs.mongodb.org/ecosystem/tools/http-interfaces] output data in Strict mode.

Output in mongo Shell Mode

bsondump outputs in mongo Shell mode.

BSON Data Types and Associated Representations

The following presents the BSON data types and the associated representations in Strict mode and mongo Shell mode.

Binary

data_binary

Strict Mode

mongo Shell Mode

{ "$binary": "<bindata>", "$type": "<t>" }

BinData ( <t>, <bindata> )

<bindata> is the base64 representation of a binary string.

<t> is a representation of a single byte indicating the data type. In Strict mode it is a hexadecimal string, and in Shell mode it is an integer. See the extended bson documentation. http://bsonspec.org/spec.html

Date

data_date

Strict Mode

mongo Shell Mode

{ "$date": "<date>" }

new Date ( <date> )

In Strict mode, <date> is an ISO-8601 date format with a mandatory time zone field following the template YYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>.

The MongoDB JSON parser currently does not support loading ISO-8601 strings representing dates prior to the Unix epoch. When formatting pre-epoch dates and dates past what your system’s time_t type can hold, the following format is used:

{ "$date" : { "$numberLong" : "<dateAsMilliseconds>" } }

In Shell mode, <date> is the JSON representation of a 64-bit signed integer giving the number of milliseconds since epoch UTC.

Timestamp

data_timestamp

Strict Mode

mongo Shell Mode

{ "$timestamp": { "t": <t>, "i": <i> } }

Timestamp( <t>, <i> )

<t> is the JSON representation of a 32-bit unsigned integer for seconds since epoch.

<i> is a 32-bit unsigned integer for the increment.

Regular Expression

data_regex

Strict Mode

mongo Shell Mode

{ "$regex": "<sRegex>", "$options": "<sOptions>" }

/<jRegex>/<jOptions>

<sRegex> is a string of valid JSON characters.

<jRegex> is a string that may contain valid JSON characters and unescaped double quote (") characters, but may not contain unescaped forward slash (/) characters.

<sOptions> is a string containing the regex options represented by the letters of the alphabet.

<jOptions> is a string that may contain only the characters ‘g’, ‘i’, ‘m’ and ‘s’ (added in v1.9). Because the JavaScript and mongo Shell representations support a limited range of options, any nonconforming options will be dropped when converting to this representation.

OID

data_oid

Strict Mode

mongo Shell Mode

{ "$oid": "<id>" }

ObjectId( "<id>" )

<id> is a 24-character hexadecimal string.

DB Reference

data_ref

Strict Mode

mongo Shell Mode

{ "$ref": "<name>", "$id": "<id>" }

DBRef("<name>", "<id>")

<name> is a string of valid JSON characters.

<id> is any valid extended JSON type.

Undefined Type

data_undefined

Strict Mode

mongo Shell Mode

{ "$undefined": true }

undefined

The representation for the JavaScript/BSON undefined type.

MinKey

data_minkey

Strict Mode

mongo Shell Mode

{ "$minKey": 1 }

MinKey

The representation of the MinKey BSON data type that compares lower than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.

MaxKey

data_maxkey

Strict Mode

mongo Shell Mode

{ "$maxKey": 1 }

MaxKey

The representation of the MaxKey BSON data type that compares higher than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.

NumberLong

New in version 2.6.

data_numberlong

Strict Mode

mongo Shell Mode

{ "$numberLong": "<number>" }

NumberLong( <number> )

Number long is a 64 bit signed integer.

Glossary

$cmd

A special virtual collection that exposes MongoDB’s database commands. To use database commands, see Issue Commands.

_id

A field required in every MongoDB document. The _id field must have a unique value. You can think of the _id field as the document’s primary key. If you create a new document without an _id field, MongoDB automatically creates the field and assigns a unique BSON ObjectId.

accumulator

An expression in the aggregation framework that maintains state between documents in the aggregation pipeline. For a list of accumulator operations, see $group.

action

An operation the user can perform on a resource. Actions and resources combine to create privileges. See action.

admin database

A privileged database. Users must have access to the admin database to run certain administrative commands. For a list of administrative commands, see Instance Administration Commands.

aggregation

Any of a variety of operations that reduces and summarizes large sets of data. MongoDB’s aggregate() and mapReduce() methods are two examples of aggregation operations. For more information, see Aggregation Concepts.

aggregation framework

The set of MongoDB operators that let you calculate aggregate values without having to use map-reduce. For a list of operators, see Aggregation Reference.

arbiter

A member of a replica set that exists solely to vote in elections. Arbiters do not replicate data. See Replica Set Arbiter.

authentication

Verification of the user identity. See Authentication.

authorization

Provisioning of access to databases and operations. See Authorization.

B-tree

A data structure commonly used by database management systems to store indexes. MongoDB uses B-trees for its indexes.

balancer

An internal MongoDB process that runs in the context of a sharded cluster and manages the migration of chunks. Administrators must disable the balancer for all maintenance operations on a sharded cluster. See Sharded Collection Balancing.

BSON

A serialization format used to store documents and make remote procedure calls in MongoDB. “BSON” is a portmanteau of the words “binary” and “JSON”. Think of BSON as a binary representation of JSON (JavaScript Object Notation) documents. See BSON Types and MongoDB Extended JSON.

BSON types

The set of types supported by the BSON serialization format. For a list of BSON types, see BSON Types.

CAP Theorem

Given three properties of computing systems, consistency, availability, and partition tolerance, a distributed computing system can provide any two of these features, but never all three.

capped collection

A fixed-sized collection that automatically overwrites its oldest entries when it reaches its maximum size. The MongoDB oplog that is used in replication is a capped collection. See Capped Collections.

checksum

A calculated value used to ensure data integrity. The md5 algorithm is sometimes used as a checksum.

chunk

A contiguous range of shard key values within a particular shard. Chunk ranges are inclusive of the lower boundary and exclusive of the upper boundary. MongoDB splits chunks when they grow beyond the configured chunk size, which by default is 64 megabytes. MongoDB migrates chunks when a shard contains too many chunks of a collection relative to other shards. See Data Partitioning and Sharding Mechanics.

client

The application layer that uses a database for data persistence and storage. Drivers provide the interface level between the application layer and the database server.

cluster

See sharded cluster.

collection

A grouping of MongoDB documents. A collection is the equivalent of an RDBMS table. A collection exists within a single database. Collections do not enforce a schema. Documents within a collection can have different fields. Typically, all documents in a collection have a similar or related purpose. See What is a namespace in MongoDB?.

collection scan

Collection scans are a query execution strategy where MongoDB must inspect every document in a collection to see if it matches the query criteria. These queries are very inefficient and do not use indexes. See Query Optimization for details about query execution strategies.

compound index

An index consisting of two or more keys. See Compound Indexes.

config database

An internal database that holds the metadata associated with a sharded cluster. Applications and administrators should not modify the config database in the course of normal operation. See Config Database.

config server

A mongod instance that stores all the metadata associated with a sharded cluster. A production sharded cluster requires three config servers, each on a separate machine. See Config Servers.

control script

A simple shell script, typically located in the /etc/rc.d or /etc/init.d directory, and used by the system’s initialization process to start, restart or stop a daemon process.

CRUD

An acronym for the fundamental operations of a database: Create, Read, Update, and Delete. See MongoDB CRUD Operations.

CSV

A text-based data format consisting of comma-separated values. This format is commonly used to exchange data between relational databases since the format is well-suited to tabular data. You can import CSV files using mongoimport.

cursor

A pointer to the result set of a query. Clients can iterate through a cursor to retrieve results. By default, cursors timeout after 10 minutes of inactivity. See Cursors.

daemon

The conventional name for a background, non-interactive process.

data directory

The file-system location where the mongod stores data files. The dbPath option specifies the data directory.

data-center awareness

A property that allows clients to address members in a system based on their locations. Replica sets implement data-center awareness using tagging. See Data Center Awareness.

database

A physical container for collections. Each database gets its own set of files on the file system. A single MongoDB server typically has multiple databases.

database command

A MongoDB operation, other than an insert, update, remove, or query. For a list of database commands, see Database Commands. To use database commands, see Issue Commands.

database profiler

A tool that, when enabled, keeps a record on all long-running operations in a database’s system.profile collection. The profiler is most often used to diagnose slow queries. See Database Profiling.

datum

A set of values used to define measurements on the earth. MongoDB uses the WGS84 datum in certain geospatial calculations. See Geospatial Indexes and Queries.

dbpath

The location of MongoDB’s data file storage. See dbPath.

delayed member

A replica set member that cannot become primary and applies operations at a specified delay. The delay is useful for protecting data from human error (i.e. unintentionally deleted databases) or updates that have unforeseen effects on the production database. See Delayed Replica Set Members.

diagnostic log

A verbose log of operations stored in the dbpath. See the --diaglog option.

document

A record in a MongoDB collection and the basic unit of data in MongoDB. Documents are analogous to JSON objects but exist in the database in a more type-rich format known as BSON. See Documents.

dot notation

MongoDB uses the dot notation to access the elements of an array and to access the fields of an embedded document. See Dot Notation.

draining

The process of removing or “shedding” chunks from one shard to another. Administrators must drain shards before removing them from the cluster. See Remove Shards from an Existing Sharded Cluster.

driver

A client library for interacting with MongoDB in a particular language. See MongoDB Drivers and Client Libraries.

election

The process by which members of a replica set select a primary on startup and in the event of a failure. See Replica Set Elections.

eventual consistency

A property of a distributed system that allows changes to the system to propagate gradually. In a database system, this means that readable members are not required to reflect the latest writes at all times. In MongoDB, reads to a primary have strict consistency; reads to secondaries have eventual consistency.

expression

In the context of aggregation framework, expressions are the stateless transformations that operate on the data that passes through a pipeline. See Aggregation Concepts.

failover

The process that allows a secondary member of a replica set to become primary in the event of a failure. See Replica Set High Availability.

field

A name-value pair in a document. A document has zero or more fields. Fields are analogous to columns in relational databases. See Document Structure.

field path

Path to a field in the document. To specify a field path, use a string that prefixes the field name with a dollar sign ($).

firewall

A system level networking filter that restricts access based on, among other things, IP address. Firewalls form a part of an effective network security strategy. See Firewalls.

fsync

A system call that flushes all dirty, in-memory pages to disk. MongoDB calls fsync() on its database files at least every 60 seconds. See fsync.

geohash

A geohash value is a binary representation of the location on a coordinate grid. See Calculation of Geohash Values for 2d Indexes.

GeoJSON

A geospatial data interchange format based on JavaScript Object Notation (JSON). GeoJSON is used in geospatial queries. For supported GeoJSON objects, see Location Data. For the GeoJSON format specification, see http://geojson.org/geojson-spec.html.

geospatial

Data that relates to geographical location. In MongoDB, you may store, index, and query data according to geographical parameters. See Geospatial Indexes and Queries.

GridFS

A convention for storing large files in a MongoDB database. All of the official MongoDB drivers support this convention, as does the mongofiles program. See GridFS and GridFS Reference.

hashed shard key

A special type of shard key that uses a hash of the value in the shard key field to distribute documents among members of the sharded cluster. See Hashed Index.

haystack index

A geospatial index that enhances searches by creating “buckets” of objects grouped by a second criterion. See geoHaystack Indexes.

hidden member

A replica set member that cannot become primary and are invisible to client applications. See Hidden Replica Set Members.

idempotent

The quality of an operation to produce the same result given the same input, whether run once or run multiple times.

index

A data structure that optimizes queries. See Index Concepts.

initial sync

The replica set operation that replicates data from an existing replica set member to a new or restored replica set member. See Initial Sync.

interrupt point

A point in an operation’s lifecycle when it can safely abort. MongoDB only terminates an operation at designated interrupt points. See Terminate Running Operations.

IPv6

A revision to the IP (Internet Protocol) standard that provides a significantly larger address space to more effectively support the number of hosts on the contemporary Internet.

ISODate

The international date format used by mongo to display dates. The format is: YYYY-MM-DD HH:MM.SS.millis.

JavaScript

A popular scripting language originally designed for web browsers. The MongoDB shell and certain server-side functions use a JavaScript interpreter. See Server-side JavaScript for more information.

journal

A sequential, binary transaction log used to bring the database into a valid state in the event of a hard shutdown. Journaling writes data first to the journal and then to the core data files. MongoDB enables journaling by default for 64-bit builds of MongoDB version 2.0 and newer. Journal files are pre-allocated and exist as files in the data directory. See Journaling Mechanics.

JSON

JavaScript Object Notation. A human-readable, plain text format for expressing structured data with support in many programming languages. For more information, see http://www.json.org. Certain MongoDB tools render an approximation of MongoDB BSON documents in JSON format. See MongoDB Extended JSON.

JSON document

A JSON document is a collection of fields and values in a structured format. For sample JSON documents, see http://json.org/example.html.

JSONP

JSON with Padding. Refers to a method of injecting JSON into applications. Presents potential security concerns.

least privilege

An authorization policy that gives a user only the amount of access that is essential to that user’s work and no more.

legacy coordinate pairs

The format used for geospatial data prior to MongoDB version 2.4. This format stores geospatial data as points on a planar coordinate system (e.g. [ x, y ]). See Geospatial Indexes and Queries.

LineString

A LineString is defined by an array of two or more positions. A closed LineString with four or more positions is called a LinearRing, as described in the GeoJSON LineString specification: http://geojson.org/geojson-spec.html#linestring. To use a LineString in MongoDB, see GeoJSON Objects.

lock

MongoDB uses locks to ensure concurrency. MongoDB uses both read locks and write locks. For more information, see What type of locking does MongoDB use?.

LVM

Logical volume manager. LVM is a program that abstracts disk images from physical devices and provides a number of raw disk manipulation and snapshot capabilities useful for system management. For information on LVM and MongoDB, see Backup and Restore Using LVM on a Linux System.

map-reduce

A data processing and aggregation paradigm consisting of a “map” phase that selects data and a “reduce” phase that transforms the data. In MongoDB, you can run arbitrary aggregations over data using map-reduce. For map-reduce implementation, see Map-Reduce. For all approaches to aggregation, see Aggregation Concepts.

mapping type

A Structure in programming languages that associate keys with values, where keys may nest other pairs of keys and values (e.g. dictionaries, hashes, maps, and associative arrays). The properties of these structures depend on the language specification and implementation. Generally the order of keys in mapping types is arbitrary and not guaranteed.

master

The database that receives all writes in a conventional master-slave replication. In MongoDB, replica sets replace master-slave replication for most use cases. For more information on master-slave replication, see Master Slave Replication.

md5

A hashing algorithm used to efficiently provide reproducible unique strings to identify and checksum data. MongoDB uses md5 to identify chunks of data for GridFS. See filemd5.

MIB

Management Information Base. MongoDB uses MIB files to define the type of data tracked by SNMP in the MongoDB Enterprise edition.

MIME

Multipurpose Internet Mail Extensions. A standard set of type and encoding definitions used to declare the encoding and type of data in multiple data storage, transmission, and email contexts. The mongofiles tool provides an option to specify a MIME type to describe a file inserted into GridFS storage.

mongo

The MongoDB shell. The mongo process starts the MongoDB shell as a daemon connected to either a mongod or mongos instance. The shell has a JavaScript interface. See mongo and mongo Shell Methods.

mongod

The MongoDB database server. The mongod process starts the MongoDB server as a daemon. The MongoDB server manages data requests and formats and manages background operations. See mongod.

MongoDB

An open-source document-based database system. “MongoDB” derives from the word “humongous” because of the database’s ability to scale up with ease and hold very large amounts of data. MongoDB stores documents in collections within databases.

MongoDB Enterprise

A commercial edition of MongoDB that includes additional features. For more information, see MongoDB Subscriptions [https://www.mongodb.com/products/mongodb-subscriptions].

mongos

The routing and load balancing process that acts an interface between an application and a MongoDB sharded cluster. See mongos.

namespace

The canonical name for a collection or index in MongoDB. The namespace is a combination of the database name and the name of the collection or index, like so: [database-name].[collection-or-index-name]. All documents belong to a namespace. See What is a namespace in MongoDB?.

natural order

The order in which the database refers to documents on disk. This is the default sort order. See $natural and Return in Natural Order.

ObjectId

A special 12-byte BSON type that guarantees uniqueness within the collection. The ObjectId is generated based on timestamp, machine ID, process ID, and a process-local incremental counter. MongoDB uses ObjectId values as the default values for _id fields.

operator

A keyword beginning with a $ used to express an update, complex query, or data transformation. For example, $gt is the query language’s “greater than” operator. For available operators, see Operators.

oplog

A capped collection that stores an ordered history of logical writes to a MongoDB database. The oplog is the basic mechanism enabling replication in MongoDB. See Replica Set Oplog.

ordered query plan

A query plan that returns results in the order consistent with the sort() order. See Query Plans.

orphaned document

In a sharded cluster, orphaned documents are those documents on a shard that also exist in chunks on other shards as a result of failed migrations or incomplete migration cleanup due to abnormal shutdown. Delete orphaned documents using cleanupOrphaned to reclaim disk space and reduce confusion.

padding

The extra space allocated to document on the disk to prevent moving a document when it grows as the result of update() operations. See Record Allocation Strategies.

padding factor

An automatically-calibrated constant used to determine how much extra space MongoDB should allocate per document container on disk. A padding factor of 1 means that MongoDB will allocate only the amount of space needed for the document. A padding factor of 2 means that MongoDB will allocate twice the amount of space required by the document. See Record Allocation Strategies.

page fault

Page faults can occur as MongoDB reads from or writes data to parts of its data files that are not currently located in physical memory. In contrast, operating system page faults happen when physical memory is exhausted and pages of physical memory are swapped to disk.

See Page Faults and What are page faults?.

partition

A distributed system architecture that splits data into ranges. Sharding uses partitioning. See Data Partitioning.

passive member

A member of a replica set that cannot become primary because its priority is 0. See Priority 0 Replica Set Members.

pcap

A packet-capture format used by mongosniff to record packets captured from network interfaces and display them as human-readable MongoDB operations. See Options.

PID

A process identifier. UNIX-like systems assign a unique-integer PID to each running process. You can use a PID to inspect a running process and send signals to it. See /proc File System.

pipe

A communication channel in UNIX-like systems allowing independent processes to send and receive data. In the UNIX shell, piped operations allow users to direct the output of one command into the input of another.

pipeline

A series of operations in an aggregation process. See Aggregation Concepts.

Point

A single coordinate pair as described in the GeoJSON Point specification: http://geojson.org/geojson-spec.html#point. To use a Point in MongoDB, see GeoJSON Objects.

Polygon

An array of LinearRing coordinate arrays, as described in the GeoJSON Polygon specification: http://geojson.org/geojson-spec.html#polygon. For Polygons with multiple rings, the first must be the exterior ring and any others must be interior rings or holes.

MongoDB does not permit the exterior ring to self-intersect. Interior rings must be fully contained within the outer loop and cannot intersect or overlap with each other. See GeoJSON Objects.

powerOf2Sizes

A per-collection setting that changes and normalizes the way MongoDB allocates space for each document, in an effort to maximize storage reuse and to reduce fragmentation. This is the default for TTL Collections. See collMod and usePowerOf2Sizes.

pre-splitting

An operation performed before inserting data that divides the range of possible shard key values into chunks to facilitate easy insertion and high write throughput. In some cases pre-splitting expedites the initial distribution of documents in sharded cluster by manually dividing the collection rather than waiting for the MongoDB balancer to do so. See Create Chunks in a Sharded Cluster.

primary

In a replica set, the primary member is the current master instance, which receives all write operations. See Primary.

primary key

A record’s unique immutable identifier. In an RDBMS, the primary key is typically an integer stored in each row’s id field. In MongoDB, the _id field holds a document’s primary key which is usually a BSON ObjectId.

primary shard

The shard that holds all the un-sharded collections. See Primary Shard.

priority

A configurable value that helps determine which members in a replica set are most likely to become primary. See priority.

privilege

A combination of specified resource and actions permitted on the resource. See privilege.

projection

A document given to a query that specifies which fields MongoDB returns in the result set. See Limit Fields to Return from a Query. For a list of projection operators, see Projection Operators.

query

A read request. MongoDB uses a JSON-like query language that includes a variety of query operators with names that begin with a $ character. In the mongo shell, you can issue queries using the find() and findOne() methods. See Read Operations Overview.

query optimizer

A process that generates query plans. For each query, the optimizer generates a plan that matches the query to the index that will return results as efficiently as possible. The optimizer reuses the query plan each time the query runs. If a collection changes significantly, the optimizer creates a new query plan. See Query Plans.

query shape

A combination of query predicate, sort, and projection specifications.

For the query predicate, only the structure of the predicate, including the field names, are significant; the values in the query predicate are insignificant. As such, a query predicate { type: 'food' } is equivalent to the query predicate { type: 'utensil' } for a query shape.

RDBMS

Relational Database Management System. A database management system based on the relational model, typically using SQL as the query language.

read lock

In the context of a reader-writer lock, a lock that while held allows concurrent readers but no writers. See What type of locking does MongoDB use?.

read preference

A setting that determines how clients direct read operations. Read preference affects all replica sets, including shards. By default, MongoDB directs reads to primaries for strict consistency. However, you may also direct reads to secondaries for eventually consistent reads. See Read Preference.

record size

The space allocated for a document including the padding. For more information on padding, see Record Allocation Strategies and compact.

recovering

A replica set member status indicating that a member is not ready to begin normal activities of a secondary or primary. Recovering members are unavailable for reads.

replica pairs

The precursor to the MongoDB replica sets.

Deprecated since version 1.6.

replica set

A cluster of MongoDB servers that implements master-slave replication and automated failover. MongoDB’s recommended replication strategy. See Replication.

replication

A feature allowing multiple database servers to share the same data, thereby ensuring redundancy and facilitating load balancing. See Replication.

replication lag

The length of time between the last operation in the primary’s oplog and the last operation applied to a particular secondary. In general, you want to keep replication lag as small as possible. See Replication Lag.

resident memory

The subset of an application’s memory currently stored in physical RAM. Resident memory is a subset of virtual memory, which includes memory mapped to physical RAM and to disk.

resource

A database, collection, set of collections, or cluster. A privilege permits actions on a specified resource. See resource.

REST

An API design pattern centered around the idea of resources and the CRUD operations that apply to them. Typically REST is implemented over HTTP. MongoDB provides a simple HTTP REST interface that allows HTTP clients to run commands against the server. See rest-interface and REST API.

role

A set of privileges that permit actions on specified resources. Roles assigned to a user determine the user’s access to resources and operations. See Security Introduction.

rollback

A process that reverts writes operations to ensure the consistency of all replica set members. See Rollbacks During Replica Set Failover.

secondary

A replica set member that replicates the contents of the master database. Secondary members may handle read requests, but only the primary members can handle write operations. See Secondaries.

secondary index

A database index that improves query performance by minimizing the amount of work that the query engine must perform to fulfill a query. See Indexes.

set name

The arbitrary name given to a replica set. All members of a replica set must have the same name specified with the replSetName setting or the --replSet option.

shard

A single mongod instance or replica set that stores some portion of a sharded cluster’s total data set. In production, all shards should be replica sets. See Shards.

shard key

The field MongoDB uses to distribute documents among members of a sharded cluster. See Shard Keys.

sharded cluster

The set of nodes comprising a sharded MongoDB deployment. A sharded cluster consists of three config processes, one or more replica sets, and one or more mongos routing processes. See Sharded Cluster Components.

sharding

A database architecture that partitions data by key ranges and distributes the data among two or more database instances. Sharding enables horizontal scaling. See Sharding.

shell helper

A method in the mongo shell that provides a more concise syntax for a database command. Shell helpers improve the general interactive experience. See mongo Shell Methods.

single-master replication

A replication topology where only a single database instance accepts writes. Single-master replication ensures consistency and is the replication topology employed by MongoDB. See Replica Set Primary.

slave

A read-only database that replicates operations from a master database in conventional master/slave replication. In MongoDB, replica sets replace master/slave replication for most use cases. However, for information on master/slave replication, see Master Slave Replication.

split

The division between chunks in a sharded cluster. See Chunk Splits in a Sharded Cluster.

SQL

Structured Query Language (SQL) is a common special-purpose programming language used for interaction with a relational database, including access control, insertions, updates, queries, and deletions. There are some similar elements in the basic SQL syntax supported by different database vendors, but most implementations have their own dialects, data types, and interpretations of proposed SQL standards. Complex SQL is generally not directly portable between major RDBMS products. SQL is often used as metonym for relational databases.

SSD

Solid State Disk. A high-performance disk drive that uses solid state electronics for persistence, as opposed to the rotating platters and movable read/write heads used by traditional mechanical hard drives.

stale

Refers to the amount of time a secondary member of a replica set trails behind the current state of the primary’soplog. If a secondary becomes too stale, it can no longer use replication to catch up to the current state of the primary. See Replica Set Oplog and Replica Set Data Synchronization for more information.

standalone

An instance of mongod that is running as a single server and not as part of a replica set. To convert a standalone into a replica set, see Convert a Standalone to a Replica Set.

storage order

See natural order.

strict consistency

A property of a distributed system requiring that all members always reflect the latest changes to the system. In a database system, this means that any system that can provide data must reflect the latest writes at all times. In MongoDB, reads from a primary have strict consistency; reads from secondary members have eventual consistency.

sync

The replica set operation where members replicate data from the primary. Sync first occurs when MongoDB creates or restores a member, which is called initial sync. Sync then occurs continually to keep the member updated with changes to the replica set’s data. See Replica Set Data Synchronization.

syslog

On UNIX-like systems, a logging process that provides a uniform standard for servers and processes to submit logging information. MongoDB provides an option to send output to the host’s syslog system. See syslogFacility.

tag

A label applied to a replica set member or shard and used by clients to issue data-center-aware operations. For more information on using tags with replica sets and with shards, see the following sections of this manual: Tag Sets and Behavior and Operations.

tailable cursor

For a capped collection, a tailable cursor is a cursor that remains open after the client exhausts the results in the initial cursor. As clients insert new documents into the capped collection, the tailable cursor continues to retrieve documents. See Create Tailable Cursor.

topology

The state of a deployment of MongoDB instances, including the type of deployment (i.e. standalone, replica set, or sharded cluster) as well as the availability of servers, and the role of each server (i.e. primary, secondary, config server, or mongos.)

TSV

A text-based data format consisting of tab-separated values. This format is commonly used to exchange data between relational databases, since the format is well-suited to tabular data. You can import TSV files using mongoimport.

TTL

Stands for “time to live” and represents an expiration time or period for a given piece of information to remain in a cache or other temporary storage before the system deletes it or ages it out. MongoDB has a TTL collection feature. See Expire Data from Collections by Setting TTL.

unique index

An index that enforces uniqueness for a particular field across a single collection. See Unique Indexes.

unix epoch

January 1st, 1970 at 00:00:00 UTC. Commonly used in expressing time, where the number of seconds or milliseconds since this point is counted.

unordered query plan

A query plan that returns results in an order inconsistent with the sort() order. See Query Plans.

upsert

An option for update operations. If set to true, the update operation will either update the first document matched by a query or insert a new document if none matches. The new document will have the fields implied by the operation. The update() and findAndModify() have the option. See Upsert Option.

virtual memory

An application’s working memory, typically residing on both disk an in physical RAM.

WGS84

The default datum MongoDB uses to calculate geometry over an Earth-like sphere. MongoDB uses the WGS84 datum for geospatial queries on GeoJSON objects. See the “EPSG:4326: WGS 84” specification: http://spatialreference.org/ref/epsg/4326/.

working set

The data that MongoDB uses most often. This data is preferably held in RAM, solid-state drive (SSD), or other fast media. See What is the working set?.

write concern

Specifies whether a write operation has succeeded. Write concern allows your application to detect insertion errors or unavailable mongod instances. For replica sets, you can configure write concern to confirm replication to a specified number of members. See Write Concern.

write lock

A lock on the database for a given writer. When a process writes to the database, it takes an exclusive write lock to prevent other processes from writing or reading. For more information on locks, see FAQ: Concurrency.

writeBacks

The process within the sharding system that ensures that writes issued to a shard that is not responsible for the relevant chunk get applied to the proper shard. For related information, see What does writebacklisten in the log mean? and writeBacksQueued.

Release Notes

Always install the latest, stable version of MongoDB. See MongoDB Version Numbers for more information.

See the following release notes for an account of the changes in major versions. Release notes also include instructions for upgrade.

Current Stable Release

(2.6-series)

Release Notes for MongoDB 2.6

Previous Stable Releases

Release Notes for MongoDB 2.4

Release Notes for MongoDB 2.2

Release Notes for MongoDB 2.0

Release Notes for MongoDB 1.8

Release Notes for MongoDB 1.6

Release Notes for MongoDB 1.4

Release Notes for MongoDB 1.2.x

Other MongoDB Release Notes

Default Write Concern Change

Changes

Releases

MongoDB Version Numbers

For MongoDB 2.4.1, 2.4 refers to the release series and .1 refers to the revision. The second component of the release series (e.g. 4 in 2.4.1) describes the type of release series. Release series ending with even numbers (e.g. 4 above) are stable and ready for production, while odd numbers are for development and testing only.

Generally, changes in the release series (e.g. 2.2 to 2.4) mark the introduction of new features that may break backwards compatibility. Changes to the revision number mark the release bug fixes and backwards-compatible changes.

Important

Always upgrade to the latest stable revision of your release series.

The version numbering system for MongoDB differs from the system used for the MongoDB drivers. Drivers use only the first number to indicate a major version. For details, see Driver Version Numbers.

Example

Version numbers

2.0.0 : Stable release.

2.0.1 : Revision.

2.1.0 : Development release for testing only. Includes new features and changes for testing. Interfaces and stability may not be compatible in development releases.

2.2.0 : Stable release. This is a culmination of the 2.1.x development series.

Release Notes for MongoDB 2.6

April 8, 2014

MongoDB 2.6 is now available. Key features include aggregation enhancements, text-search integration, query-engine improvements, a new write-operation protocol, and security enhancements.

MMS 1.4, which includes On-Prem Backup in addition to Monitoring, is now also available. See MMS 1.4 documentation [https://mms.mongodb.com/help-hosted/v1.4/] and the MMS 1.4 release notes [https://mms.mongodb.com/help-hosted/v1.4/management/changelog/] for more information.

Minor Releases

2.6 Changelog

2.6.8 – Changes

Security and Networking

Query and Aggregation

Replication

Sharding

Storage

Tools

Build and Packaging

Usability

Testing

2.6.7 – Changes

Stability

Querying

Replication

Sharding

Packaging

2.6.6 – Changes

Security

Stability

Querying

Replication

Sharding

Storage

Indexing and write Operations

Data Aggregation

Build and Packaging

Logging and Diagnostics

Testing and Internals

2.6.5 – Changes

Security

Stability

Querying

Replication

Sharding

Storage

Indexing

Write Operations

Data Aggregation

Packaging

Logging and Diagnostics

Internal Code and Testing

2.6.4 – Changes

Security

Querying

Replication

Sharding

Storage

Indexing

Write Ops

Networking

Geo

Text Search

Tools

Admin

Packaging

JavaScript

Shell

Usability

Logging and Diagnostics

Testing

2.6.3 – Changes

2.6.2 – Changes

Security

Querying

Geospatial

Write Operations

Replication

Sharding

Map/Reduce

Storage

Build and Packaging

Diagnostics

Administration

Tools

Shell

Internal Code

Testing

2.6.1 – Changes

Stability

Build and Packaging

Querying

Geospatial

Replication

Sharding

Security

Write Operations

2.6.8 – February 25, 2015

Add listCollections command functionality to 2.6 shell and client SERVER-17087 [https://jira.mongodb.org/browse/SERVER-17087]

copydb/clone commands can crash the server if a primary steps down SERVER-16599 [https://jira.mongodb.org/browse/SERVER-16599]

Secondary fasserts trying to replicate an index SERVER-16274 [https://jira.mongodb.org/browse/SERVER-16274]

Query optimizer should always use equality predicate over unique index when possible SERVER-15802 [https://jira.mongodb.org/browse/SERVER-15802]

All issues closed in 2.6.8 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.8%22%20AND%20project%20%3D%20SERVER]

2.6.7 – January 13, 2015

Decreased mongos memory footprint when shards have several tags SERVER-16683 [https://jira.mongodb.org/browse/SERVER-16683]

Removed check for shard version if the primary server is down SERVER-16237 [https://jira.mongodb.org/browse/SERVER-16237]

Fixed: /etc/init.d/mongod startup script failure with dirname message SERVER-16081 [https://jira.mongodb.org/browse/SERVER-16081]

Fixed: mongos can cause shards to hit the in-memory sort limit by requesting more results than needed SERVER-14306 [https://jira.mongodb.org/browse/SERVER-14306]

All issues closed in 2.6.7 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.7%22%20AND%20project%20%3D%20SERVER]

2.6.6 – December 09, 2014

Fixed: Evaluating candidate query plans with concurrent writes on same collection may crash mongod SERVER-15580 [https://jira.mongodb.org/browse/SERVER-15580]

Fixed: 2.6 mongod crashes with segfault when added to a 2.8 replica set with 12 or more members SERVER-16107 [https://jira.mongodb.org/browse/SERVER-16107]

Fixed: $regex, $in and $sort with index returns too many results SERVER-15696 [https://jira.mongodb.org/browse/SERVER-15696]

Change: moveChunk will fail if there is data on the target shard and a required index does not exist. SERVER-12472 [https://jira.mongodb.org/browse/SERVER-12472]

Primary should abort if encountered problems writing to the oplog SERVER-12058 [https://jira.mongodb.org/browse/SERVER-12058]

All issues closed in 2.6.6 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.6%22%20AND%20project%20%3D%20SERVER]

2.6.5 – October 07, 2014

$rename now uses correct dotted source paths SERVER-15029 [https://jira.mongodb.org/browse/SERVER-15029]

Partially written journal last section does not affect recovery SERVER-15111 [https://jira.mongodb.org/browse/SERVER-15111]

Explicitly zero .ns files on creation SERVER-15369 [https://jira.mongodb.org/browse/SERVER-15369]

Plan ranker will no longer favor intersection plans if predicate generates empty range index scan SERVER-14961 [https://jira.mongodb.org/browse/SERVER-14961]

Generate Community and Enterprise packages for SUSE 11 SERVER-10642 [https://jira.mongodb.org/browse/SERVER-10642]

All issues closed in 2.6.5 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.5%22%20AND%20project%20%3D%20SERVER]

2.6.4 – August 11, 2014

Fix for text index where under specific circumstances, in-place updates to a text-indexed field may result in incorrect/incomplete results SERVER-14738 [https://jira.mongodb.org/browse/SERVER-14738]

Check the size of the split point before performing a manual split chunk operation SERVER-14431 [https://jira.mongodb.org/browse/SERVER-14431]

Ensure read preferences are re-evaluated by drawing secondary connections from a global pool and releasing back to the pool at the end of a query/command SERVER-9788 [https://jira.mongodb.org/browse/SERVER-9788]

Allow read from secondaries when both audit and authorization are enabled in a sharded cluster SERVER-14170 [https://jira.mongodb.org/browse/SERVER-14170]

All issues closed in 2.6.4 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.4%22%20AND%20project%20%3D%20SERVER]

2.6.3 – June 19, 2014

Equality queries on _id with projection may return no results on sharded collections SERVER-14302 [https://jira.mongodb.org/browse/SERVER-14302].

Equality queries on _id with projection on _id may return orphan documents on sharded collections SERVER-14304 [https://jira.mongodb.org/browse/SERVER-14304].

All issues closed in 2.6.3 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.3%22%20AND%20project%20%3D%20SERVER].

2.6.2 – June 16, 2014

Query plans with differing performance can tie during plan ranking SERVER-13675 [https://jira.mongodb.org/browse/SERVER-13675].

mongod may terminate if x.509 authentication certificate is invalid SERVER-13753 [https://jira.mongodb.org/browse/SERVER-13753].

Temporary map/reduce collections are incorrectly replicated to secondaries SERVER-13981 [https://jira.mongodb.org/browse/SERVER-13981].

mongos incorrectly targets multiple shards for nested field shard key predicates SERVER-14138 [https://jira.mongodb.org/browse/SERVER-14138].

rs.stepDown() during mapReduce causes fassert when writing to op log SERVER-14186 [https://jira.mongodb.org/browse/SERVER-14186].

All issues closed in 2.6.2 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.2%22%20AND%20project%20%3D%20SERVER].

2.6.1 – May 5, 2014

Fix to install MongoDB service on Windows with the --install option SERVER-13515 [https://jira.mongodb.org/browse/SERVER-13515].

Allow direct upgrade from 2.4.x to 2.6.0 via yum SERVER-13563 [https://jira.mongodb.org/browse/SERVER-13563].

Fix issues with background index builds on secondaries: SERVER-13589 [https://jira.mongodb.org/browse/SERVER-13589] and SERVER-13620 [https://jira.mongodb.org/browse/SERVER-13620].

Redact credential information passed as startup options SERVER-13644 [https://jira.mongodb.org/browse/SERVER-13644].

2.6.1 Changelog.

All issues closed in 2.6.1 [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.6.1%22%20AND%20project%20%3D%20SERVER].

Major Changes

The following changes in MongoDB affect both the standard and Enterprise editions:

Aggregation Enhancements

The aggregation pipeline adds the ability to return result sets of any size, either by returning a cursor or writing the output to a collection. Additionally, the aggregation pipeline supports variables and adds new operations to handle sets and redact data.

The db.collection.aggregate() now returns a cursor, which enables the aggregation pipeline to return result sets of any size.

Aggregation pipelines now support an explain operation to aid analysis of aggregation operations.

Aggregation can now use a more efficient external-disk-based sorting process.

New pipeline stages:

$out stage to output to a collection.

$redact stage to allow additional control to accessing the data.

New or modified operators:

set expression operators.

$let and $map operators to allow for the use of variables.

$literal operator and $size operator.

$cond expression now accepts either an object or an array.

Text Search Integration

Text search is now enabled by default, and the query system, including the aggregation pipeline $match stage, includes the $text operator, which resolves text-search queries.

MongoDB 2.6 includes an updated text index format and deprecates the text command.

Insert and Update Improvements

Improvements to the update and insert systems include additional operations and improvements that increase consistency of modified data.

MongoDB preserves the order of the document fields following write operations except for the following cases:

The _id field is always the first field in the document.

Updates that include renaming of field names may result in the reordering of fields in the document.

New or enhanced update operators:

$bit operator supports bitwise xor operation.

$min and $max operators that perform conditional update depending on the relative size of the specified value and the current value of a field.

$push operator has enhanced support for the $sort, $slice, and $each modifiers and supports a new $position modifier.

$currentDate operator to set the value of a field to the current date.

The $mul operator for multiplicative increments for insert and update operations.

See also

Update Operator Syntax Validation

New Write Operation Protocol

A new write protocol integrates write operations with write concerns. The protocol also provides improved support for bulk operations.

MongoDB 2.6 adds the write commands insert, update, and delete, which provide the basis for the improved bulk insert. All officially supported MongoDB drivers support the new write commands.

The mongo shell now includes methods to perform bulk-write operations. See Bulk() for more information.

See also

Write Method Acknowledgements

MSI Package for MongoDB Available for Windows

MongoDB now distributes MSI packages for Microsoft Windows. This is the recommended method for MongoDB installation under Windows.

Security Improvements

MongoDB 2.6 enhances support for secure deployments through improved SSL support, x.509-based authentication, an improved authorization system with more granular controls, as well as centralized credential storage, and improved user management tools.

Specifically these changes include:

A new authorization model that provides the ability to create custom User-Defined Roles and the ability to specify user privileges at a collection-level granularity.

Global user management, which stores all user and user-defined role data in the admin database and provides a new set of commands for managing users and roles.

x.509 certificate authentication for client authentication as well as for internal authentication of sharded and/or replica set cluster members. x.509 authentication is only available for deployments using SSL.

Enhanced SSL Support:

Rolling upgrades of clusters to use SSL.

MongoDB Tools support connections to mongod and mongos instances using SSL connections.

Prompt for passphrase by mongod or mongos at startup.

Require the use of strong SSL ciphers, with a minimum 128-bit key length for all connections. The strong-cipher requirement prevents an old or malicious client from forcing use of a weak cipher.

MongoDB disables the http interface by default, limiting network exposure. To enable the interface, see enabled.

See also

New Authorization Model, SSL Certificate Hostname Validation, and Security Checklist.

Query Engine Improvements

MongoDB can now use index intersection to fulfill queries supported by more than one index.

Index Filters to limit which indexes can become the winning plan for a query.

Query Plan Cache Methods methods to view and clear the query plans cached by the query optimizer.

MongoDB can now use count() with hint(). See count() for details.

Improvements

Geospatial Enhancements

2dsphere indexes version 2.

Support for MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.

Support for geospatial query clauses in $or expressions.

See also

2dsphere Index Version 2, $maxDistance Changes, Deprecated $uniqueDocs, Stronger Validation of Geospatial Queries

Index Build Enhancements

Background index build allowed on secondaries. If you initiate a background index build on a primary, the secondaries will replicate the index build in the background.

Automatic rebuild of interrupted index builds after a restart.

If a standalone or a primary instance terminates during an index build without a clean shutdown, mongod now restarts the index build when the instance restarts. If the instance shuts down cleanly or if a user kills the index build, the interrupted index builds do not automatically restart upon the restart of the server.

If a secondary instance terminates during an index build, the mongod instance will now restart the interrupted index build when the instance restarts.

To disable this behavior, use the --noIndexBuildRetry command-line option.

ensureIndex() now wraps a new createIndex command.

The dropDups option to ensureIndex() and createIndex is deprecated.

See also

Enforce Index Key Length Limit

Enhanced Sharding and Replication Administration

New cleanupOrphaned command to remove orphaned documents from a shard.

New mergeChunks command to combine contiguous chunks located on a single shard. See mergeChunks and Merge Chunks in a Sharded Cluster.

New rs.printReplicationInfo() and rs.printSlaveReplicationInfo() methods to provide a formatted report of the status of a replica set from the perspective of the primary and the secondary, respectively.

Configuration Options YAML File Format

MongoDB 2.6 supports a YAML-based configuration file format in addition to the previous configuration file format. See the documentation of the Configuration File for more information.

Operational Changes

Storage

usePowerOf2Sizes is now the default allocation strategy for all new collections. The new allocation strategy uses more storage relative to total document size but results in lower levels of storage fragmentation and more predictable storage capacity planning over time.

To use the previous exact-fit allocation strategy:

For a specific collection, use collMod with usePowerOf2Sizes set to false.

For all new collections on an entire mongod instance, set newCollectionsUsePowerOf2Sizes to false.

New collections include those: created during initial sync, as well as those created by the mongorestore and mongoimport tools, by running mongod with the --repair option, as well as the restoreDatabase command.

See Storage for more information about MongoDB’s storage system.

Networking

Removed upward limit for the maxIncomingConnections for mongod and mongos. Previous versions capped the maximum possible maxIncomingConnections setting at 20,000 connections.

Connection pools for a mongos instance may be used by multiple MongoDB servers. This can reduce the number of connections needed for high-volume workloads and reduce resource consumption in sharded clusters.

The C++ driver now monitors replica set health with the isMaster command instead of replSetGetStatus. This allows the C++ driver to support systems that require authentication.

New cursor.maxTimeMS() and corresponding maxTimeMS option for commands to specify a time limit.

Tool Improvements

mongo shell supports a global /etc/mongorc.js.

All MongoDB executable files now support the --quiet option to suppress all logging output except for error messages.

mongoimport uses the input filename, without the file extension if any, as the collection name if run without the -c or --collection specification.

mongoexport can now constrain export data using --skip and --limit, as well as order the documents in an export using the --sort option.

mongostat can support the use of --rowcount (-n) with the --discover option to produce the specified number of output lines.

Add strict mode representation for data_numberlong for use by mongoexport and mongoimport.

MongoDB Enterprise Features

The following changes are specific to MongoDB Enterprise Editions:

MongoDB Enterprise for Windows

MongoDB Enterprise for Windows is now available. It includes support for Kerberos, SSL, and SNMP.

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB Enterprise for Windows includes OpenSSL version 1.0.1g.

Auditing

MongoDB Enterprise adds auditing capability for mongod and mongos instances. See Auditing for details.

LDAP Support for Authentication

MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to configure a MongoDB cluster to authenticate users by proxying authentication requests to a specified Lightweight Directory Access Protocol (LDAP) service. See Authenticate Using SASL and LDAP with OpenLDAP and Authenticate Using SASL and LDAP with ActiveDirectory for details.

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards. See Upgrade MongoDB to 2.6 for upgrade instructions.

Expanded SNMP Support

MongoDB Enterprise has greatly expanded its SNMP support to provide SNMP access to nearly the full range of metrics provided by db.serverStatus().

See also

SNMP Changes

Additional Information

Changes Affecting Compatibility

Compatibility Changes in MongoDB 2.6

Index Changes

Enforce Index Key Length Limit

Index Specifications Validate Field Names

ensureIndex and Existing Indexes

Write Method Acknowledgements

db.collection.aggregate() Change

Write Concern Validation

Security Changes

New Authorization Model

SSL Certificate Hostname Validation

2dsphere Index Version 2

Log Messages

Timestamp Format Change

Package Configuration Changes

Default bindIp for RPM/DEB Packages

SNMP Changes

Remove Method Signature Change

Update Operator Syntax Validation

Updates Enforce Field Name Restrictions

Query and Sort Changes

Enforce Field Name Restrictions

Sparse Index and Incomplete Results

sort() Specification Values

skip() and _id Queries

explain() Retains Query Plan Cache

Geospatial Changes

$maxDistance Changes

Deprecated $uniqueDocs

Stronger Validation of Geospatial Queries

Query Operator Changes

$not Query Behavior Changes

null Comparison Queries

$all Operator Behavior Change

$mod Operator Enforces Strict Syntax

$where Must Be Top-Level

$exists and notablescan

MinKey and MaxKey Queries

Nested Array Queries with $elemMatch

Text Search Compatibility

Replica Set/Sharded Cluster Validation

Shard Name Checks on Metadata Refresh

Replica Set Vote Configuration Validation

Time Format Changes

Other Resources

Some changes in 2.6 can affect compatibility and may require user actions. The 2.6 mongo shell provides a db.upgradeCheckAllDBs() method to perform a check for upgrade preparedness for some of these changes.

See Compatibility Changes in MongoDB 2.6 for a detailed list of compatibility changes.

See also

All Backwards incompatible changes (JIRA) [https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20fixVersion%20in%20(%222.5.0%22%2C%20%222.5.1%22%2C%20%222.5.2%22%2C%20%222.5.3%22%2C%20%222.5.4%22%2C%20%222.5.5%22%2C%20%222.6.0-rc1%22%2C%20%222.6.0-rc2%22%2C%20%222.6.0-rc3%22)%20AND%20%22Backwards%20Compatibility%22%20in%20(%20%22Minor%20Change%22%2C%22Major%20Change%22%20)%20ORDER%20BY%20votes%20DESC%2C%20issuetype%20DESC%2C%20key%20DESC].

Upgrade Process

Upgrade MongoDB to 2.6

Upgrade Recommendations and Checklists

Upgrade Requirements

Preparedness

Authentication

Downgrade Limitations

Package Upgrades

Upgrade MongoDB Processes

Upgrade Standalone mongod Instance to MongoDB 2.6

Upgrade a Replica Set to 2.6

Upgrade secondary members of the replica set.

Step 1: Upgrade secondary members of the replica set.

Step down the replica set primary.

Step 2: Step down the replica set primary.

Upgrade the primary.

Step 3: Upgrade the primary.

Upgrade a Sharded Cluster to 2.6

Considerations

Upgrade Sharded Clusters

Disable the Balancer.

Step 1: Disable the Balancer.

Upgrade the cluster’s meta data.

Step 2: Upgrade the cluster’s meta data.

Ensure mongos --upgrade process completes successfully.

Step 3: Ensure mongos --upgrade process completes successfully.

Upgrade the remaining mongos instances to v2.6.

Step 4: Upgrade the remaining mongos instances to v2.6.

Complete Sharded Cluster Upgrade

Upgrade Procedure

Stop the existing mongod instance.

Step 1: Stop the existing mongod instance.

Start the new mongod instance.

Step 2: Start the new mongod instance.

Upgrade User Authorization Data to 2.6 Format

Considerations

Complete all other Upgrade Requirements

Timing

Replica Sets

Sharded Clusters

Requirements

Procedure

Connect to MongoDB instance.

Step 1: Connect to MongoDB instance.

Upgrade authorization schema.

Run authSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

Step 2: Upgrade authorization schema.

Run authSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

Result

Downgrade MongoDB from 2.6

Downgrade Recommendations and Checklist

Downgrade Path

Preparedness

Procedures

Downgrade 2.6 User Authorization Model

Considerations

Access Control Prerequisites

Connect as user with privileges to manage users and roles.

Step 1: Connect as user with privileges to manage users and roles.

Create a role with required privileges.

Step 2: Create a role with required privileges.

Create a user with the new role.

Step 3: Create a user with the new role.

Authenticate as the new user.

Step 4: Authenticate as the new user.

Procedure

Connect and authenticate to MongoDB instance.

Step 1: Connect and authenticate to MongoDB instance.

Create backup of 2.6 admin.system.users collection.

Step 2: Create backup of 2.6 admin.system.users collection.

Update the version document for the authSchema.

Step 3: Update the version document for the authSchema.

Remove existing documents from the admin.system.users collection.

Step 4: Remove existing documents from the admin.system.users collection.

Copy documents from the admin.system.backup_users collection.

Step 5: Copy documents from the admin.system.backup_users collection.

Update the version document for the authSchema.

Step 6: Update the version document for the authSchema.

Result

Downgrade Updated Indexes

Text Index Version Check

2dsphere Index Version Check

Downgrade MongoDB Processes

Downgrade 2.6 Standalone mongod Instance

Downgrade a 2.6 Replica Set

Downgrade each secondary member, one at a time.

Replace and restart secondary mongod instances.

Allow secondary to recover.

Step 1: Downgrade each secondary member, one at a time.

Replace and restart secondary mongod instances.

Allow secondary to recover.

Step down the primary.

Step 2: Step down the primary.

Replace and restart former primary mongod.

Step 3: Replace and restart former primary mongod.

Downgrade a 2.6 Sharded Cluster

Requirements

Procedure

Downgrade Procedure

Stop the existing mongod instance.

Step 1: Stop the existing mongod instance.

Start the new mongod instance.

Step 2: Start the new mongod instance.

See Upgrade MongoDB to 2.6 for full upgrade instructions.

Download

To download MongoDB 2.6, go to the downloads page [http://www.mongodb.org/downloads].

Other Resources

All JIRA issues resolved in 2.6 [https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+fixVersion+in+%28%222.5.0%22%2C+%222.5.1%22%2C+%222.5.2%22%2C+%222.5.3%22%2C+%222.5.4%22%2C+%222.5.5%22%2C+%222.6.0-rc1%22%2C+%222.6.0-rc2%22%2C+%222.6.0-rc3%22%29].

All Third Party License Notices [https://github.com/mongodb/mongo/blob/v2.6/distsrc/THIRD-PARTY-NOTICES].

2.6 Changelog

2.6.8 – Changes

Security and Networking

SERVER-17278 [https://jira.mongodb.org/browse/SERVER-17278] BSON BinData validation enforcement

SERVER-17022 [https://jira.mongodb.org/browse/SERVER-17022] No SSL Session Caching may not be respected

SERVER-17264 [https://jira.mongodb.org/browse/SERVER-17264] improve bson validation

Query and Aggregation

SERVER-16655 [https://jira.mongodb.org/browse/SERVER-16655] Geo predicate is unable to use compound 2dsphere index if it is root of $or clause

SERVER-16527 [https://jira.mongodb.org/browse/SERVER-16527] 2dsphere explain reports “works” for nscanned & nscannedObjects

SERVER-15802 [https://jira.mongodb.org/browse/SERVER-15802] Query optimizer should always use equality predicate over unique index when possible

SERVER-14044 [https://jira.mongodb.org/browse/SERVER-14044] Incorrect {$meta: 'text'} reference in aggregation $sort error message

Replication

SERVER-16599 [https://jira.mongodb.org/browse/SERVER-16599] copydb and clone commands can crash the server if a primary steps down

SERVER-16315 [https://jira.mongodb.org/browse/SERVER-16315] Replica set nodes should not threaten to veto nodes whose config version is higher than their own

SERVER-16274 [https://jira.mongodb.org/browse/SERVER-16274] secondary fasserts trying to replicate an index

SERVER-15471 [https://jira.mongodb.org/browse/SERVER-15471] Better error message when replica is not found in GhostSync::associateSlave

Sharding

SERVER-17191 [https://jira.mongodb.org/browse/SERVER-17191] Spurious warning during upgrade of sharded cluster

SERVER-17163 [https://jira.mongodb.org/browse/SERVER-17163] Fatal error “logOp but not primary” in MigrateStatus::go

SERVER-16984 [https://jira.mongodb.org/browse/SERVER-16984] UpdateLifecycleImpl can return empty collectionMetadata even if ns is sharded

SERVER-10904 [https://jira.mongodb.org/browse/SERVER-10904] Possible for _master and _slaveConn to be pointing to different connections even with primary read pref

Storage

SERVER-17087 [https://jira.mongodb.org/browse/SERVER-17087] Add listCollections command functionality to 2.6 shell & client

SERVER-14572 [https://jira.mongodb.org/browse/SERVER-14572] Increase C runtime stdio file limit

Tools

SERVER-17216 [https://jira.mongodb.org/browse/SERVER-17216] 2.6 mongostat cannot be used with 3.0 mongod

SERVER-14190 [https://jira.mongodb.org/browse/SERVER-14190] mongorestore parseMetadataFile passes non-null terminated string to ‘fromjson‘

Build and Packaging

SERVER-14803 [https://jira.mongodb.org/browse/SERVER-14803] Support static libstdc++ builds for non-Linux builds

SERVER-15400 [https://jira.mongodb.org/browse/SERVER-15400] Create Windows Enterprise Zip File with vcredist and dependent dlls

Usability

SERVER-14756 [https://jira.mongodb.org/browse/SERVER-14756] The YAML storage.quota.enforced option is not found

Testing

SERVER-16421 [https://jira.mongodb.org/browse/SERVER-16421] sharding_rs2.js should clean up data on all replicas

2.6.7 – Changes

Stability

SERVER-16237 [https://jira.mongodb.org/browse/SERVER-16237] Don’t check the shard version if the primary server is down

Querying

SERVER-16408 [https://jira.mongodb.org/browse/SERVER-16408] max_time_ms.js should not run in parallel suite.

Replication

SERVER-16732 [https://jira.mongodb.org/browse/SERVER-16732] SyncSourceFeedback::replHandshake() may perform an illegal erase from a std::map in some circumstances

Sharding

SERVER-16683 [https://jira.mongodb.org/browse/SERVER-16683] Decrease mongos memory footprint when shards have several tags

SERVER-15766 [https://jira.mongodb.org/browse/SERVER-15766] prefix_shard_key.js depends on primary allocation to particular shards

SERVER-14306 [https://jira.mongodb.org/browse/SERVER-14306] mongos can cause shards to hit the in-memory sort limit by requesting more results than needed.

Packaging

SERVER-16081 [https://jira.mongodb.org/browse/SERVER-16081] /etc/init.d/mongod startup script fails, with dirname message

2.6.6 – Changes

Security

SERVER-15673 [https://jira.mongodb.org/browse/SERVER-15673] Disable SSLv3 ciphers

SERVER-15515 [https://jira.mongodb.org/browse/SERVER-15515] New test for mixed version replSet, 2.4 primary, user updates

SERVER-15500 [https://jira.mongodb.org/browse/SERVER-15500] New test for system.user operations

Stability

SERVER-12061 [https://jira.mongodb.org/browse/SERVER-12061] Do not silently ignore read errors when syncing a replica set node

SERVER-12058 [https://jira.mongodb.org/browse/SERVER-12058] Primary should abort if encountered problems writing to the oplog

Querying

SERVER-16291 [https://jira.mongodb.org/browse/SERVER-16291] Cannot set/list/clear index filters on the secondary

SERVER-15958 [https://jira.mongodb.org/browse/SERVER-15958] The “isMultiKey” value is not correct in the output of aggregation explain plan

SERVER-15899 [https://jira.mongodb.org/browse/SERVER-15899] Querying against path in document containing long array of subdocuments with nested arrays causes stack overflow

SERVER-15696 [https://jira.mongodb.org/browse/SERVER-15696] $regex, $in and $sort with index returns too many results

SERVER-15639 [https://jira.mongodb.org/browse/SERVER-15639] Text queries can return incorrect results and leak memory when multiple predicates given on same text index prefix field

SERVER-15580 [https://jira.mongodb.org/browse/SERVER-15580] Evaluating candidate query plans with concurrent writes on same collection may crash :program:``mongod

SERVER-15528 [https://jira.mongodb.org/browse/SERVER-15528] Distinct queries can scan many index keys without yielding read lock

SERVER-15485 [https://jira.mongodb.org/browse/SERVER-15485] CanonicalQuery::canonicalize can leak a LiteParsedQuery

SERVER-15403 [https://jira.mongodb.org/browse/SERVER-15403] $min and $max equal errors in 2.6 but not in 2.4

SERVER-15233 [https://jira.mongodb.org/browse/SERVER-15233] Cannot run planCacheListQueryShapes on a Secondary

SERVER-14799 [https://jira.mongodb.org/browse/SERVER-14799] count with hint doesn’t work when hint is a document

Replication

SERVER-16107 [https://jira.mongodb.org/browse/SERVER-16107] 2.6 mongod crashes with segfault when added to a 2.8 replica set with >= 12 nodes.

SERVER-15994 [https://jira.mongodb.org/browse/SERVER-15994] listIndexes and listCollections can be run on secondaries without slaveOk bit

SERVER-15849 [https://jira.mongodb.org/browse/SERVER-15849] do not forward replication progress for nodes that are no longer part of a replica set

SERVER-15491 [https://jira.mongodb.org/browse/SERVER-15491] SyncSourceFeedback can crash due to a SocketException in authenticateInternalUser

Sharding

SERVER-15318 [https://jira.mongodb.org/browse/SERVER-15318] copydb should not use exhaust flag when used against mongos

SERVER-14728 [https://jira.mongodb.org/browse/SERVER-14728] Shard depends on string comparison of replica set connection string

SERVER-14506 [https://jira.mongodb.org/browse/SERVER-14506] special top chunk logic can move max chunk to a shard with incompatible tag

SERVER-14299 [https://jira.mongodb.org/browse/SERVER-14299] For sharded limit=N queries with sort, mongos can request >N results from shard

SERVER-14080 [https://jira.mongodb.org/browse/SERVER-14080] Have migration result reported in the changelog correctly

SERVER-12472 [https://jira.mongodb.org/browse/SERVER-12472] Fail MoveChunk if an index is needed on TO shard and data exists

Storage

SERVER-16283 [https://jira.mongodb.org/browse/SERVER-16283] Can’t start new wiredtiger node with log file or config file in data directory - false detection of old mmapv1 files

SERVER-15986 [https://jira.mongodb.org/browse/SERVER-15986] Starting with different storage engines in the same dbpath should error/warn

SERVER-14057 [https://jira.mongodb.org/browse/SERVER-14057] Changing TTL expiration time with collMod does not correctly update index definition

Indexing and write Operations

SERVER-14287 [https://jira.mongodb.org/browse/SERVER-14287] ensureIndex can abort reIndex and lose indexes

SERVER-14886 [https://jira.mongodb.org/browse/SERVER-14886] Updates against paths composed with array index notation and positional operator fail with error

Data Aggregation

SERVER-15552 [https://jira.mongodb.org/browse/SERVER-15552] Errors writing to temporary collections during mapReduce command execution should be operation-fatal

Build and Packaging

SERVER-14184 [https://jira.mongodb.org/browse/SERVER-14184] Unused preprocessor macros from s2 conflict on OS X Yosemite

SERVER-14015 [https://jira.mongodb.org/browse/SERVER-14015] S2 Compilation on GCC 4.9/Solaris fails

SERVER-16017 [https://jira.mongodb.org/browse/SERVER-16017] Suse11 enterprise packages fail due to unmet dependencies

SERVER-15598 [https://jira.mongodb.org/browse/SERVER-15598] Ubuntu 14.04 Enterprise packages depend on unavailable libsnmp15 package

SERVER-13595 [https://jira.mongodb.org/browse/SERVER-13595] Red Hat init.d script error: YAML config file parsing

Logging and Diagnostics

SERVER-13471 [https://jira.mongodb.org/browse/SERVER-13471] Increase log level of “did reduceInMemory” message in map/reduce

SERVER-16324 [https://jira.mongodb.org/browse/SERVER-16324] Command execution log line displays “query not recording (too large)” instead of abbreviated command object

SERVER-10069 [https://jira.mongodb.org/browse/SERVER-10069] Improve errorcodes.py so it captures multiline messages

Testing and Internals

SERVER-15632 [https://jira.mongodb.org/browse/SERVER-15632] MultiHostQueryOp::PendingQueryContext::doBlockingQuery can leak a cursor object

SERVER-15629 [https://jira.mongodb.org/browse/SERVER-15629] GeoParser::parseMulti{Line|Polygon} does not clear objects owned by out parameter

SERVER-16316 [https://jira.mongodb.org/browse/SERVER-16316] Remove unsupported behavior in shard3.js

SERVER-14763 [https://jira.mongodb.org/browse/SERVER-14763] Update jstests/sharding/split_large_key.js

SERVER-14249 [https://jira.mongodb.org/browse/SERVER-14249] Add tests for querying oplog via mongodump using –dbpath

SERVER-13726 [https://jira.mongodb.org/browse/SERVER-13726] indexbg_drop.js

2.6.5 – Changes

Security

SERVER-15465 [https://jira.mongodb.org/browse/SERVER-15465] OpenSSL crashes on stepdown

SERVER-15360 [https://jira.mongodb.org/browse/SERVER-15360] User document changes made on a 2.4 primary and replicated to a 2.6 secondary don’t make the 2.6 secondary invalidate its user cache

SERVER-14887 [https://jira.mongodb.org/browse/SERVER-14887] Allow user document changes made on a 2.4 primary to replicate to a 2.6 secondary

SERVER-14727 [https://jira.mongodb.org/browse/SERVER-14727] Details of SASL failures aren’t logged

SERVER-12551 [https://jira.mongodb.org/browse/SERVER-12551] Audit DML/CRUD operations

Stability

SERVER-9032 [https://jira.mongodb.org/browse/SERVER-9032] mongod fails when launched with misconfigured locale

Querying

SERVER-15287 [https://jira.mongodb.org/browse/SERVER-15287] Query planner sort analysis incorrectly allows index key pattern plugin fields to provide sort

SERVER-15286 [https://jira.mongodb.org/browse/SERVER-15286] Assertion in date indexes when opposite-direction-sorted and double “or” filtered

SERVER-15279 [https://jira.mongodb.org/browse/SERVER-15279] Disable hash-based index intersection (AND_HASH) by default

SERVER-15152 [https://jira.mongodb.org/browse/SERVER-15152] When evaluating plans, some index candidates cause complete index scan

SERVER-15015 [https://jira.mongodb.org/browse/SERVER-15015] Assertion failure when combining $max and $min and reverse index scan

SERVER-15012 [https://jira.mongodb.org/browse/SERVER-15012] Server crashes on indexed rooted $or queries using a 2d index

SERVER-14969 [https://jira.mongodb.org/browse/SERVER-14969] Dropping index during active aggregation operation can crash server

SERVER-14961 [https://jira.mongodb.org/browse/SERVER-14961] Plan ranker favors intersection plans if predicate generates empty range index scan

SERVER-14892 [https://jira.mongodb.org/browse/SERVER-14892] Invalid {$elemMatch: {$where}} query causes memory leak

SERVER-14706 [https://jira.mongodb.org/browse/SERVER-14706] Queries that use negated $type predicate over a field may return incomplete results when an index is present on that field

SERVER-13104 [https://jira.mongodb.org/browse/SERVER-13104] Plan enumerator doesn’t enumerate all possibilities for a nested $or

SERVER-14984 [https://jira.mongodb.org/browse/SERVER-14984] Server aborts when running $centerSphere query with NaN radius

SERVER-14981 [https://jira.mongodb.org/browse/SERVER-14981] Server aborts when querying against 2dsphere index with coarsestIndexedLevel:0

SERVER-14831 [https://jira.mongodb.org/browse/SERVER-14831] Text search trips assertion when default language only supported in textIndexVersion=1 used

Replication

SERVER-15038 [https://jira.mongodb.org/browse/SERVER-15038] Multiple background index builds may not interrupt cleanly for commands, on secondaries

SERVER-14887 [https://jira.mongodb.org/browse/SERVER-14887] Allow user document changes made on a 2.4 primary to replicate to a 2.6 secondary

SERVER-14805 [https://jira.mongodb.org/browse/SERVER-14805] Use multithreaded oplog replay during initial sync

Sharding

SERVER-15056 [https://jira.mongodb.org/browse/SERVER-15056] Sharded connection cleanup on setup error can crash mongos

SERVER-13702 [https://jira.mongodb.org/browse/SERVER-13702] Commands without optional query may target to wrong shards on mongos

SERVER-15156 [https://jira.mongodb.org/browse/SERVER-15156] MongoDB upgrade 2.4 to 2.6 check returns error in config.changelog collection

Storage

SERVER-15369 [https://jira.mongodb.org/browse/SERVER-15369] explicitly zero .ns files on creation

SERVER-15319 [https://jira.mongodb.org/browse/SERVER-15319] Verify 2.8 freelist is upgrade-downgrade safe with 2.6

SERVER-15111 [https://jira.mongodb.org/browse/SERVER-15111] partially written journal last section causes recovery to fail

Indexing

SERVER-14848 [https://jira.mongodb.org/browse/SERVER-14848] Port index_id_desc.js to v2.6 and master branches

SERVER-14205 [https://jira.mongodb.org/browse/SERVER-14205] ensureIndex failure reports ok: 1 on some failures

Write Operations

SERVER-15106 [https://jira.mongodb.org/browse/SERVER-15106] Incorrect nscanned and nscannedObjects for idhack updates in 2.6.4 profiler or slow query log

SERVER-15029 [https://jira.mongodb.org/browse/SERVER-15029] The $rename modifier uses incorrect dotted source path

SERVER-14829 [https://jira.mongodb.org/browse/SERVER-14829] UpdateIndexData::clear() should reset all member variables

Data Aggregation

SERVER-15087 [https://jira.mongodb.org/browse/SERVER-15087] Server crashes when running concurrent mapReduce and dropDatabase commands

SERVER-14969 [https://jira.mongodb.org/browse/SERVER-14969] Dropping index during active aggregation operation can crash server

SERVER-14168 [https://jira.mongodb.org/browse/SERVER-14168] Warning logged when incremental MR collections are unsuccessfully dropped on secondaries

Packaging

SERVER-14679 [https://jira.mongodb.org/browse/SERVER-14679] (CentOS 7/RHEL 7) init.d script should create directory for pid file if it is missing

SERVER-14023 [https://jira.mongodb.org/browse/SERVER-14023] Support for RHEL 7 Enterprise .rpm packages

SERVER-13243 [https://jira.mongodb.org/browse/SERVER-13243] Support for Ubuntu 14 “Trusty” Enterprise .deb packages

SERVER-11077 [https://jira.mongodb.org/browse/SERVER-11077] Support for Debian 7 Enterprise .deb packages

SERVER-10642 [https://jira.mongodb.org/browse/SERVER-10642] Generate Community and Enterprise packages for SUSE 11

Logging and Diagnostics

SERVER-14964 [https://jira.mongodb.org/browse/SERVER-14964] nscanned not written to the logs at logLevel 1 unless slowms exceeded or profiling enabled

SERVER-12551 [https://jira.mongodb.org/browse/SERVER-12551] Audit DML/CRUD operations

SERVER-14904 [https://jira.mongodb.org/browse/SERVER-14904] Adjust dates in tool/exportimport_date.js to account for different timezones

Internal Code and Testing

SERVER-13770 [https://jira.mongodb.org/browse/SERVER-13770] Helpers::removeRange should check all runner states

SERVER-14284 [https://jira.mongodb.org/browse/SERVER-14284] jstests should not leave profiler enabled at test run end

SERVER-14076 [https://jira.mongodb.org/browse/SERVER-14076] remove test replset_remove_node.js

SERVER-14778 [https://jira.mongodb.org/browse/SERVER-14778] Hide function and data pointers for natively-injected v8 functions

2.6.4 – Changes

Security

SERVER-14701 [https://jira.mongodb.org/browse/SERVER-14701] The “backup” auth role should allow running the “collstats” command for all resources

SERVER-14518 [https://jira.mongodb.org/browse/SERVER-14518] Allow disabling hostname validation for SSL

SERVER-14268 [https://jira.mongodb.org/browse/SERVER-14268] Potential information leak

SERVER-14170 [https://jira.mongodb.org/browse/SERVER-14170] Cannot read from secondary if both audit and auth are enabled in a sharded cluster

SERVER-13833 [https://jira.mongodb.org/browse/SERVER-13833] userAdminAnyDatabase role should be able to create indexes on admin.system.users and admin.system.roles

SERVER-12512 [https://jira.mongodb.org/browse/SERVER-12512] Add role-based, selective audit logging.

SERVER-9482 [https://jira.mongodb.org/browse/SERVER-9482] Add build flag for sslFIPSMode

Querying

SERVER-14625 [https://jira.mongodb.org/browse/SERVER-14625] Query planner can construct incorrect bounds for negations inside $elemMatch

SERVER-14607 [https://jira.mongodb.org/browse/SERVER-14607] hash intersection of fetched and non-fetched data can discard data from a result

SERVER-14532 [https://jira.mongodb.org/browse/SERVER-14532] Improve logging in the case of plan ranker ties

SERVER-14350 [https://jira.mongodb.org/browse/SERVER-14350] Server crash when $centerSphere has non-positive radius

SERVER-14317 [https://jira.mongodb.org/browse/SERVER-14317] Dead code in IDHackRunner::applyProjection

SERVER-14311 [https://jira.mongodb.org/browse/SERVER-14311] skipping of index keys is not accounted for in plan ranking by the index scan stage

SERVER-14123 [https://jira.mongodb.org/browse/SERVER-14123] some operations can create BSON object larger than the 16MB limit

SERVER-14034 [https://jira.mongodb.org/browse/SERVER-14034] Sorted $in query with large number of elements can’t use merge sort

SERVER-13994 [https://jira.mongodb.org/browse/SERVER-13994] do not aggressively pre-fetch data for parallelCollectionScan

Replication

SERVER-14665 [https://jira.mongodb.org/browse/SERVER-14665] Build failure for v2.6 in closeall.js caused by access violation reading _me

SERVER-14505 [https://jira.mongodb.org/browse/SERVER-14505] cannot dropAllIndexes when index builds in progress assertion failure

SERVER-14494 [https://jira.mongodb.org/browse/SERVER-14494] Dropping collection during active background index build on secondary triggers segfault

SERVER-13822 [https://jira.mongodb.org/browse/SERVER-13822] Running resync before replset config is loaded can crash mongod

SERVER-11776 [https://jira.mongodb.org/browse/SERVER-11776] Replication ‘isself’ check should allow mapped ports

Sharding

SERVER-14551 [https://jira.mongodb.org/browse/SERVER-14551] Runner yield during migration cleanup (removeRange) results in fassert

SERVER-14431 [https://jira.mongodb.org/browse/SERVER-14431] Invalid chunk data after splitting on a key that’s too large

SERVER-14261 [https://jira.mongodb.org/browse/SERVER-14261] stepdown during migration range delete can abort mongod

SERVER-14032 [https://jira.mongodb.org/browse/SERVER-14032] v2.6 mongos doesn’t verify _id is present for config server upserts

SERVER-13648 [https://jira.mongodb.org/browse/SERVER-13648] better stats from migration cleanup

SERVER-12750 [https://jira.mongodb.org/browse/SERVER-12750] mongos shouldn’t accept initial query with “exhaust” flag set

SERVER-9788 [https://jira.mongodb.org/browse/SERVER-9788] mongos does not re-evaluate read preference once a valid replica set member is chosen

SERVER-9526 [https://jira.mongodb.org/browse/SERVER-9526] Log messages regarding chunks not very informative when the shard key is of type BinData

Storage

SERVER-14198 [https://jira.mongodb.org/browse/SERVER-14198] Std::set<pointer> and Windows Heap Allocation Reuse produces non-deterministic results

SERVER-13975 [https://jira.mongodb.org/browse/SERVER-13975] Creating index on collection named “system” can cause server to abort

SERVER-13729 [https://jira.mongodb.org/browse/SERVER-13729] Reads & Writes are blocked during data file allocation on Windows

SERVER-13681 [https://jira.mongodb.org/browse/SERVER-13681] mongod B stalls during background flush on Windows

Indexing

SERVER-14494 [https://jira.mongodb.org/browse/SERVER-14494] Dropping collection during active background index build on secondary triggers segfault

Write Ops

SERVER-14257 [https://jira.mongodb.org/browse/SERVER-14257] “remove” command can cause process termination by throwing unhandled exception if profiling is enabled

SERVER-14024 [https://jira.mongodb.org/browse/SERVER-14024] Update fails when query contains part of a DBRef and results in an insert (upsert:true)

SERVER-13764 [https://jira.mongodb.org/browse/SERVER-13764] debug mechanisms report incorrect nscanned / nscannedObjects for updates

Networking

SERVER-13734 [https://jira.mongodb.org/browse/SERVER-13734] Remove catch (...) from handleIncomingMsg

Geo

SERVER-14039 [https://jira.mongodb.org/browse/SERVER-14039] $nearSphere query with 2d index, skip, and limit returns incomplete results

SERVER-13701 [https://jira.mongodb.org/browse/SERVER-13701] Query using 2d index throws exception when using explain()

Text Search

SERVER-14738 [https://jira.mongodb.org/browse/SERVER-14738] Updates to documents with text-indexed fields may lead to incorrect entries

SERVER-14027 [https://jira.mongodb.org/browse/SERVER-14027] Renaming collection within same database fails if wildcard text index present

Tools

SERVER-14212 [https://jira.mongodb.org/browse/SERVER-14212] mongorestore may drop system users and roles

SERVER-14048 [https://jira.mongodb.org/browse/SERVER-14048] mongodump against mongos can’t send dump to standard output

Admin

SERVER-14556 [https://jira.mongodb.org/browse/SERVER-14556] Default dbpath for mongod --configsvr changes in 2.6

SERVER-14355 [https://jira.mongodb.org/browse/SERVER-14355] Allow dbAdmin role to manually create system.profile collections

Packaging

SERVER-14283 [https://jira.mongodb.org/browse/SERVER-14283] Parameters in installed config file are out of date

JavaScript

SERVER-14254 [https://jira.mongodb.org/browse/SERVER-14254] Do not store native function pointer as a property in function prototype

SERVER-13798 [https://jira.mongodb.org/browse/SERVER-13798] v8 garbage collection can cause crash due to independent lifetime of DBClient and Cursor objects

SERVER-13707 [https://jira.mongodb.org/browse/SERVER-13707] mongo shell may crash when converting invalid regular expression

Shell

SERVER-14341 [https://jira.mongodb.org/browse/SERVER-14341] negative opcounter values in serverStatus

SERVER-14107 [https://jira.mongodb.org/browse/SERVER-14107] Querying for a document containing a value of either type Javascript or JavascriptWithScope crashes the shell

Usability

SERVER-13833 [https://jira.mongodb.org/browse/SERVER-13833] userAdminAnyDatabase role should be able to create indexes on admin.system.users and admin.system.roles

Logging and Diagnostics

SERVER-12512 [https://jira.mongodb.org/browse/SERVER-12512] Add role-based, selective audit logging.

SERVER-14341 [https://jira.mongodb.org/browse/SERVER-14341] negative opcounter values in serverStatus

Testing

SERVER-14731 [https://jira.mongodb.org/browse/SERVER-14731] plan_cache_ties.js sometimes fails

SERVER-14147 [https://jira.mongodb.org/browse/SERVER-14147] make index_multi.js retry on connection failure

SERVER-13615 [https://jira.mongodb.org/browse/SERVER-13615] sharding_rs2.js intermittent failure due to reliance on opcounters

2.6.3 – Changes

SERVER-14302 [https://jira.mongodb.org/browse/SERVER-14302] Fixed: “Equality queries on _id with projection may return no results on sharded collections”

SERVER-14304 [https://jira.mongodb.org/browse/SERVER-14304] Fixed: “Equality queries on _id with projection on _id may return orphan documents on sharded collections”

2.6.2 – Changes

Security

SERVER-13727 [https://jira.mongodb.org/browse/SERVER-13727] The backup authorization role now includes privileges to run the collStats command.

SERVER-13804 [https://jira.mongodb.org/browse/SERVER-13804] The built-in role restore now has privileges on system.roles collection.

SERVER-13612 [https://jira.mongodb.org/browse/SERVER-13612] Fixed: “SSL-enabled server appears not to be sending the list of supported certificate issuers to the client”

SERVER-13753 [https://jira.mongodb.org/browse/SERVER-13753] Fixed: “mongod may terminate if x.509 authentication certificate is invalid”

SERVER-13945 [https://jira.mongodb.org/browse/SERVER-13945] For replica set/sharded cluster member authentication, now matches x.509 cluster certificates by attributes instead of by substring comparison.

SERVER-13868 [https://jira.mongodb.org/browse/SERVER-13868] Now marks V1 users as probed on databases that do not have surrogate user documents.

SERVER-13850 [https://jira.mongodb.org/browse/SERVER-13850] Now ensures that the user cache entry is up to date before using it to determine a user’s roles in user management commands on mongos.

SERVER-13588 [https://jira.mongodb.org/browse/SERVER-13588] Fixed: “Shell prints startup warning when auth enabled”

Querying

SERVER-13731 [https://jira.mongodb.org/browse/SERVER-13731] Fixed: “Stack overflow when parsing deeply nested $not query”

SERVER-13890 [https://jira.mongodb.org/browse/SERVER-13890] Fixed: “Index bounds builder constructs invalid bounds for multiple negations joined by an $or“

SERVER-13752 [https://jira.mongodb.org/browse/SERVER-13752] Verified assertion on empty $in clause and sort on second field in a compound index.

SERVER-13337 [https://jira.mongodb.org/browse/SERVER-13337] Re-enabled idhack for queries with projection.

SERVER-13715 [https://jira.mongodb.org/browse/SERVER-13715] Fixed: “Aggregation pipeline execution can fail with $or and blocking sorts”

SERVER-13714 [https://jira.mongodb.org/browse/SERVER-13714] Fixed: “non-top-level indexable $not triggers query planning bug”

SERVER-13769 [https://jira.mongodb.org/browse/SERVER-13769] Fixed: “distinct command on indexed field with geo predicate fails to execute”

SERVER-13675 [https://jira.mongodb.org/browse/SERVER-13675] Fixed “Plans with differing performance can tie during plan ranking”

SERVER-13899 [https://jira.mongodb.org/browse/SERVER-13899] Fixed: “‘Whole index scan’ query solutions can use incompatible indexes, return incorrect results”

SERVER-13852 [https://jira.mongodb.org/browse/SERVER-13852] Fixed “IndexBounds::endKeyInclusive not initialized by constructor”

SERVER-14073 [https://jira.mongodb.org/browse/SERVER-14073] planSummary no longer truncated at 255 characters

SERVER-14174 [https://jira.mongodb.org/browse/SERVER-14174] Fixed: “If ntoreturn is a limit (rather than batch size) extra data gets buffered during plan ranking”

SERVER-13789 [https://jira.mongodb.org/browse/SERVER-13789] Some nested queries no longer trigger an assertion error

SERVER-14064 [https://jira.mongodb.org/browse/SERVER-14064] Added planSummary information for count command log message.

SERVER-13960 [https://jira.mongodb.org/browse/SERVER-13960] Queries containing $or no longer miss results if multiple clauses use the same index.

SERVER-14180 [https://jira.mongodb.org/browse/SERVER-14180] Fixed: “Crash with ‘and’ clause, $elemMatch, and nested $mod or regex”

SERVER-14176 [https://jira.mongodb.org/browse/SERVER-14176] Natural order sort specification no longer ignored if query is specified.

SERVER-13754 [https://jira.mongodb.org/browse/SERVER-13754] Bounds no longer combined for $or queries that can use merge sort.

Geospatial

SERVER-13687 [https://jira.mongodb.org/browse/SERVER-13687] Results of $near query on compound multi-key 2dsphere index are now sorted by distance.

Write Operations

SERVER-13802 [https://jira.mongodb.org/browse/SERVER-13802] Insert field validation no longer stops at first Timestamp() field.

Replication

SERVER-13993 [https://jira.mongodb.org/browse/SERVER-13993] Fixed: “log a message when shouldChangeSyncTarget() believes a node should change sync targets”

SERVER-13976 [https://jira.mongodb.org/browse/SERVER-13976] Fixed: “Cloner needs to detect failure to create collection”

Sharding

SERVER-13616 [https://jira.mongodb.org/browse/SERVER-13616] Resolved: “‘type 7’ (OID) error when acquiring distributed lock for first time”

SERVER-13812 [https://jira.mongodb.org/browse/SERVER-13812] Now catches exception thrown by getShardsForQuery for geo query.

SERVER-14138 [https://jira.mongodb.org/browse/SERVER-14138] mongos will now correctly target multiple shards for nested field shard key predicates.

SERVER-11332 [https://jira.mongodb.org/browse/SERVER-11332] Fixed: “Authentication requests delayed if first config server is unresponsive”

Map/Reduce

SERVER-14186 [https://jira.mongodb.org/browse/SERVER-14186] Resolved: “rs.stepDown during mapReduce causes fassert in logOp”

SERVER-13981 [https://jira.mongodb.org/browse/SERVER-13981] Temporary map/reduce collections are now correctly replicated to secondaries.

Storage

SERVER-13750 [https://jira.mongodb.org/browse/SERVER-13750] convertToCapped on empty collection no longer aborts after invariant() failure.

SERVER-14056 [https://jira.mongodb.org/browse/SERVER-14056] Moving large collection across databases with renameCollection no longer triggers fatal assertion.

SERVER-14082 [https://jira.mongodb.org/browse/SERVER-14082] Fixed: “Excessive freelist scanning for MaxBucket”

SERVER-13737 [https://jira.mongodb.org/browse/SERVER-13737] CollectionOptions parser now skips non-numeric for “size”/”max” elements if values non-numeric.

Build and Packaging

SERVER-13950 [https://jira.mongodb.org/browse/SERVER-13950] MongoDB Enterprise now includes required dependency list.

SERVER-13862 [https://jira.mongodb.org/browse/SERVER-13862] Support for mongodb-org-server installation 2.6.1-1 on RHEL5 via RPM.

SERVER-13724 [https://jira.mongodb.org/browse/SERVER-13724] Added SCons flag to override treating all warnings as errors.

Diagnostics

SERVER-13587 [https://jira.mongodb.org/browse/SERVER-13587] Resolved: “ndeleted in system.profile documents reports 1 too few documents removed”

SERVER-13368 [https://jira.mongodb.org/browse/SERVER-13368] Improved exposure of timing information in currentOp.

Administration

SERVER-13954 [https://jira.mongodb.org/browse/SERVER-13954] security.javascriptEnabled option is now available in the YAML configuration file.

Tools

SERVER-10464 [https://jira.mongodb.org/browse/SERVER-10464] mongodump can now query oplog.$main and oplog.rs when using --dbpath.

SERVER-13760 [https://jira.mongodb.org/browse/SERVER-13760] mongoexport can now handle large timestamps on Windows.

Shell

SERVER-13865 [https://jira.mongodb.org/browse/SERVER-13865] Shell now returns correct WriteResult for compatibility-mode upsert with non-OID equality predicate on _id field.

SERVER-13037 [https://jira.mongodb.org/browse/SERVER-13037] Fixed typo in error message for “compatibility mode”.

Internal Code

SERVER-13794 [https://jira.mongodb.org/browse/SERVER-13794] Fixed: “Unused snapshot history consuming significant heap space”

SERVER-13446 [https://jira.mongodb.org/browse/SERVER-13446] Removed Solaris builds dependency on ILLUMOS libc.

SERVER-14092 [https://jira.mongodb.org/browse/SERVER-14092] MongoDB upgrade 2.4 to 2.6 check no longer returns an error in internal collections.

SERVER-14000 [https://jira.mongodb.org/browse/SERVER-14000] Added new lsb file location for Debian 7.1

Testing

SERVER-13723 [https://jira.mongodb.org/browse/SERVER-13723] Stabilized tags.js after a change in its timeout when it was ported to use write commands.

SERVER-13494 [https://jira.mongodb.org/browse/SERVER-13494] Fixed: “setup_multiversion_mongodb.py doesn’t download 2.4.10 because of non-numeric version sorting”

SERVER-13603 [https://jira.mongodb.org/browse/SERVER-13603] Fixed: “Test suites with options tests fail when run with --nopreallocj“

SERVER-13948 [https://jira.mongodb.org/browse/SERVER-13948] Fixed: “awaitReplication() failures related to getting a config version from master causing test failures”

SERVER-13839 [https://jira.mongodb.org/browse/SERVER-13839] Fixed sync2.js failure.

SERVER-13972 [https://jira.mongodb.org/browse/SERVER-13972] Fixed connections_opened.js failure.

SERVER-13712 [https://jira.mongodb.org/browse/SERVER-13712] Reduced peak disk usage of test suites.

SERVER-14249 [https://jira.mongodb.org/browse/SERVER-14249] Added tests for querying oplog via mongodump using --dbpath

SERVER-10462 [https://jira.mongodb.org/browse/SERVER-10462] Fixed: “Windows file locking related buildbot failures”

2.6.1 – Changes

Stability

SERVER-13739 [https://jira.mongodb.org/browse/SERVER-13739] Repair database failure can delete database files

Build and Packaging

SERVER-13287 [https://jira.mongodb.org/browse/SERVER-13287] Addition of debug symbols has doubled compile time

SERVER-13563 [https://jira.mongodb.org/browse/SERVER-13563] Upgrading from 2.4.x to 2.6.0 via yum clobbers configuration file

SERVER-13691 [https://jira.mongodb.org/browse/SERVER-13691] yum and apt “stable” repositories contain release candidate 2.6.1-rc0 packages

SERVER-13515 [https://jira.mongodb.org/browse/SERVER-13515] Cannot install MongoDB as a service on Windows

Querying

SERVER-13066 [https://jira.mongodb.org/browse/SERVER-13066] Negations over multikey fields do not use index

SERVER-13495 [https://jira.mongodb.org/browse/SERVER-13495] Concurrent GETMORE and KILLCURSORS operations can cause race condition and server crash

SERVER-13503 [https://jira.mongodb.org/browse/SERVER-13503] The $where operator should not be allowed under $elemMatch

SERVER-13537 [https://jira.mongodb.org/browse/SERVER-13537] Large skip and and limit values can cause crash in blocking sort stage

SERVER-13557 [https://jira.mongodb.org/browse/SERVER-13557] Incorrect negation of $elemMatch value in 2.6

SERVER-13562 [https://jira.mongodb.org/browse/SERVER-13562] Queries that use tailable cursors do not stream results if skip() is applied

SERVER-13566 [https://jira.mongodb.org/browse/SERVER-13566] Using the OplogReplay flag with extra predicates can yield incorrect results

SERVER-13611 [https://jira.mongodb.org/browse/SERVER-13611] Missing sort order for compound index leads to unnecessary in-memory sort

SERVER-13618 [https://jira.mongodb.org/browse/SERVER-13618] Optimization for sorted $in queries not applied to reverse sort order

SERVER-13661 [https://jira.mongodb.org/browse/SERVER-13661] Increase the maximum allowed depth of query objects

SERVER-13664 [https://jira.mongodb.org/browse/SERVER-13664] Query with $elemMatch using a compound multikey index can generate incorrect results

SERVER-13677 [https://jira.mongodb.org/browse/SERVER-13677] Query planner should traverse through $all while handling $elemMatch object predicates

SERVER-13766 [https://jira.mongodb.org/browse/SERVER-13766] Dropping index or collection while $or query is yielding triggers fatal assertion

Geospatial

SERVER-13666 [https://jira.mongodb.org/browse/SERVER-13666] $near queries with out-of-bounds points in legacy format can lead to crashes

SERVER-13540 [https://jira.mongodb.org/browse/SERVER-13540] The geoNear command no longer returns distance in radians for legacy point

SERVER-13486 [https://jira.mongodb.org/browse/SERVER-13486]: The geoNear command can create too large BSON objects for aggregation.

Replication

SERVER-13500 [https://jira.mongodb.org/browse/SERVER-13500] Changing replica set configuration can crash running members

SERVER-13589 [https://jira.mongodb.org/browse/SERVER-13589] Background index builds from a 2.6.0 primary fail to complete on 2.4.x secondaries

SERVER-13620 [https://jira.mongodb.org/browse/SERVER-13620] Replicated data definition commands will fail on secondaries during background index build

SERVER-13496 [https://jira.mongodb.org/browse/SERVER-13496] Creating index with same name but different spec in mixed version replicaset can abort replication

Sharding

SERVER-12638 [https://jira.mongodb.org/browse/SERVER-12638] Initial sharding with hashed shard key can result in duplicate split points

SERVER-13518 [https://jira.mongodb.org/browse/SERVER-13518] The _id field is no longer automatically generated by mongos when missing

SERVER-13777 [https://jira.mongodb.org/browse/SERVER-13777] Migrated ranges waiting for deletion do not report cursors still open

Security

SERVER-9358 [https://jira.mongodb.org/browse/SERVER-9358] Log rotation can overwrite previous log files

SERVER-13644 [https://jira.mongodb.org/browse/SERVER-13644] Sensitive credentials in startup options are not redacted and may be exposed

SERVER-13441 [https://jira.mongodb.org/browse/SERVER-13441] Inconsistent error handling in user management shell helpers

Write Operations

SERVER-13466 [https://jira.mongodb.org/browse/SERVER-13466] Error message in collection creation failure contains incorrect namespace

SERVER-13499 [https://jira.mongodb.org/browse/SERVER-13499] Yield policy for batch-inserts should be the same as for batch-updates/deletes

SERVER-13516 [https://jira.mongodb.org/browse/SERVER-13516] Array updates on documents with more than 128 BSON elements may crash mongod

Compatibility Changes in MongoDB 2.6

The following 2.6 changes can affect the compatibility with older versions of MongoDB. See Release Notes for MongoDB 2.6 for the full list of the 2.6 changes.

Index Changes

Enforce Index Key Length Limit

Description

MongoDB 2.6 implements a stronger enforcement of the limit on index key.

Creating indexes will error if an index key in an existing document exceeds the limit:

db.collection.ensureIndex(), db.collection.reIndex(), compact, and repairDatabase will error and not create the index. Previous versions of MongoDB would create the index but not index such documents.

Because db.collection.reIndex(), compact, and repairDatabase drop all the indexes from a collection and then recreate them sequentially, the error from the index key limit prevents these operations from rebuilding any remaining indexes for the collection and, in the case of the repairDatabase command, from continuing with the remainder of the process.

Inserts will error:

db.collection.insert() and other operations that perform inserts (e.g. db.collection.save() and db.collection.update() with upsert that result in inserts) will fail to insert if the new document has an indexed field whose corresponding index entry exceeds the limit. Previous versions of MongoDB would insert but not index such documents.

mongorestore and mongoimport will fail to insert if the new document has an indexed field whose corresponding index entry exceeds the limit.

Updates will error:

db.collection.update() and db.collection.save() operations on an indexed field will error if the updated value causes the index entry to exceed the limit.

If an existing document contains an indexed field whose index entry exceeds the limit, updates on other fields that result in the relocation of a document on disk will error.

Chunk Migration will fail:

Migrations will fail for a chunk that has a document with an indexed field whose index entry exceeds the limit.

If left unfixed, the chunk will repeatedly fail migration, effectively ceasing chunk balancing for that collection. Or, if chunk splits occur in response to the migration failures, this response would lead to unnecessarily large number of chunks and an overly large config databases.

Secondary members of replica sets will warn:

Secondaries will continue to replicate documents with an indexed field whose corresponding index entry exceeds the limit on initial sync but will print warnings in the logs.

Secondaries allow index build and rebuild operations on a collection that contains an indexed field whose corresponding index entry exceeds the limit but with warnings in the logs.

With mixed version replica sets where the secondaries are version 2.6 and the primary is version 2.4, secondaries will replicate documents inserted or updated on the 2.4 primary, but will print error messages in the log if the documents contain an indexed field whose corresponding index entry exceeds the limit.

Solution

Run db.upgradeCheckAllDBs() to find current keys that violate this limit and correct as appropriate. Preferably, run the test before upgrading; i.e. connect the 2.6 mongo shell to your MongoDB 2.4 database and run the method.

If you have an existing data set and want to disable the default index key length validation so that you can upgrade before resolving these indexing issues, use the failIndexKeyTooLong parameter.

Index Specifications Validate Field Names

Description

In MongoDB 2.6, create and re-index operations fail when the index key refers to an empty field, e.g. "a..b" : 1 or the field name starts with a dollar sign ($).

db.collection.ensureIndex() will not create a new index with an invalid or empty key name.

db.collection.reIndex(), compact, and repairDatabase will error if an index exists with an invalid or empty key name.

Chunk migration will fail if an index exists with an invalid or empty key name.

Previous versions of MongoDB allow the index.

Solution

Run db.upgradeCheckAllDBs() to find current keys that violate this limit and correct as appropriate. Preferably, run the test before upgrading; i.e. connect the 2.6 mongo shell to your MongoDB 2.4 database and run the method.

ensureIndex and Existing Indexes

Description

db.collection.ensureIndex() now errors:

if you try to create an existing index but with different options; e.g. in the following example, the second db.collection.ensureIndex() will error.

db.mycollection.ensureIndex( { x: 1 } )
db.mycollection.ensureIndex( { x: 1 }, { unique: 1 } )

if you specify an index name that already exists but the key specifications differ; e.g. in the following example, the second db.collection.ensureIndex() will error.

db.mycollection.ensureIndex( { a: 1 }, { name: "myIdx" } )
db.mycollection.ensureIndex( { z: 1 }, { name: "myIdx" } )

Previous versions did not create the index but did not error.

Write Method Acknowledgements

Description

The mongo shell write methods db.collection.insert(), db.collection.update(), db.collection.save() and db.collection.remove() now integrate the write concern directly into the method rather than with a separate getLastError command to provide safe writes whether run interactively in the mongo shell or non-interactively in a script. In previous versions, these methods exhibited a “fire-and-forget” behavior. [1]

Existing scripts for the mongo shell that used these methods will now observe safe writes which take longer than the previous “fire-and-forget” behavior.

The write methods now return a WriteResult object that contains the results of the operation, including any write errors and write concern errors, and obviates the need to call getLastError command to get the status of the results. See db.collection.insert(), db.collection.update(), db.collection.save() and db.collection.remove() for details.

In sharded environments, mongos no longer supports “fire-and-forget” behavior. This limits throughput when writing data to sharded clusters.

[1]
In previous versions, when using the mongo shell interactively, the mongo shell automatically called the getLastError command after a write method to provide “safe writes”. Scripts, however, would observe “fire-and-forget” behavior in previous versions unless the scripts included an explicit call to the getLastError command after a write method.

Solution

Scripts that used these mongo shell methods for bulk write operations with “fire-and-forget” behavior should use the Bulk() methods.

In sharded environments, applications using any driver or mongo shell should use Bulk() methods for optimal performance when inserting or modifying groups of documents.

For example, instead of:

for (var i = 1; i <= 1000000; i++) {
    db.test.insert( { x : i } );
}

In MongoDB 2.6, replace with Bulk() operation:

var bulk = db.test.initializeUnorderedBulkOp();

for (var i = 1; i <= 1000000; i++) {
    bulk.insert( { x : i} );
}

bulk.execute( { w: 1 } );

Bulk method returns a BulkWriteResult object that contains the result of the operation.

See also

New Write Operation Protocol, Bulk(), Bulk.execute(), db.collection.initializeUnorderedBulkOp(), db.collection.initializeOrderedBulkOp()

db.collection.aggregate() Change

Description

The db.collection.aggregate() method in the mongo shell defaults to returning a cursor to the results set. This change enables the aggregation pipeline to return result sets of any size and requires cursor iteration to access the result set. For example:

var myCursor = db.orders.aggregate( [
    {
      $group: {
         _id: "$cust_id",
         total: { $sum: "$price" }
      }
    }
] );

myCursor.forEach( function(x) { printjson (x); } );

Previous versions returned a single document with a field results that contained an array of the result set, subject to the BSON Document size limit. Accessing the result set in the previous versions of MongoDB required accessing the results field and iterating the array. For example:

var returnedDoc = db.orders.aggregate( [
    {
      $group: {
         _id: "$cust_id",
         total: { $sum: "$price" }
      }
    }
] );

var myArray = returnedDoc.result; // access the result field

myArray.forEach( function(x) { printjson (x); } );

Solution

Update scripts that currently expect db.collection.aggregate() to return a document with a results array to handle cursors instead.

See also

Aggregation Enhancements, db.collection.aggregate(),

Write Concern Validation

Description

Specifying a write concern that includes j: true to a mongod or mongos instance running with --nojournal option now errors. Previous versions would ignore the j: true.

Solution

Either remove the j: true specification from the write concern when issued against a mongod or mongos instance with --nojournal or run mongod or mongos with journaling.

Security Changes

New Authorization Model

Description

MongoDB 2.6 authorization model changes how MongoDB stores and manages user privilege information:

Before the upgrade, MongoDB 2.6 requires at least one user in the admin database.

MongoDB versions using older models cannot create/modify users or create user-defined roles.

Solution

Ensure that at least one user exists in the admin database. If no user exists in the admin database, add a user. Then upgrade to MongoDB 2.6. Finally, upgrade the user privilege model. See Upgrade MongoDB to 2.6.

Important

Before upgrading the authorization model, you should first upgrade MongoDB binaries to 2.6. For sharded clusters, ensure that all cluster components are 2.6. If there are users in any database, be sure you have at least one user in the admin database before upgrading the MongoDB binaries.

See also

Security Improvements

SSL Certificate Hostname Validation

Description

The SSL certificate validation now checks the Common Name (CN) and the Subject Alternative Name (SAN) fields to ensure that either the CN or one of the SAN entries matches the hostname of the server. As a result, if you currently use SSL and neither the CN nor any of the SAN entries of your current SSL certificates match the hostnames, upgrading to version 2.6 will cause the SSL connections to fail.

Solution

To allow for the continued use of these certificates, MongoDB provides the allowInvalidCertificates setting. The setting is available for:

mongod and mongos to bypass the validation of SSL certificates on other servers in the cluster.

mongo shell, MongoDB tools that support SSL, and the C++ driver to bypass the validation of server certificates.

When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificates.

Warning

The allowInvalidCertificates setting bypasses the other certificate validation, such as checks for expiration and valid signatures.

2dsphere Index Version 2

Description

MongoDB 2.6 introduces a version 2 of the 2dsphere index. If a document lacks a 2dsphere index field (or the field is null or an empty array), MongoDB does not add an entry for the document to the 2dsphere index. For inserts, MongoDB inserts the document but does not add to the 2dsphere index.

Previous version would not insert documents where the 2dsphere index field is a null or an empty array. For documents that lack the 2dsphere index field, previous versions would insert and index the document.

Solution

To revert to old behavior, create the 2dsphere index with { "2dsphereIndexVersion" : 1 } to create a version 1 index. However, version 1 index cannot use the new GeoJSON geometries.

See also

2dsphere Version 2

Log Messages

Timestamp Format Change

Description

Each message now starts with the timestamp format given in Time Format Changes. Previous versions used the ctime format.

Solution

MongoDB adds a new option --timeStampFormat which supports timestamp format in ctime, iso8601-utc, and iso8601-local (new default).

Package Configuration Changes

Default bindIp for RPM/DEB Packages

Description

In the official MongoDB packages in RPM (Red Hat, CentOS, Fedora Linux, and derivatives) and DEB (Debian, Ubuntu, and derivatives), the default bindIp value attaches MongoDB components to the localhost interface only. These packages set this default in the default configuration file (i.e. /etc/mongodb.conf.)

Solution

If you use one of these packages and have not modified the default /etc/mongodb.conf file, you will need to set bindIp before or during the upgrade.

There is no default bindIp setting in any other official MongoDB packages.

SNMP Changes

Description

The IANA enterprise identifier for MongoDB changed from 37601 to 34601.

MongoDB changed the MIB field name globalopcounts to globalOpcounts.

Solution

Users of SNMP monitoring must modify their SNMP configuration (i.e. MIB) from 37601 to 34601.

Update references to globalopcounts to globalOpcounts.

Remove Method Signature Change

Description

db.collection.remove() requires a query document as a parameter. In previous versions, the method invocation without a query document deleted all documents in a collection.

Solution

For existing db.collection.remove() invocations without a query document, modify the invocations to include an empty document db.collection.remove({}).

Update Operator Syntax Validation

Description

Update operators (e.g $set) must specify a non-empty operand expression. For example, the following expression is now invalid:

{ $set: { } }

Update operators (e.g $set) cannot repeat in the update statement. For example, the following expression is invalid:

{ $set: { a: 5 }, $set: { b: 5 } }

Updates Enforce Field Name Restrictions

Description

Updates cannot use update operators (e.g $set) to target fields with empty field names (i.e. "").

Updates no longer support saving field names that contain a dot (.) or a field name that starts with a dollar sign ($).

Solution

For existing documents that have fields with empty names "", replace the whole document. See db.collection.update() and db.collection.save() for details on replacing an existing document.

For existing documents that have fields with names that contain a dot (.), either replace the whole document or unset the field. To find fields whose names contain a dot, run db.upgradeCheckAllDBs().

For existing documents that have fields with names that start with a dollar sign ($), unset or rename those fields. To find fields whose names start with a dollar sign, run db.upgradeCheckAllDBs().

See New Write Operation Protocol for the changes to the write operation protocol, and Insert and Update Improvements for the changes to the insert and update operations. Also consider the documentation of the Restrictions on Field Names.

Query and Sort Changes

Enforce Field Name Restrictions

Description

Queries cannot specify conditions on fields with names that start with a dollar sign ($).

Solution

Unset or rename existing fields whose names start with a dollar sign ($). Run db.upgradeCheckAllDBs() to find fields whose names start with a dollar sign.

Sparse Index and Incomplete Results

Description

If a sparse index results in an incomplete result set for queries and sort operations, MongoDB will not use that index unless a hint() explicitly specifies the index.

For example, the query { x: { $exists: false } } will no longer use a sparse index on the x field, unless explicitly hinted.

Solution

To override the behavior to use the sparse index and return incomplete results, explicitly specify the index with a hint().

See Sparse Index On A Collection Cannot Return Complete Results for an example that details the new behavior.

sort() Specification Values

Description

The sort() method only accepts the following values for the sort keys:

1 to specify ascending order for a field,

-1 to specify descending order for a field, or

$meta expression to specify sort by the text search score.

Any other value will result in an error.

Previous versions also accepted either true or false for ascending.

Solution

Update sort key values that use true or false to 1.

skip() and _id Queries

Description

Equality match on the _id field obeys skip().

Previous versions ignored skip() when performing an equality match on the _id field.

explain() Retains Query Plan Cache

Description

explain() no longer clears the query plans cached for that query shape.

In previous versions, explain() would have the side effect of clearing the query plan cache for that query shape.

See also

The PlanCache() reference.

Geospatial Changes

$maxDistance Changes

Description

For $near queries on GeoJSON data, if the queries specify a $maxDistance, $maxDistance must be inside of the $near document.

In previous version, $maxDistance could be either inside or outside the $near document.

$maxDistance must be a positive value.

Solution

Update any existing $near queries on GeoJSON data that currently have the $maxDistance outside the $near document

Update any existing queries where $maxDistance is a negative value.

Deprecated $uniqueDocs

Description

MongoDB 2.6 deprecates $uniqueDocs, and geospatial queries no longer return duplicated results when a document matches the query multiple times.

Stronger Validation of Geospatial Queries

Description

MongoDB 2.6 enforces a stronger validation of geospatial queries, such as validating the options or GeoJSON specifications, and errors if the geospatial query is invalid. Previous versions allowed/ignored invalid options.

Query Operator Changes

$not Query Behavior Changes

Description

Queries with $not expressions on an indexed field now match:

Documents that are missing the indexed field. Previous versions would not return these documents using the index.

Documents whose indexed field value is a different type than that of the specified value. Previous versions would not return these documents using the index.

For example, if a collection orders contains the following documents:

{ _id: 1, status: "A", cust_id: "123", price: 40 }
{ _id: 2, status: "A", cust_id: "xyz", price: "N/A" }
{ _id: 3, status: "D", cust_id: "xyz" }

If the collection has an index on the price field:

db.orders.ensureIndex( { price: 1 } )

The following query uses the index to search for documents where price is not greater than or equal to 50:

db.orders.find( { price: { $not: { $gte: 50 } } } )

In 2.6, the query returns the following documents:

{ "_id" : 3, "status" : "D", "cust_id" : "xyz" }
{ "_id" : 1, "status" : "A", "cust_id" : "123", "price" : 40 }
{ "_id" : 2, "status" : "A", "cust_id" : "xyz", "price" : "N/A" }

In previous versions, indexed plans would only return matching documents where the type of the field matches the type of the query predicate:

{ "_id" : 1, "status" : "A", "cust_id" : "123", "price" : 40 }

If using a collection scan, previous versions would return the same results as those in 2.6.

MongoDB 2.6 allows chaining of $not expressions.

null Comparison Queries

Description

$lt and $gt comparisons to null no longer match documents that are missing the field.

null equality conditions on array elements (e.g. "a.b": null) no longer match document missing the nested field a.b (e.g. a: [ 2, 3 ]).

null equality queries (i.e. field: null ) now match fields with values undefined.

$all Operator Behavior Change

Description

The $all operator is now equivalent to an $and operation of the specified values. This change in behavior can allow for more matches than previous versions when passed an array of a single nested array (e.g. [ [ "A" ] ]). When passed an array of a nested array, $all can now match documents where the field contains the nested array as an element (e.g. field: [ [ "A" ], ... ]), or the field equals the nested array (e.g. field: [ "A", "B" ]). Earlier version could only match documents where the field contains the nested array.

The $all operator returns no match if the array field contains nested arrays (e.g. field: [ "a", ["b"] ]) and $all on the nested field is the element of the nested array (e.g. "field.1": { $all: [ "b" ] }). Previous versions would return a match.

$mod Operator Enforces Strict Syntax

Description

The $mod operator now only accepts an array with exactly two elements, and errors when passed an array with fewer or more elements. See Not Enough Elements Error and Too Many Elements Error for details.

In previous versions, if passed an array with one element, the $mod operator uses 0 as the second element, and if passed an array with more than two elements, the $mod ignores all but the first two elements. Previous versions do return an error when passed an empty array.

Solution

Ensure that the array passed to $mod contains exactly two elements:

If the array contains the a single element, add 0 as the second element.

If the array contains more than two elements, remove the extra elements.

$where Must Be Top-Level

Description

$where expressions can now only be at top level and cannot be nested within another expression, such as $elemMatch.

Solution

Update existing queries that nest $where.

$exists and notablescan

If the MongoDB server has disabled collection scans, i.e. notablescan, then $exists queries that have no indexed solution will error.

MinKey and MaxKey Queries

Description

Equality match for either MinKey or MaxKey no longer match documents missing the field.

Nested Array Queries with $elemMatch

Description

The $elemMatch query operator no longer traverses recursively into nested arrays.

For example, if a collection test contains the following document:

{ "_id": 1, "a" : [ [ 1, 2, 5 ] ] }

In 2.6, the following $elemMatch query does not match the document:

db.test.find( { a: { $elemMatch: { $gt: 1, $lt: 5 } } } )

Solution

Update existing queries that rely upon the old behavior.

Text Search Compatibility

MongoDB does not support the use of the $text query operator in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards. See Upgrade MongoDB to 2.6 for upgrade instructions.

Replica Set/Sharded Cluster Validation

Shard Name Checks on Metadata Refresh

Description

For sharded clusters, MongoDB 2.6 disallows a shard from refreshing the metadata if the shard name has not been explicitly set.

For mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards, this change can cause errors when migrating chunks from version 2.4 shards to version 2.6 shards if the shard name is unknown to the version 2.6 shards. MongoDB does not support migrations in mixed sharded cluster deployments.

Solution

Upgrade all components of the cluster to 2.6. See Upgrade MongoDB to 2.6.

Replica Set Vote Configuration Validation

Description

MongoDB now deprecates giving any replica set member more than a single vote. During configuration, local.system.replset.members[n].votes should only have a value of 1 for voting members and 0 for non-voting members. MongoDB treats values other than 1 or 0 as a value of 1 and produces a warning message.

Solution

Update local.system.replset.members[n].votes with values other than 1 or 0 to 1 or 0 as appropriate.

Time Format Changes

MongoDB now uses iso8601-local when formatting time data in many outputs. This format follows the template YYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>. For example, 2014-03-04T20:13:38.944-0500.

This change impacts all clients using Extended JSON in Strict mode, such as mongoexport and the REST and HTTP Interfaces [http://docs.mongodb.org/ecosystem/tools/http-interfaces].

Other Resources

All backwards incompatible changes (JIRA) [https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20fixVersion%20in%20(%222.5.0%22%2C%20%222.5.1%22%2C%20%222.5.2%22%2C%20%222.5.3%22%2C%20%222.5.4%22%2C%20%222.5.5%22%2C%20%222.6.0-rc1%22%2C%20%222.6.0-rc2%22)%20AND%20%22Backwards%20Compatibility%22%20in%20%20(%22Major%20Change%22%2C%20%22Minor%20Change%22)%20ORDER%20BY%20votes%20DESC%2C%20issuetype%20DESC%2C%20key%20DESC].

Release Notes for MongoDB 2.6.

Upgrade MongoDB to 2.6 for the upgrade process.

Upgrade MongoDB to 2.6

In the general case, the upgrade from MongoDB 2.4 to 2.6 is a binary-compatible “drop-in” upgrade: shut down the mongod instances and replace them with mongod instances running 2.6. However, before you attempt any upgrade, familiarize yourself with the content of this document, particularly the Upgrade Recommendations and Checklists, the procedure for upgrading sharded clusters, and the considerations for reverting to 2.4 after running 2.6.

Upgrade Recommendations and Checklists

When upgrading, consider the following:

Upgrade Requirements

To upgrade an existing MongoDB deployment to 2.6, you must be running 2.4. If you’re running a version of MongoDB before 2.4, you must upgrade to 2.4 before upgrading to 2.6. See Upgrade MongoDB to 2.4 for the procedure to upgrade from 2.2 to 2.4.

If you use MMS Backup, ensure that you’re running at least version v20131216.1 of the Backup agent before upgrading. Version 1.4.0 of the backup agent followed v20131216.1

Preparedness

Before upgrading MongoDB always test your application in a staging environment before deploying the upgrade to your production environment.

To begin the upgrade procedure, connect a 2.6 mongo shell to your MongoDB 2.4 mongos or mongod and run the db.upgradeCheckAllDBs() to check your data set for compatibility. This is a preliminary automated check. Assess and resolve all issues identified by db.upgradeCheckAllDBs().

Some changes in MongoDB 2.6 require manual checks and intervention. See Compatibility Changes in MongoDB 2.6 for an explanation of these changes. Resolve all incompatibilities in your deployment before continuing.

Authentication

MongoDB 2.6 includes significant changes to the authorization model, which requires changes to the way that MongoDB stores users’ credentials. As a result, in addition to upgrading MongoDB processes, if your deployment uses authentication and authorization, after upgrading all MongoDB process to 2.6 you must also upgrade the authorization model.

After you begin to upgrade a MongoDB deployment that uses authentication to 2.6, you cannot modify existing user data until you complete the authorization user schema upgrade.

Before beginning the upgrade process for a deployment that uses authentication and authorization:

Ensure that at least one user exists in the admin database.

If your application performs CRUD operations on the <database>.system.users collection or uses a db.addUser()-like method, then you must upgrade those drivers (i.e. client libraries) before mongod or mongos instances.

You must fully complete the upgrade procedure for all MongoDB processes before upgrading the authorization model.

See Upgrade User Authorization Data to 2.6 Format for a complete discussion of the upgrade procedure for the authorization model including additional requirements and procedures.

Downgrade Limitations

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you created text or 2dsphere indexes while running 2.6, you can only downgrade to MongoDB 2.4.10 or later.

Package Upgrades

If you installed MongoDB from the MongoDB apt or yum repositories, upgrade to 2.6 using the package manager.

For Debian, Ubuntu, and related operating systems, type these commands:

sudo apt-get update
sudo apt-get install mongodb-org

For Red Hat Enterprise, CentOS, Fedora, or Amazon Linux:

sudo yum install mongodb-org

If you did not install the mongodb-org package, and installed a subset of MongoDB components replace mongodb-org in the commands above with the appropriate package names.

See installation instructions for Ubuntu, RHEL, Debian, or other Linux Systems for a list of the available packages and complete MongoDB installation instructions.

Upgrade MongoDB Processes

Upgrade Standalone mongod Instance to MongoDB 2.6

The following steps outline the procedure to upgrade a standalone mongod from version 2.4 to 2.6. To upgrade from version 2.2 to 2.6, upgrade to version 2.4 first, and then follow the procedure to upgrade from 2.4 to 2.6.

Download binaries of the latest release in the 2.6 series from the MongoDB Download Page [http://www.mongodb.org/downloads]. See Install MongoDB for more information.

Shut down your mongod instance. Replace the existing binary with the 2.6 mongod binary and restart mongod.

Upgrade a Replica Set to 2.6

The following steps outline the procedure to upgrade a replica set from MongoDB 2.4 to MongoDB 2.6. To upgrade from MongoDB 2.2 to 2.6, upgrade all members of the replica set to version 2.4 first, and then follow the procedure to upgrade from MongoDB 2.4 to 2.6.

You can upgrade from MongoDB 2.4 to 2.6 using a “rolling” upgrade to minimize downtime by upgrading the members individually while the other members are available:

1

Upgrade secondary members of the replica set.

Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.4 binary with the 2.6 binary. After upgrading a mongod instance, wait for the member to recover to SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

Step 1: Upgrade secondary members of the replica set.

Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.4 binary with the 2.6 binary. After upgrading a mongod instance, wait for the member to recover to SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

2

Step down the replica set primary.

Use rs.stepDown() in the mongo shell to step down the primary and force the set to failover. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.

Step 2: Step down the replica set primary.

Use rs.stepDown() in the mongo shell to step down the primary and force the set to failover. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.

3

Upgrade the primary.

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, shut down the previous primary and replace the mongod binary with the 2.6 binary and start the new instance.

Step 3: Upgrade the primary.

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, shut down the previous primary and replace the mongod binary with the 2.6 binary and start the new instance.

Replica set failover is not instant but will render the set unavailable accept writes until the failover process completes. Typically this takes 30 seconds or more: schedule the upgrade procedure during a scheduled maintenance window.

Upgrade a Sharded Cluster to 2.6

Only upgrade sharded clusters to 2.6 if all members of the cluster are currently running instances of 2.4. The only supported upgrade path for sharded clusters running 2.2 is via 2.4. The upgrade process checks all components of the cluster and will produce warnings if any component is running version 2.2.

Considerations

The upgrade process does not require any downtime. However, while you upgrade the sharded cluster, ensure that clients do not make changes to the collection meta-data. For example, during the upgrade, do not do any of the following:

sh.enableSharding()

sh.shardCollection()

sh.addShard()

db.createCollection()

db.collection.drop()

db.dropDatabase()

any operation that creates a database

any other operation that modifies the cluster metadata in any way. See Sharding Reference for a complete list of sharding commands. Note, however, that not all commands on the Sharding Reference page modifies the cluster meta-data.

Upgrade Sharded Clusters

Optional but Recommended. As a precaution, take a backup of the config database before upgrading the sharded cluster.

1

Disable the Balancer.

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

Step 1: Disable the Balancer.

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

2

Upgrade the cluster’s meta data.

Start a single 2.6 mongos instance with the configDB pointing to the cluster’s config servers and with the --upgrade option.

To run a mongos with the --upgrade option, you can upgrade an existing mongos instance to 2.6, or if you need to avoid reconfiguring a production mongos instance, you can use a new 2.6 mongos that can reach all the config servers.

To upgrade the meta data, run:

mongos --configdb <configDB string> --upgrade

You can include the --logpath option to output the log messages to a file instead of the standard output. Also include any other options required to start mongos instances in your cluster, such as --sslOnNormalPorts or --sslPEMKeyFile.

The mongos will exit upon completion of the --upgrade process.

The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If the data files have many sharded collections or if failed processes hold stale locks, acquiring the locks for all collections can take seconds or minutes. Watch the log for progress updates.

Step 2: Upgrade the cluster’s meta data.

Start a single 2.6 mongos instance with the configDB pointing to the cluster’s config servers and with the --upgrade option.

To run a mongos with the --upgrade option, you can upgrade an existing mongos instance to 2.6, or if you need to avoid reconfiguring a production mongos instance, you can use a new 2.6 mongos that can reach all the config servers.

To upgrade the meta data, run:

mongos --configdb <configDB string> --upgrade

You can include the --logpath option to output the log messages to a file instead of the standard output. Also include any other options required to start mongos instances in your cluster, such as --sslOnNormalPorts or --sslPEMKeyFile.

The mongos will exit upon completion of the --upgrade process.

The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If the data files have many sharded collections or if failed processes hold stale locks, acquiring the locks for all collections can take seconds or minutes. Watch the log for progress updates.

3

Ensure mongos --upgrade process completes successfully.

The mongos will exit upon completion of the meta data upgrade process. If successful, the process will log the following messages:

upgrade of config server to v5 successful
Config database is at version v5

After a successful upgrade, restart the mongos instance. If mongos fails to start, check the log for more information.

If the mongos instance loses its connection to the config servers during the upgrade or if the upgrade is otherwise unsuccessful, you may always safely retry the upgrade.

Step 3: Ensure mongos --upgrade process completes successfully.

The mongos will exit upon completion of the meta data upgrade process. If successful, the process will log the following messages:

upgrade of config server to v5 successful
Config database is at version v5

After a successful upgrade, restart the mongos instance. If mongos fails to start, check the log for more information.

If the mongos instance loses its connection to the config servers during the upgrade or if the upgrade is otherwise unsuccessful, you may always safely retry the upgrade.

4

Upgrade the remaining mongos instances to v2.6.

Upgrade and restart without the --upgrade option the other mongos instances in the sharded cluster. After upgrading all the mongos, see Complete Sharded Cluster Upgrade for information on upgrading the other cluster components.

Step 4: Upgrade the remaining mongos instances to v2.6.

Upgrade and restart without the --upgrade option the other mongos instances in the sharded cluster. After upgrading all the mongos, see Complete Sharded Cluster Upgrade for information on upgrading the other cluster components.

Complete Sharded Cluster Upgrade

After you have successfully upgraded all mongos instances, you can upgrade the other instances in your MongoDB deployment.

Warning

Do not upgrade mongod instances until after you have upgraded all mongos instances.

While the balancer is still disabled, upgrade the components of your sharded cluster in the following order:

Upgrade all 3 mongod config server instances, leaving the first system in the mongos --configdb argument to upgrade last.

Upgrade each shard, one at a time, upgrading the mongod secondaries before running replSetStepDown and upgrading the primary of each shard.

When this process is complete, re-enable the balancer.

Upgrade Procedure

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you have text or 2dsphere indexes, you can only downgrade to MongoDB 2.4.10 or later.

Except as described on this page, moving between 2.4 and 2.6 is a drop-in replacement:

1

Stop the existing mongod instance.

For example, on Linux, run 2.4 mongod with the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.

Step 1: Stop the existing mongod instance.

For example, on Linux, run 2.4 mongod with the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.

2

Start the new mongod instance.

Ensure you start the 2.6 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Step 2: Start the new mongod instance.

Ensure you start the 2.6 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Upgrade User Authorization Data to 2.6 Format

MongoDB 2.6 includes significant changes to the authorization model, which requires changes to the way that MongoDB stores users’ credentials. As a result, in addition to upgrading MongoDB processes, if your deployment uses authentication and authorization, after upgrading all MongoDB process to 2.6 you must also upgrade the authorization model.

Considerations

Complete all other Upgrade Requirements

Before upgrading the authorization model, you should first upgrade MongoDB binaries to 2.6. For sharded clusters, ensure that all cluster components are 2.6. If there are users in any database, be sure you have at least one user in the admin database before upgrading the MongoDB binaries.

Timing

Because downgrades are more difficult after you upgrade the user authorization model, once you upgrade the MongoDB binaries to version 2.6, allow your MongoDB deployment to run a day or two without upgrading the user authorization model.

This allows 2.6 some time to “burn in” and decreases the likelihood of downgrades occurring after the user privilege model upgrade. The user authentication and access control will continue to work as it did in 2.4, but it will be impossible to create or modify users or to use user-defined roles until you run the authorization upgrade.

If you decide to upgrade the user authorization model immediately instead of waiting the recommended “burn in” period, then for sharded clusters, you must wait at least 10 seconds after upgrading the sharded clusters to run the authorization upgrade script.

Replica Sets

For a replica set, it is only necessary to run the upgrade process on the primary as the changes will automatically replicate to the secondaries.

Sharded Clusters

For a sharded cluster, connect to a mongos and run the upgrade procedure to upgrade the cluster’s authorization data. By default, the procedure will upgrade the authorization data of the shards as well.

To override this behavior, run the upgrade command with the additional parameter upgradeShards: false. If you choose to override, you must run the upgrade procedure on the mongos first, and then run the procedure on the primary members of each shard.

For a sharded cluster, do not run the upgrade process directly against the config servers. Instead, perform the upgrade process using one mongos instance to interact with the config database.

Requirements

To upgrade the authorization model, you must have a user in the admin database with the role userAdminAnyDatabase.

Procedure

1

Connect to MongoDB instance.

Connect and authenticate to the mongod instance for a single deployment or a mongos for a sharded cluster as an admin database user with the role userAdminAnyDatabase.

Step 1: Connect to MongoDB instance.

Connect and authenticate to the mongod instance for a single deployment or a mongos for a sharded cluster as an admin database user with the role userAdminAnyDatabase.

2

Upgrade authorization schema.

Use the authSchemaUpgrade command in the admin database to update the user data using the mongo shell.

Run authSchemaUpgrade command.

db.getSiblingDB("admin").runCommand({authSchemaUpgrade: 1 });

In case of error, you may safely rerun the authSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

For a sharded cluster, authSchemaUpgrade will upgrade the authorization data of the shards as well and the upgrade is complete. You can, however, override this behavior by including upgradeShards: false in the command, as in the following example:

db.getSiblingDB("admin").runCommand({authSchemaUpgrade: 1,
upgradeShards: false });

If you override the behavior, after running authSchemaUpgrade on a mongos instance, you will need to connect to the primary for each shard and repeat the upgrade process after upgrading on the mongos.

Step 2: Upgrade authorization schema.

Use the authSchemaUpgrade command in the admin database to update the user data using the mongo shell.

Run authSchemaUpgrade command.

db.getSiblingDB("admin").runCommand({authSchemaUpgrade: 1 });

In case of error, you may safely rerun the authSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

For a sharded cluster, authSchemaUpgrade will upgrade the authorization data of the shards as well and the upgrade is complete. You can, however, override this behavior by including upgradeShards: false in the command, as in the following example:

db.getSiblingDB("admin").runCommand({authSchemaUpgrade: 1,
upgradeShards: false });

If you override the behavior, after running authSchemaUpgrade on a mongos instance, you will need to connect to the primary for each shard and repeat the upgrade process after upgrading on the mongos.

Result

All users in a 2.6 system are stored in the admin.system.users collection. To manipulate these users, use the user management methods.

The upgrade procedure copies the version 2.4 admin.system.users collection to admin.system.backup_users.

The upgrade procedure leaves the version 2.4 <database>.system.users collection(s) intact.

Downgrade MongoDB from 2.6

Before you attempt any downgrade, familiarize yourself with the content of this document, particularly the Downgrade Recommendations and Checklist and the procedure for downgrading sharded clusters.

Downgrade Recommendations and Checklist

When downgrading, consider the following:

Downgrade Path

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you created text or 2dsphere indexes while running 2.6, you can only downgrade to MongoDB 2.4.10 or later.

Preparedness

Remove or downgrade version 2 text indexes before downgrading MongoDB 2.6 to 2.4.

Remove or downgrade version 2 2dsphere indexes before downgrading MongoDB 2.6 to 2.4.

Downgrade 2.6 User Authorization Model. If you have upgraded to the 2.6 user authorization model, you must downgrade the user model to 2.4 before downgrading MongoDB 2.6 to 2.4.

Procedures

Follow the downgrade procedures:

To downgrade sharded clusters, see Downgrade a 2.6 Sharded Cluster.

To downgrade replica sets, see Downgrade a 2.6 Replica Set.

To downgrade a standalone MongoDB instance, see Downgrade 2.6 Standalone mongod Instance.

Downgrade 2.6 User Authorization Model

If you have upgraded to the 2.6 user authorization model, you must first downgrade the user authorization model to 2.4 before before downgrading MongoDB 2.6 to 2.4.

Considerations

For a replica set, it is only necessary to run the downgrade process on the primary as the changes will automatically replicate to the secondaries.

For sharded clusters, although the procedure lists the downgrade of the cluster’s authorization data first, you may downgrade the authorization data of the cluster or shards first.

You must have the admin.system.backup_users and admin.system.new_users collections created during the upgrade process.

Important. The downgrade process returns the user data to its state prior to upgrading to 2.6 authorization model. Any changes made to the user/role data using the 2.6 users model will be lost.

Access Control Prerequisites

To downgrade the authorization model, you must connect as a user with the following privileges:

{ resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] }
{ resource: { db: "admin", collection: "system.backup_users" }, actions: [  "find" ] }
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] }
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }

If no user exists with the appropriate privileges, create an authorization model downgrade user:

1

Connect as user with privileges to manage users and roles.

Connect and authenticate as a user with userAdminAnyDatabase.

Step 1: Connect as user with privileges to manage users and roles.

Connect and authenticate as a user with userAdminAnyDatabase.

2

Create a role with required privileges.

Using the db.createRole method, create a role with the required privileges.

use admin
db.createRole(
  {
    role: "downgradeAuthRole",
    privileges: [
      { resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] },
      { resource: { db: "admin", collection: "system.backup_users" }, actions: [  "find" ] },
      { resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] },
      { resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }
    ],
    roles: [ ]
  }
)

Step 2: Create a role with required privileges.

Using the db.createRole method, create a role with the required privileges.

use admin
db.createRole(
  {
    role: "downgradeAuthRole",
    privileges: [
      { resource: { db: "admin", collection: "system.new_users" }, actions: [ "find", "insert", "update" ] },
      { resource: { db: "admin", collection: "system.backup_users" }, actions: [  "find" ] },
      { resource: { db: "admin", collection: "system.users" }, actions: [ "find", "remove", "insert"] },
      { resource: { db: "admin", collection: "system.version" }, actions: [ "find", "update" ] }
    ],
    roles: [ ]
  }
)

3

Create a user with the new role.

Create a user and assign the user the downgradeRole.

use admin
db.createUser(
   {
     user: "downgradeAuthUser",
     pwd: "somePass123",
     roles: [ { role: "downgradeAuthRole", db: "admin" } ]
   }
)

Note

Instead of creating a new user, you can also grant the role to an existing user. See db.grantRolesToUser() method.

Step 3: Create a user with the new role.

Create a user and assign the user the downgradeRole.

use admin
db.createUser(
   {
     user: "downgradeAuthUser",
     pwd: "somePass123",
     roles: [ { role: "downgradeAuthRole", db: "admin" } ]
   }
)

Note

Instead of creating a new user, you can also grant the role to an existing user. See db.grantRolesToUser() method.

4

Authenticate as the new user.

Authenticate as the newly created user.

use admin
db.auth( "downgradeAuthUser", "somePass123" )

The method returns 1 upon successful authentication.

Step 4: Authenticate as the new user.

Authenticate as the newly created user.

use admin
db.auth( "downgradeAuthUser", "somePass123" )

The method returns 1 upon successful authentication.

Procedure

The following downgrade procedure requires <database>.system.users collections used in version 2.4. to be intact for non-admin databases.

1

Connect and authenticate to MongoDB instance.

Connect and authenticate to the mongod instance for a single deployment or a mongos for a sharded cluster with the appropriate privileges. See Access Control Prerequisites for details.

Step 1: Connect and authenticate to MongoDB instance.

Connect and authenticate to the mongod instance for a single deployment or a mongos for a sharded cluster with the appropriate privileges. See Access Control Prerequisites for details.

2

Create backup of 2.6 admin.system.users collection.

Copy all documents in the admin.system.users collection to the admin.system.new_users collection:

db.getSiblingDB("admin").system.users.find().forEach( function(userDoc) {
    status = db.getSiblingDB("admin").system.new_users.save( userDoc );
    if (status.hasWriteError()) {
        print(status.writeError);
    }
  }
);

Step 2: Create backup of 2.6 admin.system.users collection.

Copy all documents in the admin.system.users collection to the admin.system.new_users collection:

db.getSiblingDB("admin").system.users.find().forEach( function(userDoc) {
    status = db.getSiblingDB("admin").system.new_users.save( userDoc );
    if (status.hasWriteError()) {
        print(status.writeError);
    }
  }
);

3

Update the version document for the authSchema.

db.getSiblingDB("admin").system.version.update(
   { _id: "authSchema" },
   { $set: { currentVersion: 2 } }
);

The method returns a WriteResult object with the status of the operation. Upon successful update, the WriteResult object should have "nModified" equal to 1.

Step 3: Update the version document for the authSchema.

db.getSiblingDB("admin").system.version.update(
   { _id: "authSchema" },
   { $set: { currentVersion: 2 } }
);

The method returns a WriteResult object with the status of the operation. Upon successful update, the WriteResult object should have "nModified" equal to 1.

4

Remove existing documents from the admin.system.users collection.

db.getSiblingDB("admin").system.users.remove( {} )

The method returns a WriteResult object with the number of documents removed in the "nRemoved" field.

Step 4: Remove existing documents from the admin.system.users collection.

db.getSiblingDB("admin").system.users.remove( {} )

The method returns a WriteResult object with the number of documents removed in the "nRemoved" field.

5

Copy documents from the admin.system.backup_users collection.

Copy all documents from the admin.system.backup_users, created during the 2.6 upgrade, to admin.system.users.

db.getSiblingDB("admin").system.backup_users.find().forEach(
   function (userDoc) {
      status = db.getSiblingDB("admin").system.users.insert( userDoc );
      if (status.hasWriteError()) {
          print(status.writeError);
      }
   }
);

Step 5: Copy documents from the admin.system.backup_users collection.

Copy all documents from the admin.system.backup_users, created during the 2.6 upgrade, to admin.system.users.

db.getSiblingDB("admin").system.backup_users.find().forEach(
   function (userDoc) {
      status = db.getSiblingDB("admin").system.users.insert( userDoc );
      if (status.hasWriteError()) {
          print(status.writeError);
      }
   }
);

6

Update the version document for the authSchema.

db.getSiblingDB("admin").system.version.update(
   { _id: "authSchema" },
   { $set: { currentVersion: 1 } }
)

Step 6: Update the version document for the authSchema.

db.getSiblingDB("admin").system.version.update(
   { _id: "authSchema" },
   { $set: { currentVersion: 1 } }
)

For a sharded cluster, repeat the downgrade process by connecting to the primary replica set member for each shard.

Note

The cluster’s mongos instances will fail to detect the authorization model downgrade until the user cache is refreshed. You can run invalidateUserCache on each mongos instance to refresh immediately, or you can wait until the cache is refreshed automatically at the end of the user cache invalidation interval. To run invalidateUserCache, you must have privilege with invalidateUserCache action, which is granted by userAdminAnyDatabase and hostManager roles.

Result

The downgrade process returns the user data to its state prior to upgrading to 2.6 authorization model. Any changes made to the user/role data using the 2.6 users model will be lost.

Downgrade Updated Indexes

Text Index Version Check

If you have version 2 text indexes (i.e. the default version for text indexes in MongoDB 2.6), drop the version 2 text indexes before downgrading MongoDB. After the downgrade, enable text search and recreate the dropped text indexes.

To determine the version of your text indexes, run db.collection.getIndexes() to view index specifications. For text indexes, the method returns the version information in the field textIndexVersion. For example, the following shows that the text index on the quotes collection is version 2.

{
   "v" : 1,
   "key" : {
      "_fts" : "text",
      "_ftsx" : 1
   },
   "name" : "quote_text_translation.quote_text",
   "ns" : "test.quotes",
   "weights" : {
      "quote" : 1,
      "translation.quote" : 1
   },
   "default_language" : "english",
   "language_override" : "language",
   "textIndexVersion" : 2
}

2dsphere Index Version Check

If you have version 2 2dsphere indexes (i.e. the default version for 2dsphere indexes in MongoDB 2.6), drop the version 2 2dsphere indexes before downgrading MongoDB. After the downgrade, recreate the 2dsphere indexes.

To determine the version of your 2dsphere indexes, run db.collection.getIndexes() to view index specifications. For 2dsphere indexes, the method returns the version information in the field 2dsphereIndexVersion. For example, the following shows that the 2dsphere index on the locations collection is version 2.

{
   "v" : 1,
   "key" : {
      "geo" : "2dsphere"
   },
   "name" : "geo_2dsphere",
   "ns" : "test.locations",
   "sparse" : true,
   "2dsphereIndexVersion" : 2
}

Downgrade MongoDB Processes

Downgrade 2.6 Standalone mongod Instance

The following steps outline the procedure to downgrade a standalone mongod from version 2.6 to 2.4.

Download binaries of the latest release in the 2.4 series from the MongoDB Download Page [http://www.mongodb.org/downloads]. See Install MongoDB for more information.

Shut down your mongod instance. Replace the existing binary with the 2.4 mongod binary and restart mongod.

Downgrade a 2.6 Replica Set

The following steps outline a “rolling” downgrade process for the replica set. The “rolling” downgrade process minimizes downtime by downgrading the members individually while the other members are available:

1

Downgrade each secondary member, one at a time.

For each secondary in a replica set:

Replace and restart secondary mongod instances.

First, shut down the mongod, then replace these binaries with the 2.4 binary and restart mongod. See Stop mongod Processes for instructions on safely terminating mongod processes.

Allow secondary to recover.

Wait for the member to recover to SECONDARY state before upgrading the next secondary.

To check the member’s state, use the rs.status() method in the mongo shell.

Step 1: Downgrade each secondary member, one at a time.

For each secondary in a replica set:

Replace and restart secondary mongod instances.

First, shut down the mongod, then replace these binaries with the 2.4 binary and restart mongod. See Stop mongod Processes for instructions on safely terminating mongod processes.

Allow secondary to recover.

Wait for the member to recover to SECONDARY state before upgrading the next secondary.

To check the member’s state, use the rs.status() method in the mongo shell.

2

Step down the primary.

Use rs.stepDown() in the mongo shell to step down the primary and force the normal failover procedure.

rs.stepDown()

rs.stepDown() expedites the failover procedure and is

preferable to shutting down the primary directly.

Step 2: Step down the primary.

Use rs.stepDown() in the mongo shell to step down the primary and force the normal failover procedure.

rs.stepDown()

rs.stepDown() expedites the failover procedure and is

preferable to shutting down the primary directly.

3

Replace and restart former primary mongod.

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, shut down the previous primary and replace the mongod binary with the 2.4 binary and start the new instance.

Step 3: Replace and restart former primary mongod.

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, shut down the previous primary and replace the mongod binary with the 2.4 binary and start the new instance.

Replica set failover is not instant but will render the set unavailable to writes and interrupt reads until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the downgrade during a predetermined maintenance window.

Downgrade a 2.6 Sharded Cluster

Requirements

While the downgrade is in progress, you cannot make changes to the collection meta-data. For example, during the downgrade, do not do any of the following:

sh.enableSharding()

sh.shardCollection()

sh.addShard()

db.createCollection()

db.collection.drop()

db.dropDatabase()

any operation that creates a database

any other operation that modifies the cluster meta-data in any way. See Sharding Reference for a complete list of sharding commands. Note, however, that not all commands on the Sharding Reference page modifies the cluster meta-data.

Procedure

The downgrade procedure for a sharded cluster reverses the order of the upgrade procedure.

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

Downgrade each shard, one at a time. For each shard,

Downgrade the mongod secondaries before downgrading the primary.

To downgrade the primary, run replSetStepDown and downgrade.

Downgrade all 3 mongod config server instances, leaving the first system in the mongos --configdb argument to downgrade last.

Downgrade and restart each mongos, one at a time. The downgrade process is a binary drop-in replacement.

Turn on the balancer, as described in Enable the Balancer.

Downgrade Procedure

Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you have text or 2dsphere indexes, you can only downgrade to MongoDB 2.4.10 or later.

Except as described on this page, moving between 2.4 and 2.6 is a drop-in replacement:

1

Stop the existing mongod instance.

For example, on Linux, run 2.6 mongod with the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.

Step 1: Stop the existing mongod instance.

For example, on Linux, run 2.6 mongod with the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.

2

Start the new mongod instance.

Ensure you start the 2.4 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Step 2: Start the new mongod instance.

Ensure you start the 2.4 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Release Notes for MongoDB 2.4

March 19, 2013

MongoDB 2.4 includes enhanced geospatial support, switch to V8 JavaScript engine, security enhancements, and text search (beta) and hashed index.

Minor Releases

2.4 Changelog

2.4.13 - Changes

2.4.12 - Changes

2.4.11 - Changes

2.4.10 - Changes

Previous Releases

2.4.13 – February 25, 2015

Enforce BSON BinData length validation SERVER-17278 [https://jira.mongodb.org/browse/SERVER-17278]

Disable SSLv3 ciphers SERVER-15673 [https://jira.mongodb.org/browse/SERVER-15673]

Improve BSON validation SERVER-17264 [https://jira.mongodb.org/browse/SERVER-17264]

2.4.13 Changelog.

All 2.4.13 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.13%22%20AND%20project%20%3D%20SERVER].

2.4.12 – October 16, 2014

Partially written journal last section causes recovery to fail SERVER-15111 [https://jira.mongodb.org/browse/SERVER-15111].

Explicitly zero .ns files on creation SERVER-15369 [https://jira.mongodb.org/browse/SERVER-15369].

2.4.12 Changelog.

All 2.4.12 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.12%22%20AND%20project%20%3D%20SERVER].

2.4.11 – August 18, 2014

Fixed potential information leak: SERVER-14268 [https://jira.mongodb.org/browse/SERVER-14268].

Resolved issue were an _id with a $prefix field caused replication failure due to unvalidated insert SERVER-12209 [https://jira.mongodb.org/browse/SERVER-12209].

Addressed issue where updates to documents with text-indexed fields could lead to incorrect entries SERVER-14738 [https://jira.mongodb.org/browse/SERVER-14738].

Resolved issue where creating descending index on _id could corrupt namespace SERVER-14833 [https://jira.mongodb.org/browse/SERVER-14833].

2.4.11 Changelog.

All 2.4.11 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.11%22%20AND%20project%20%3D%20SERVER].

2.4.10 – April 4, 2014

Performs fast file allocation on Windows when available SERVER-8480 [https://jira.mongodb.org/browse/SERVER-8480].

Start elections if more than one primary is detected SERVER-10793 [https://jira.mongodb.org/browse/SERVER-10793].

Changes to allow safe downgrading from v2.6 to v2.4 SERVER-12914 [https://jira.mongodb.org/browse/SERVER-12914], SERVER-12175 [https://jira.mongodb.org/browse/SERVER-12175].

Fixes for edge cases in index creation SERVER-12481 [https://jira.mongodb.org/browse/SERVER-12481], SERVER-12956 [https://jira.mongodb.org/browse/SERVER-12956].

2.4.10 Changelog.

All 2.4.10 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.10%22%20AND%20project%20%3D%20SERVER].

2.4.9 – January 10, 2014

Fix for instances where mongos incorrectly reports a successful write SERVER-12146 [https://jira.mongodb.org/browse/SERVER-12146].

Make non-primary read preferences consistent with slaveOK versioning logic SERVER-11971 [https://jira.mongodb.org/browse/SERVER-11971].

Allow new sharded cluster connections to read from secondaries when primary is down SERVER-7246 [https://jira.mongodb.org/browse/SERVER-7246].

All 2.4.9 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.9%22%20AND%20project%20%3D%20SERVER].

2.4.8 – November 1, 2013

Increase future compatibility for 2.6 authorization features SERVER-11478 [https://jira.mongodb.org/browse/SERVER-11478].

Fix dbhash cache issue for config servers SERVER-11421 [https://jira.mongodb.org/browse/SERVER-11421].

All 2.4.8 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.8%22%20AND%20project%20%3D%20SERVER].

2.4.7 – October 21, 2013

Fixed over-aggressive caching of V8 Isolates SERVER-10596 [https://jira.mongodb.org/browse/SERVER-10596].

Removed extraneous initial count during mapReduce SERVER-9907 [https://jira.mongodb.org/browse/SERVER-9907].

Cache results of dbhash command SERVER-11021 [https://jira.mongodb.org/browse/SERVER-11021].

Fixed memory leak in aggregation SERVER-10554 [https://jira.mongodb.org/browse/SERVER-10554].

All 2.4.7 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.7%22%20AND%20project%20%3D%20SERVER].

2.4.6 – August 20, 2013

Fix for possible loss of documents during the chunk migration process if a document in the chunk is very large SERVER-10478 [https://jira.mongodb.org/browse/SERVER-10478].

Fix for C++ client shutdown issues SERVER-8891 [https://jira.mongodb.org/browse/SERVER-8891].

Improved replication robustness in presence of high network latency SERVER-10085 [https://jira.mongodb.org/browse/SERVER-10085].

Improved Solaris support SERVER-9832 [https://jira.mongodb.org/browse/SERVER-9832], SERVER-9786 [https://jira.mongodb.org/browse/SERVER-9786], and SERVER-7080 [https://jira.mongodb.org/browse/SERVER-7080].

All 2.4.6 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.6%22%20AND%20project%20%3D%20SERVER].

2.4.5 – July 3, 2013

Fix for CVE-2013-4650 Improperly grant user system privileges on databases other than local SERVER-9983 [https://jira.mongodb.org/browse/SERVER-9983].

Fix for CVE-2013-3969 Remotely triggered segmentation fault in Javascript engine SERVER-9878 [https://jira.mongodb.org/browse/SERVER-9878].

Fix to prevent identical background indexes from being built SERVER-9856 [https://jira.mongodb.org/browse/SERVER-9856].

Config server performance improvements SERVER-9864 [https://jira.mongodb.org/browse/SERVER-9864] and SERVER-5442 [https://jira.mongodb.org/browse/SERVER-5442].

Improved initial sync resilience to network failure SERVER-9853 [https://jira.mongodb.org/browse/SERVER-9853].

All 2.4.5 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.5%22%20AND%20project%20%3D%20SERVER].

2.4.4 – June 4, 2013

Performance fix for Windows version SERVER-9721 [https://jira.mongodb.org/browse/SERVER-9721]

Fix for config upgrade failure SERVER-9661 [https://jira.mongodb.org/browse/SERVER-9661].

Migration to Cyrus SASL library for MongoDB Enterprise SERVER-8813 [https://jira.mongodb.org/browse/SERVER-8813].

All 2.4.4 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.4%22%20AND%20project%20%3D%20SERVER].

2.4.3 – April 23, 2013

Fix for mongo shell ignoring modified object’s _id field SERVER-9385 [https://jira.mongodb.org/browse/SERVER-9385].

Fix for race condition in log rotation SERVER-4739 [https://jira.mongodb.org/browse/SERVER-4739].

Fix for copydb command with authorization in a sharded cluster SERVER-9093 [https://jira.mongodb.org/browse/SERVER-9093].

All 2.4.3 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.3%22%20AND%20project%20%3D%20SERVER].

2.4.2 – April 17, 2013

Several V8 memory leak and performance fixes SERVER-9267 [https://jira.mongodb.org/browse/SERVER-9267] and SERVER-9230 [https://jira.mongodb.org/browse/SERVER-9230].

Fix for upgrading sharded clusters SERVER-9125 [https://jira.mongodb.org/browse/SERVER-9125].

Fix for high volume connection crash SERVER-9014 [https://jira.mongodb.org/browse/SERVER-9014].

All 2.4.2 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.2%22%20AND%20project%20%3D%20SERVER]

2.4.1 – April 17, 2013

Fix for losing index changes during initial sync SERVER-9087 [https://jira.mongodb.org/browse/SERVER-9087]

All 2.4.1 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.1%22%20AND%20project%20%3D%20SERVER].

Major New Features

The following changes in MongoDB affect both standard and Enterprise editions:

Text Search

Add support for text search of content in MongoDB databases as a beta feature. See Text Indexes for more information.

Geospatial Support Enhancements

Add new 2dsphere index. The new index supports GeoJSON [http://geojson.org/geojson-spec.html] objects Point, LineString, and Polygon. See 2dsphere Indexes and Geospatial Indexes and Queries.

Introduce operators $geometry, $geoWithin and $geoIntersects to work with the GeoJSON data.

Hashed Index

Add new hashed index to index documents using hashes of field values. When used to index a shard key, the hashed index ensures an evenly distributed shard key. See also Hashed Shard Keys.

Improvements to the Aggregation Framework

Improve support for geospatial queries. See the $geoWithin operator and the $geoNear pipeline stage.

Improve sort efficiency when the $sort stage immediately precedes a $limit in the pipeline.

Add new operators $millisecond and $concat and modify how $min operator processes null values.

Changes to Update Operators

Add new $setOnInsert operator for use with upsert .

Enhance functionality of the $push operator, supporting its use with the $each, the $sort, and the $slice modifiers.

Additional Limitations for Map-Reduce and $where Operations

The mapReduce command, group command, and the $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell. See the individual command or operator for details.

Improvements to serverStatus Command

Provide additional metrics and customization for the serverStatus command. See db.serverStatus() and serverStatus for more information.

Security Enhancements

Introduce a role-based access control system User Privileges [http://docs.mongodb.org/v2.4/reference/user-privileges] now use a new format for Privilege Documents.

Enforce uniqueness of the user in user privilege documents per database. Previous versions of MongoDB did not enforce this requirement, and existing databases may have duplicates.

Support encrypted connections using SSL certificates signed by a Certificate Authority. See Configure mongod and mongos for SSL.

For more information on security and risk management strategies, see MongoDB Security Practices and Procedures.

Performance Improvements

V8 JavaScript Engine

JavaScript Changes in MongoDB 2.4

Improved Concurrency

Modernized JavaScript Implementation (ES5)

Removed Non-Standard SpiderMonkey Features

E4X Extensions

Destructuring Assignment

Iterator(), StopIteration(), and Generators

InternalError()

for each...in Construct

Array Comprehension

Multiple Catch Blocks

Conditional Function Definition

String Generic Methods

Array Generic Methods

Array Instance Method toSource()

uneval()

Change default JavaScript engine from SpiderMonkey to V8. The change provides improved concurrency for JavaScript operations, modernized JavaScript implementation, and the removal of non-standard SpiderMonkey features, and affects all JavaScript behavior including the commands mapReduce, group, and eval and the query operator $where.

See JavaScript Changes in MongoDB 2.4 for more information about all changes .

BSON Document Validation Enabled by Default for mongod and mongorestore

Enable basic BSON object validation for mongod and mongorestore when writing to MongoDB data files. See wireObjectCheck for details.

Index Build Enhancements

Add support for multiple concurrent index builds in the background by a single mongod instance. See building indexes in the background for more information on background index builds.

Allow the db.killOp() method to terminate a foreground index build.

Improve index validation during index creation. See Compatibility and Index Type Changes in MongoDB 2.4 for more information.

Set Parameters as Command Line Options

Provide --setParameter as a command line option for mongos and mongod. See mongod and mongos for list of available options for setParameter.

Changed Replication Behavior for Chunk Migration

By default, each document move during chunk migration in a sharded cluster propagates to at least one secondary before the balancer proceeds with its next operation. See Chunk Migration and Replication.

Improved Chunk Migration Queue Behavior

Increase performance for moving multiple chunks off an overloaded shard. The balancer no longer waits for the current migration’s delete phase to complete before starting the next chunk migration. See Chunk Migration Queuing for details.

Enterprise

The following changes are specific to MongoDB Enterprise Editions:

SASL Library Change

In 2.4.4, MongoDB Enterprise uses Cyrus SASL. Earlier 2.4 Enterprise versions use GNU SASL (libgsasl). To upgrade to 2.4.4 MongoDB Enterprise or greater, you must install all package dependencies related to this change, including the appropriate Cyrus SASL GSSAPI library. See Install MongoDB Enterprise for details of the dependencies.

New Modular Authentication System with Support for Kerberos

In 2.4, the MongoDB Enterprise now supports authentication via a Kerberos mechanism. See Configure MongoDB with Kerberos Authentication on Linux for more information. For drivers that provide support for Kerberos authentication to MongoDB, refer to Driver Support.

For more information on security and risk management strategies, see MongoDB Security Practices and Procedures.

Additional Information

Platform Notes

For OS X, MongoDB 2.4 only supports OS X versions 10.6 (Snow Leopard) and later. There are no other platform support changes in MongoDB 2.4. See the downloads page [http://www.mongodb.org/downloads/] for more information on platform support.

Upgrade Process

Upgrade MongoDB to 2.4

Upgrade Recommendations and Checklist

Upgrade Standalone mongod Instance to MongoDB 2.4

Upgrade a Replica Set from MongoDB 2.2 to MongoDB 2.4

Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4

Overview

Cluster Meta-data Upgrade

Considerations

Meta-data Upgrade Procedure

Resync after an Interruption of the Critical Section

Upgrade Sharded Cluster Components

Rolling Upgrade Limitation for 2.2.0 Deployments Running with auth Enabled

Upgrade from 2.3 to 2.4

Downgrade MongoDB from 2.4 to Previous Versions

Considerations and Compatibility

Upgrade and Downgrade Procedures

Basic Downgrade and Upgrade

Downgrade to 2.2 After Creating a 2dsphere or text Index

Troubleshooting Upgrade/Downgrade Operations

Compatibility and Index Type Changes in MongoDB 2.4

New Index Types

Index Type Validation

See Upgrade MongoDB to 2.4 for full upgrade instructions.

Other Resources

MongoDB Downloads [http://mongodb.org/downloads].

All JIRA issues resolved in 2.4 [https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+fixVersion+in+%28%222.3.2%22,+%222.3.1%22,+%222.3.0%22,+%222.4.0-rc0%22,+%222.4.0-rc1%22,+%222.4.0-rc2%22,+%222.4.0-rc3%22%29].

All Backwards incompatible changes [https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20fixVersion%20in%20(%222.3.2%22%2C%20%222.3.1%22%2C%20%222.3.0%22%2C%20%222.4.0-rc0%22%2C%20%222.4.0-rc1%22%2C%20%222.4.0-rc2%22%2C%20%222.4.0-rc3%22)%20AND%20%22Backwards%20Compatibility%22%20in%20(%22Major%20Change%22%2C%22Minor%20Change%22%20)%20ORDER%20BY%20votes%20DESC%2C%20issuetype%20DESC%2C%20key%20DESC].

All Third Party License Notices [https://github.com/mongodb/mongo/blob/v2.4/distsrc/THIRD-PARTY-NOTICES].

2.4 Changelog

2.4.13 - Changes

Security: Enforce BSON BinData length validation (SERVER-17278 [https://jira.mongodb.org/browse/SERVER-17278])

Security: Disable SSLv3 ciphers (SERVER-15673 [https://jira.mongodb.org/browse/SERVER-15673])

Networking: Improve BSON validation (SERVER-17264 [https://jira.mongodb.org/browse/SERVER-17264])

2.4.12 - Changes

Sharding: Sharded connection cleanup on setup error can crash mongos (SERVER-15056 [https://jira.mongodb.org/browse/SERVER-15056])

Sharding: “type 7” (OID) error when acquiring distributed lock for first time (SERVER-13616 [https://jira.mongodb.org/browse/SERVER-13616])

Storage: explicitly zero .ns files on creation (SERVER-15369 [https://jira.mongodb.org/browse/SERVER-15369])

Storage: partially written journal last section causes recovery to fail (SERVER-15111 [https://jira.mongodb.org/browse/SERVER-15111])

2.4.11 - Changes

Security: Potential information leak (SERVER-14268 [https://jira.mongodb.org/browse/SERVER-14268])

Replication: _id with $prefix field causes replication failure due to unvalidated insert (SERVER-12209 [https://jira.mongodb.org/browse/SERVER-12209])

Sharding: Invalid access: seg fault in SplitChunkCommand::run (SERVER-14342 [https://jira.mongodb.org/browse/SERVER-14342])

Indexing: Creating descending index on _id can corrupt namespace (SERVER-14833 [https://jira.mongodb.org/browse/SERVER-14833])

Text Search: Updates to documents with text-indexed fields may lead to incorrect entries (SERVER-14738 [https://jira.mongodb.org/browse/SERVER-14738])

Build: Add SCons flag to override treating all warnings as errors (SERVER-13724 [https://jira.mongodb.org/browse/SERVER-13724])

Packaging: Fix mongodb enterprise 2.4 init script to allow multiple processes per host (SERVER-14336 [https://jira.mongodb.org/browse/SERVER-14336])

JavaScript: Do not store native function pointer as a property in function prototype (SERVER-14254 [https://jira.mongodb.org/browse/SERVER-14254])

2.4.10 - Changes

Indexes: Fixed issue that can cause index corruption when building indexes concurrently (SERVER-12990 [https://jira.mongodb.org/browse/SERVER-12990])

Indexes: Fixed issue that can cause index corruption when shutting down secondary node during index build (SERVER-12956 [https://jira.mongodb.org/browse/SERVER-12956])

Indexes: Mongod now recognizes incompatible “future” text and geo index versions and exits gracefully (SERVER-12914 [https://jira.mongodb.org/browse/SERVER-12914])

Indexes: Fixed issue that can cause secondaries to fail replication when building the same index multiple times concurrently (SERVER-12662 [https://jira.mongodb.org/browse/SERVER-12662])

Indexes: Fixed issue that can cause index corruption on the tenth index in a collection if the index build fails (SERVER-12481 [https://jira.mongodb.org/browse/SERVER-12481])

Indexes: Introduced versioning for text and geo indexes to ensure backwards compatibility (SERVER-12175 [https://jira.mongodb.org/browse/SERVER-12175])

Indexes: Disallowed building indexes on the system.indexes collection, which can lead to initial sync failure on secondaries (SERVER-10231 [https://jira.mongodb.org/browse/SERVER-10231])

Sharding: Avoid frequent immediate balancer retries when config servers are out of sync (SERVER-12908 [https://jira.mongodb.org/browse/SERVER-12908])

Sharding: Add indexes to locks collection on config servers to avoid long queries in case of large numbers of collections (SERVER-12548 [https://jira.mongodb.org/browse/SERVER-12548])

Sharding: Fixed issue that can corrupt the config metadata cache when sharding collections concurrently (SERVER-12515 [https://jira.mongodb.org/browse/SERVER-12515])

Sharding: Don’t move chunks created on collections with a hashed shard key if the collection already contains data (SERVER-9259 [https://jira.mongodb.org/browse/SERVER-9259])

Replication: Fixed issue where node appears to be down in a replica set during a compact operation (SERVER-12264 [https://jira.mongodb.org/browse/SERVER-12264])

Replication: Fixed issue that could cause delays in elections when a node is not vetoing an election (SERVER-12170 [https://jira.mongodb.org/browse/SERVER-12170])

Replication: Step down all primaries if multiple primaries are detected in replica set to ensure correct election result (SERVER-10793 [https://jira.mongodb.org/browse/SERVER-10793])

Replication: Upon clock skew detection, secondaries will switch to sync directly from the primary to avoid sync cycles (SERVER-8375 [https://jira.mongodb.org/browse/SERVER-8375])

Runtime: The SIGXCPU signal is now caught and mongod writes a log message and exits gracefully (SERVER-12034 [https://jira.mongodb.org/browse/SERVER-12034])

Runtime: Fixed issue where mongod fails to start on Linux when /sys/dev/block directory is not readable (SERVER-9248 [https://jira.mongodb.org/browse/SERVER-9248])

Windows: No longer zero-fill newly allocated files on systems other than Windows 7 or Windows Server 2008 R2 (SERVER-8480 [https://jira.mongodb.org/browse/SERVER-8480])

GridFS: Chunk size is decreased to 255 KB (from 256 KB) to avoid overhead with usePowerOf2Sizes option (SERVER-13331 [https://jira.mongodb.org/browse/SERVER-13331])

SNMP: Fixed MIB file validation under smilint (SERVER-12487 [https://jira.mongodb.org/browse/SERVER-12487])

Shell: Fixed issue in V8 memory allocation that could cause long-running shell commands to crash (SERVER-11871 [https://jira.mongodb.org/browse/SERVER-11871])

Shell: Fixed memory leak in the md5sumFile shell utility method (SERVER-11560 [https://jira.mongodb.org/browse/SERVER-11560])

Previous Releases

All 2.4.9 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.9%22%20AND%20project%20%3D%20SERVER].

All 2.4.8 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.8%22%20AND%20project%20%3D%20SERVER].

All 2.4.7 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.7%22%20AND%20project%20%3D%20SERVER].

All 2.4.6 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.6%22%20AND%20project%20%3D%20SERVER].

All 2.4.5 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.5%22%20AND%20project%20%3D%20SERVER].

All 2.4.4 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.4%22%20AND%20project%20%3D%20SERVER].

All 2.4.3 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.3%22%20AND%20project%20%3D%20SERVER].

All 2.4.2 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.2%22%20AND%20project%20%3D%20SERVER]

All 2.4.1 improvements [https://jira.mongodb.org/issues/?jql=fixVersion%20%3D%20%222.4.1%22%20AND%20project%20%3D%20SERVER].

JavaScript Changes in MongoDB 2.4

Consider the following impacts of V8 JavaScript Engine in MongoDB 2.4:

Tip

Use the new interpreterVersion() method in the mongo shell and the javascriptEngine field in the output of db.serverBuildInfo() to determine which JavaScript engine a MongoDB binary uses.

Improved Concurrency

Previously, MongoDB operations that required the JavaScript interpreter had to acquire a lock, and a single mongod could only run a single JavaScript operation at a time. The switch to V8 improves concurrency by permitting multiple JavaScript operations to run at the same time.

Modernized JavaScript Implementation (ES5)

The 5th edition of ECMAscript [http://www.ecma-international.org/publications/standards/Ecma-262.htm], abbreviated as ES5, adds many new language features, including:

standardized JSON [http://www.ecma-international.org/ecma-262/5.1/#sec-15.12.1],

strict mode [http://www.ecma-international.org/ecma-262/5.1/#sec-4.2.2],

function.bind() [http://www.ecma-international.org/ecma-262/5.1/#sec-15.3.4.5],

array extensions [http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.16], and

getters and setters.

With V8, MongoDB supports the ES5 implementation of Javascript with the following exceptions.

Note

The following features do not work as expected on documents returned from MongoDB queries:

Object.seal() throws an exception on documents returned from MongoDB queries.

Object.freeze() throws an exception on documents returned from MongoDB queries.

Object.preventExtensions() incorrectly allows the addition of new properties on documents returned from MongoDB queries.

enumerable properties, when added to documents returned from MongoDB queries, are not saved during write operations.

See SERVER-8216 [https://jira.mongodb.org/browse/SERVER-8216], SERVER-8223 [https://jira.mongodb.org/browse/SERVER-8223], SERVER-8215 [https://jira.mongodb.org/browse/SERVER-8215], and SERVER-8214 [https://jira.mongodb.org/browse/SERVER-8214] for more information.

For objects that have not been returned from MongoDB queries, the features work as expected.

Removed Non-Standard SpiderMonkey Features

V8 does not support the following non-standard SpiderMonkey [https://developer.mozilla.org/en-US/docs/SpiderMonkey] JavaScript extensions, previously supported by MongoDB’s use of SpiderMonkey as its JavaScript engine.

E4X Extensions

V8 does not support the non-standard E4X [https://developer.mozilla.org/en-US/docs/E4X] extensions. E4X provides a native XML [https://developer.mozilla.org/en-US/docs/E4X/Processing_XML_with_E4X] object to the JavaScript language and adds the syntax for embedding literal XML documents in JavaScript code.

You need to use alternative XML processing if you used any of the following constructors/methods:

XML()

Namespace()

QName()

XMLList()

isXMLName()

Destructuring Assignment

V8 does not support the non-standard destructuring assignments. Destructuring assignment “extract[s] data from arrays or objects using a syntax that mirrors the construction of array and object literals.” - Mozilla docs [https://developer.mozilla.org/en-US/docs/JavaScript/New_in_JavaScript/1.7#Destructuring_assignment_(Merge_into_own_page.2Fsection)]

Example

The following destructuring assignment is invalid with V8 and throws a SyntaxError:

original = [4, 8, 15];
var [b, ,c] = a;  // <== destructuring assignment
print(b) // 4
print(c) // 15

Iterator(), StopIteration(), and Generators

V8 does not support Iterator(), StopIteration(), and generators [https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Iterators_and_Generators].

InternalError()

V8 does not support InternalError(). Use Error() instead.

for each...in Construct

V8 does not support the use of for each...in [https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Statements/for_each...in] construct. Use for (var x in y) construct instead.

Example

The following for each (var x in y) construct is invalid with V8:

var o = { name: 'MongoDB', version: 2.4 };

for each (var value in o) {
  print(value);
}

Instead, in version 2.4, you can use the for (var x in y) construct:

var o = { name: 'MongoDB', version: 2.4 };

for (var prop in o) {
  var value = o[prop];
  print(value);
}

You can also use the array instance method forEach() with the ES5 method Object.keys():

Object.keys(o).forEach(function (key) {
  var value = o[key];
  print(value);
});

Array Comprehension

V8 does not support Array comprehensions [https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Predefined_Core_Objects#Array_comprehensions].

Use other methods such as the Array instance methods map(), filter(), or forEach().

Example

With V8, the following array comprehension is invalid:

var a = { w: 1, x: 2, y: 3, z: 4 }

var arr = [i * i for each (i in a) if (i > 2)]
printjson(arr)

Instead, you can implement using the Array instance method forEach() and the ES5 method Object.keys() :

var a = { w: 1, x: 2, y: 3, z: 4 }

var arr = [];
Object.keys(a).forEach(function (key) {
  var val = a[key];
  if (val > 2) arr.push(val * val);
})
printjson(arr)

Note

The new logic uses the Array instance method forEach() and not the generic method Array.forEach(); V8 does not support Array generic methods. See Array Generic Methods for more information.

Multiple Catch Blocks

V8 does not support multiple catch blocks and will throw a SyntaxError.

Example

The following multiple catch blocks is invalid with V8 and will throw "SyntaxError: Unexpected token if":

try {
  something()
} catch (err if err instanceof SomeError) {
  print('some error')
} catch (err) {
  print('standard error')
}

Conditional Function Definition

V8 will produce different outcomes than SpiderMonkey with conditional function definitions [https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Functions].

Example

The following conditional function definition produces different outcomes in SpiderMonkey versus V8:

function test () {
   if (false) {
      function go () {};
   }
   print(typeof go)
}

With SpiderMonkey, the conditional function outputs undefined, whereas with V8, the conditional function outputs function.

If your code defines functions this way, it is highly recommended that you refactor the code. The following example refactors the conditional function definition to work in both SpiderMonkey and V8.

function test () {
  var go;
  if (false) {
    go = function () {}
  }
  print(typeof go)
}

The refactored code outputs undefined in both SpiderMonkey and V8.

Note

ECMAscript prohibits conditional function definitions. To force V8 to throw an Error, enable strict mode [http://www.nczonline.net/blog/2012/03/13/its-time-to-start-using-javascript-strict-mode/].

function test () {
  'use strict';

  if (false) {
    function go () {}
  }
}

The JavaScript code throws the following syntax error:

SyntaxError: In strict mode code, functions can only be declared at top level or immediately within another function.

String Generic Methods

V8 does not support String generics [https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String#String_generic_methods]. String generics are a set of methods on the String class that mirror instance methods.

Example

The following use of the generic method String.toLowerCase() is invalid with V8:

var name = 'MongoDB';

var lower = String.toLowerCase(name);

With V8, use the String instance method toLowerCase() available through an instance of the String class instead:

var name = 'MongoDB';

var lower = name.toLowerCase();
print(name + ' becomes ' + lower);

With V8, use the String instance methods instead of following generic methods:

String.charAt() | String.quote() | String.toLocaleLowerCase()
String.charCodeAt() | String.replace() | String.toLocaleUpperCase()
String.concat() | String.search() | String.toLowerCase()
String.endsWith() | String.slice() | String.toUpperCase()
String.indexOf() | String.split() | String.trim()
String.lastIndexOf() | String.startsWith() | String.trimLeft()
String.localeCompare() | String.substr() | String.trimRight()
String.match() | String.substring() |

Array Generic Methods

V8 does not support Array generic methods [https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array#Array_generic_methods]. Array generics are a set of methods on the Array class that mirror instance methods.

Example

The following use of the generic method Array.every() is invalid with V8:

var arr = [4, 8, 15, 16, 23, 42];

function isEven (val) {
   return 0 === val % 2;
}

var allEven = Array.every(arr, isEven);
print(allEven);

With V8, use the Array instance method every() available through an instance of the Array class instead:

var allEven = arr.every(isEven);
print(allEven);

With V8, use the Array instance methods instead of the following generic methods:

Array.concat() | Array.lastIndexOf() | Array.slice()
Array.every() | Array.map() | Array.some()
Array.filter() | Array.pop() | Array.sort()
Array.forEach() | Array.push() | Array.splice()
Array.indexOf() | Array.reverse() | Array.unshift()
Array.join() | Array.shift() |

Array Instance Method toSource()

V8 does not support the Array instance method toSource() [https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/toSource]. Use the Array instance method toString() instead.

uneval()

V8 does not support the non-standard method uneval(). Use the standardized JSON.stringify() [https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify] method instead.

Upgrade MongoDB to 2.4

In the general case, the upgrade from MongoDB 2.2 to 2.4 is a binary-compatible “drop-in” upgrade: shut down the mongod instances and replace them with mongod instances running 2.4. However, before you attempt any upgrade please familiarize yourself with the content of this document, particularly the procedure for upgrading sharded clusters and the considerations for reverting to 2.2 after running 2.4.

Upgrade Recommendations and Checklist

When upgrading, consider the following:

For all deployments using authentication, upgrade the drivers (i.e. client libraries), before upgrading the mongod instance or instances.

To upgrade to 2.4 sharded clusters must upgrade following the meta-data upgrade procedure.

If you’re using 2.2.0 and running with authorization enabled, you will need to upgrade first to 2.2.1 and then upgrade to 2.4. See Rolling Upgrade Limitation for 2.2.0 Deployments Running with auth Enabled.

If you have system.users documents (i.e. for authorization) that you created before 2.4 you must ensure that there are no duplicate values for the user field in the system.users collection in any database. If you do have documents with duplicate user fields, you must remove them before upgrading.

See Security Enhancements for more information.

Upgrade Standalone mongod Instance to MongoDB 2.4

Download binaries of the latest release in the 2.4 series from the MongoDB Download Page [http://www.mongodb.org/downloads]. See Install MongoDB for more information.

Shutdown your mongod instance. Replace the existing binary with the 2.4 mongod binary and restart mongod.

Upgrade a Replica Set from MongoDB 2.2 to MongoDB 2.4

You can upgrade to 2.4 by performing a “rolling” upgrade of the set by upgrading the members individually while the other members are available to minimize downtime. Use the following procedure:

Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.2 binary with the 2.4 binary. After upgrading a mongod instance, wait for the member to recover to SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

Use the mongo shell method rs.stepDown() to step down the primary to allow the normal failover procedure. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.

Once the primary has stepped down and another member has assumed PRIMARY state, as observed in the output of rs.status(), shut down the previous primary and replace mongod binary with the 2.4 binary and start the new process.

Note

Replica set failover is not instant but will render the set unavailable to read or accept writes until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the upgrade during a predefined maintenance window.

Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4

Important

Only upgrade sharded clusters to 2.4 if all members of the cluster are currently running instances of 2.2. The only supported upgrade path for sharded clusters running 2.0 is via 2.2.

Overview

Upgrading a sharded cluster from MongoDB version 2.2 to 2.4 (or 2.3) requires that you run a 2.4 mongos with the --upgrade option, described in this procedure. The upgrade process does not require downtime.

The upgrade to MongoDB 2.4 adds epochs to the meta-data for all collections and chunks in the existing cluster. MongoDB 2.2 processes are capable of handling epochs, even though 2.2 did not require them. This procedure applies only to upgrades from version 2.2. Earlier versions of MongoDB do not correctly handle epochs. See Cluster Meta-data Upgrade for more information.

After completing the meta-data upgrade you can fully upgrade the components of the cluster. With the balancer disabled:

Upgrade all mongos instances in the cluster.

Upgrade all 3 mongod config server instances.

Upgrade the mongod instances for each shard, one at a time.

See Upgrade Sharded Cluster Components for more information.

Cluster Meta-data Upgrade

Considerations

Beware of the following properties of the cluster upgrade process:

Before you start the upgrade, ensure that the amount of free space on the filesystem for the config database is at least 4 to 5 times the amount of space currently used by the config database data files.

Additionally, ensure that all indexes in the config database are {v:1} indexes. If a critical index is a {v:0} index, chunk splits can fail due to known issues with the {v:0} format. {v:0} indexes are present on clusters created with MongoDB 2.0 or earlier.

The duration of the metadata upgrade depends on the network latency between the node performing the upgrade and the three config servers. Ensure low latency between the upgrade process and the config servers.

While the upgrade is in progress, you cannot make changes to the collection meta-data. For example, during the upgrade, do not perform:

sh.enableSharding(),

sh.shardCollection(),

sh.addShard(),

db.createCollection(),

db.collection.drop(),

db.dropDatabase(),

any operation that creates a database, or

any other operation that modifies the cluster meta-data in any way. See Sharding Reference for a complete list of sharding commands. Note, however, that not all commands on the Sharding Reference page modifies the cluster meta-data.

Once you upgrade to 2.4 and complete the upgrade procedure do not use 2.0 mongod and mongos processes in your cluster. 2.0 process may re-introduce old meta-data formats into cluster meta-data.

The upgraded config database will require more storage space than before, to make backup and working copies of the config.chunks and config.collections collections. As always, if storage requirements increase, the mongod might need to pre-allocate additional data files. See What tools can I use to investigate storage use in MongoDB? for more information.

Meta-data Upgrade Procedure

Changes to the meta-data format for sharded clusters, stored in the config database, require a special meta-data upgrade procedure when moving to 2.4.

Do not perform operations that modify meta-data while performing this procedure. See Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4 for examples of prohibited operations.

Before you start the upgrade, ensure that the amount of free space on the filesystem for the config database is at least 4 to 5 times the amount of space currently used by the config database data files.

Additionally, ensure that all indexes in the config database are {v:1} indexes. If a critical index is a {v:0} index, chunk splits can fail due to known issues with the {v:0} format. {v:0} indexes are present on clusters created with MongoDB 2.0 or earlier.

The duration of the metadata upgrade depends on the network latency between the node performing the upgrade and the three config servers. Ensure low latency between the upgrade process and the config servers.

To check the version of your indexes, use db.collection.getIndexes().

If any index on the config database is {v:0}, you should rebuild those indexes by connecting to the mongos and either: rebuild all indexes using the db.collection.reIndex() method, or drop and rebuild specific indexes using db.collection.dropIndex() and then db.collection.ensureIndex(). If you need to upgrade the _id index to {v:1} use db.collection.reIndex().

You may have {v:0} indexes on other databases in the cluster.

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

Optional

For additional security during the upgrade, you can make a backup of the config database using mongodump or other backup tools.

Ensure there are no version 2.0 mongod or mongos processes still active in the sharded cluster. The automated upgrade process checks for 2.0 processes, but network availability can prevent a definitive check. Wait 5 minutes after stopping or upgrading version 2.0 mongos processes to confirm that none are still active.

Start a single 2.4 mongos process with configDB pointing to the sharded cluster’s config servers and with the --upgrade option. The upgrade process happens before the process becomes a daemon (i.e. before --fork.)

You can upgrade an existing mongos instance to 2.4 or you can start a new mongos instance that can reach all config servers if you need to avoid reconfiguring a production mongos.

Start the mongos with a command that resembles the following:

mongos --configdb <config servers> --upgrade

Without the --upgrade option 2.4 mongos processes will fail to start until the upgrade process is complete.

The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If there are very many sharded collections or there are stale locks held by other failed processes, acquiring the locks for all collections can take seconds or minutes. See the log for progress updates.

When the mongos process starts successfully, the upgrade is complete. If the mongos process fails to start, check the log for more information.

If the mongos terminates or loses its connection to the config servers during the upgrade, you may always safely retry the upgrade.

However, if the upgrade failed during the short critical section, the mongos will exit and report that the upgrade will require manual intervention. To continue the upgrade process, you must follow the Resync after an Interruption of the Critical Section procedure.

Optional

If the mongos logs show the upgrade waiting for the upgrade lock, a previous upgrade process may still be active or may have ended abnormally. After 15 minutes of no remote activity mongos will force the upgrade lock. If you can verify that there are no running upgrade processes, you may connect to a 2.2 mongos process and force the lock manually:

mongo <mongos.example.net>

db.getMongo().getCollection("config.locks").findOne({ _id : "configUpgrade" })

If the process specified in the process field of this document is verifiably offline, run the following operation to force the lock.

db.getMongo().getCollection("config.locks").update({ _id : "configUpgrade" }, { $set : { state : 0 } })

It is always more safe to wait for the mongos to verify that the lock is inactive, if you have any doubts about the activity of another upgrade operation. In addition to the configUpgrade, the mongos may need to wait for specific collection locks. Do not force the specific collection locks.

Upgrade and restart other mongos processes in the sharded cluster, without the --upgrade option.

See Upgrade Sharded Cluster Components for more information.

Re-enable the balancer. You can now perform operations that modify cluster meta-data.

Once you have upgraded, do not introduce version 2.0 MongoDB processes into the sharded cluster. This can reintroduce old meta-data formats into the config servers. The meta-data change made by this upgrade process will help prevent errors caused by cross-version incompatibilities in future versions of MongoDB.

Resync after an Interruption of the Critical Section

During the short critical section of the upgrade that applies changes to the meta-data, it is unlikely but possible that a network interruption can prevent all three config servers from verifying or modifying data. If this occurs, the config servers must be re-synced, and there may be problems starting new mongos processes. The sharded cluster will remain accessible, but avoid all cluster meta-data changes until you resync the config servers. Operations that change meta-data include: adding shards, dropping databases, and dropping collections.

Note

Only perform the following procedure if something (e.g. network, power, etc.) interrupts the upgrade process during the short critical section of the upgrade. Remember, you may always safely attempt the meta data upgrade procedure.

To resync the config servers:

Turn off the balancer in the sharded cluster and stop all meta-data operations. If you are in the middle of an upgrade process (Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4), you have already disabled the balancer.

Shut down two of the three config servers, preferably the last two listed in the configDB string. For example, if your configDB string is configA:27019,configB:27019,configC:27019, shut down configB and configC. Shutting down the last two config servers ensures that most mongos instances will have uninterrupted access to cluster meta-data.

mongodump the data files of the active config server (configA).

Move the data files of the deactivated config servers (configB and configC) to a backup location.

Create new, empty data directories.

Restart the disabled config servers with --dbpath pointing to the now-empty data directory and --port pointing to an alternate port (e.g. 27020).

Use mongorestore to repopulate the data files on the disabled documents from the active config server (configA) to the restarted config servers on the new port (configB:27020,configC:27020). These config servers are now re-synced.

Restart the restored config servers on the old port, resetting the port back to the old settings (configB:27019 and configC:27019).

In some cases connection pooling may cause spurious failures, as the mongos disables old connections only after attempted use. 2.4 fixes this problem, but to avoid this issue in version 2.2, you can restart all mongos instances (one-by-one, to avoid downtime) and use the rs.stepDown() method before restarting each of the shard replica set primaries.

The sharded cluster is now fully resynced; however before you attempt the upgrade process again, you must manually reset the upgrade state using a version 2.2 mongos. Begin by connecting to the 2.2 mongos with the mongo shell:

mongo <mongos.example.net>

Then, use the following operation to reset the upgrade process:

db.getMongo().getCollection("config.version").update({ _id : 1 }, { $unset : { upgradeState : 1 } })

Finally retry the upgrade process, as in Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4.

Upgrade Sharded Cluster Components

After you have successfully completed the meta-data upgrade process described in Meta-data Upgrade Procedure, and the 2.4 mongos instance starts, you can upgrade the other processes in your MongoDB deployment.

While the balancer is still disabled, upgrade the components of your sharded cluster in the following order:

Upgrade all mongos instances in the cluster, in any order.

Upgrade all 3 mongod config server instances, upgrading the first system in the mongos --configdb argument last.

Upgrade each shard, one at a time, upgrading the mongod secondaries before running replSetStepDown and upgrading the primary of each shard.

When this process is complete, you can now re-enable the balancer.

Rolling Upgrade Limitation for 2.2.0 Deployments Running with auth Enabled

MongoDB cannot support deployments that mix 2.2.0 and 2.4.0, or greater, components. MongoDB version 2.2.1 and later processes can exist in mixed deployments with 2.4-series processes. Therefore you cannot perform a rolling upgrade from MongoDB 2.2.0 to MongoDB 2.4.0. To upgrade a cluster with 2.2.0 components, use one of the following procedures.

Perform a rolling upgrade of all 2.2.0 processes to the latest 2.2-series release (e.g. 2.2.3) so that there are no processes in the deployment that predate 2.2.1. When there are no 2.2.0 processes in the deployment, perform a rolling upgrade to 2.4.0.

Stop all processes in the cluster. Upgrade all processes to a 2.4-series release of MongoDB, and start all processes at the same time.

Upgrade from 2.3 to 2.4

If you used a mongod from the 2.3 or 2.4-rc (release candidate) series, you can safely transition these databases to 2.4.0 or later; however, if you created 2dsphere or text indexes using a mongod before v2.4-rc2, you will need to rebuild these indexes. For example:

db.records.dropIndex( { loc: "2dsphere" } )
db.records.dropIndex( "records_text" )

db.records.ensureIndex( { loc: "2dsphere" } )
db.records.ensureIndex( { records: "text" } )

Downgrade MongoDB from 2.4 to Previous Versions

For some cases the on-disk format of data files used by 2.4 and 2.2 mongod is compatible, and you can upgrade and downgrade if needed. However, several new features in 2.4 are incompatible with previous versions:

2dsphere indexes are incompatible with 2.2 and earlier mongod instances.

text indexes are incompatible with 2.2 and earlier mongod instances.

using a hashed index as a shard key are incompatible with 2.2 and earlier mongos instances.

hashed indexes are incompatible with 2.0 and earlier mongod instances.

Important

Collections sharded using hashed shard keys, should not use 2.2 mongod instances, which cannot correctly support cluster operations for these collections.

If you completed the meta-data upgrade for a sharded cluster, you can safely downgrade to 2.2 MongoDB processes. Do not use 2.0 processes after completing the upgrade procedure.

Note

In sharded clusters, once you have completed the meta-data upgrade procedure, you cannot use 2.0 mongod or mongos instances in the same cluster.

If you complete the meta-data upgrade, you can safely downgrade components in any order. When upgrade again, always upgrade mongos instances before mongod instances.

Do not create 2dsphere or text indexes in a cluster that has 2.2 components.

Considerations and Compatibility

If you upgrade to MongoDB 2.4, and then need to run MongoDB 2.2 with the same data files, consider the following limitations.

If you use a hashed index as the shard key index, which is only possible under 2.4 you will not be able to query data in this sharded collection. Furthermore, a 2.2 mongos cannot properly route an insert operation for a collections sharded using a hashed index for the shard key index: any data that you insert using a 2.2 mongos, will not arrive on the correct shard and will not be reachable by future queries.

If you never create an 2dsphere or text index, you can move between a 2.4 and 2.2 mongod for a given data set; however, after you create the first 2dsphere or text index with a 2.4 mongod you will need to run a 2.2 mongod with the --upgrade option and drop any 2dsphere or text index.

Upgrade and Downgrade Procedures

Basic Downgrade and Upgrade

Except as described below, moving between 2.2 and 2.4 is a drop-in replacement:

stop the existing mongod, using the --shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath.

start the new mongod processes with the same dbPath setting, for example:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.

Downgrade to 2.2 After Creating a 2dsphere or text Index

If you have created 2dsphere or text indexes while running a 2.4 mongod instance, you can downgrade at any time, by starting the 2.2 mongod with the --upgrade option as follows:

mongod --dbpath /var/mongod/data/ --upgrade

Then, you will need to drop any existing 2dsphere or text indexes using db.collection.dropIndex(), for example:

db.records.dropIndex( { loc: "2dsphere" } )
db.records.dropIndex( "records_text" )

Warning

--upgrade will run repairDatabase on any database where you have created a 2dsphere or text index, which will rebuild all indexes.

Troubleshooting Upgrade/Downgrade Operations

If you do not use --upgrade, when you attempt to start a 2.2 mongod and you have created a 2dsphere or text index, mongod will return the following message:

'need to upgrade database index_plugin_upgrade with pdfile version 4.6, new version: 4.5 Not upgrading, exiting'

While running 2.4, to check the data file version of a MongoDB database, use the following operation in the shell:

db.getSiblingDB('<databasename>').stats().dataFileVersion

The major data file [1] version for both 2.2 and 2.4 is 4, the minor data file version for 2.2 is 5 and the minor data file version for 2.4 is 6 after you create a 2dsphere or text index.

[1]
The data file version (i.e. pdfile version) is independent and unrelated to the release version of MongoDB.

Compatibility and Index Type Changes in MongoDB 2.4

In 2.4 MongoDB includes two new features related to indexes that users upgrading to version 2.4 must consider, particularly with regard to possible downgrade paths. For more information on downgrades, see Downgrade MongoDB from 2.4 to Previous Versions.

New Index Types

In 2.4 MongoDB adds two new index types: 2dsphere and text. These index types do not exist in 2.2, and for each database, creating a 2dsphere or text index, will upgrade the data-file version and make that database incompatible with 2.2.

If you intend to downgrade, you should always drop all 2dsphere and text indexes before moving to 2.2.

You can use the downgrade procedure to downgrade these databases and run 2.2 if needed, however this will run a full database repair (as with repairDatabase) for all affected databases.

Index Type Validation

In MongoDB 2.2 and earlier you could specify invalid index types that did not exist. In these situations, MongoDB would create an ascending (e.g. 1) index. Invalid indexes include index types specified by strings that do not refer to an existing index type, and all numbers other than 1 and -1. [1]

In 2.4, creating any invalid index will result in an error. Furthermore, you cannot create a 2dsphere or text index on a collection if its containing database has any invalid index types. [1]

Example

If you attempt to add an invalid index in MongoDB 2.4, as in the following:

db.coll.ensureIndex( { field: "1" } )

MongoDB will return the following error document:

{
  "err" : "Unknown index plugin '1' in index { field: \"1\" }"
  "code": 16734,
  "n": <number>,
  "connectionId": <number>,
  "ok": 1
}

[1]
(1, 2) In 2.4, indexes that specify a type of "1" or "-1" (the strings "1" and "-1") will continue to exist, despite a warning on start-up. However, a secondary in a replica set cannot complete an initial sync from a primary that has a "1" or "-1" index. Avoid all indexes with invalid types.

Release Notes for MongoDB 2.2

Upgrading

MongoDB 2.2 is a production release series and succeeds the 2.0 production release series.

MongoDB 2.0 data files are compatible with 2.2-series binaries without any special migration process. However, always perform the upgrade process for replica sets and sharded clusters using the procedures that follow.

Synopsis

mongod, 2.2 is a drop-in replacement for 2.0 and 1.8.

Check your driver documentation for information regarding required compatibility upgrades, and always run the recent release of your driver.

Typically, only users running with authentication, will need to upgrade drivers before continuing with the upgrade to 2.2.

For all deployments using authentication, upgrade the drivers (i.e. client libraries), before upgrading the mongod instance or instances.

For all upgrades of sharded clusters:

turn off the balancer during the upgrade process. See the Disable the Balancer section for more information.

upgrade all mongos instances before upgrading any mongod instances.

Other than the above restrictions, 2.2 processes can interoperate with 2.0 and 1.8 tools and processes. You can safely upgrade the mongod and mongos components of a deployment one by one while the deployment is otherwise operational. Be sure to read the detailed upgrade procedures below before upgrading production systems.

[1]
To minimize the interruption caused by election process, always upgrade the secondaries of the set first, then step down the primary, and then upgrade the primary.

Upgrading a Standalone mongod

Download binaries of the latest release in the 2.2 series from the MongoDB Download Page [http://downloads.mongodb.org/].

Shutdown your mongod instance. Replace the existing binary with the 2.2 mongod binary and restart MongoDB.

Upgrading a Replica Set

You can upgrade to 2.2 by performing a “rolling” upgrade of the set by upgrading the members individually while the other members are available to minimize downtime. Use the following procedure:

Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.0 binary with the 2.2 binary. After upgrading a mongod instance, wait for the member to recover to SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

Use the mongo shell method rs.stepDown() to step down the primary to allow the normal failover procedure. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.

Once the primary has stepped down and another member has assumed PRIMARY state, as observed in the output of rs.status(), shut down the previous primary and replace mongod binary with the 2.2 binary and start the new process.

Note

Replica set failover is not instant but will render the set unavailable to read or accept writes until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the upgrade during a predefined maintenance window.

Upgrading a Sharded Cluster

Use the following procedure to upgrade a sharded cluster:

Disable the balancer.

Upgrade all mongos instances first, in any order.

Upgrade all of the mongod config server instances using the stand alone procedure. To keep the cluster online, be sure that at all times at least one config server is up.

Upgrade each shard’s replica set, using the upgrade procedure for replica sets detailed above.

re-enable the balancer.

Note

Balancing is not currently supported in mixed 2.0.x and 2.2.0 deployments. Thus you will want to reach a consistent version for all shards within a reasonable period of time, e.g. same-day. See SERVER-6902 [https://jira.mongodb.org/browse/SERVER-6902] for more information.

Changes

Major Features

Aggregation Framework

The aggregation framework makes it possible to do aggregation operations without needing to use map-reduce. The aggregate command exposes the aggregation framework, and the aggregate() helper in the mongo shell provides an interface to these operations. Consider the following resources for background on the aggregation framework and its use:

Documentation: Aggregation Concepts

Reference: Aggregation Reference

Examples: Aggregation Examples

TTL Collections

TTL collections remove expired data from a collection, using a special index and a background thread that deletes expired documents every minute. These collections are useful as an alternative to capped collections in some cases, such as for data warehousing and caching cases, including: machine generated event data, logs, and session information that needs to persist in a database for only a limited period of time.

For more information, see the Expire Data from Collections by Setting TTL tutorial.

Concurrency Improvements

MongoDB 2.2 increases the server’s capacity for concurrent operations with the following improvements:

DB Level Locking [https://jira.mongodb.org/browse/SERVER-4328]

Improved Yielding on Page Faults [https://jira.mongodb.org/browse/SERVER-3357]

Improved Page Fault Detection on Windows [https://jira.mongodb.org/browse/SERVER-4538]

To reflect these changes, MongoDB now provides changed and improved reporting for concurrency and use, see locks and recordStats in server status and see db.currentOp(), mongotop, and mongostat.

Improved Data Center Awareness with Tag Aware Sharding

MongoDB 2.2 adds additional support for geographic distribution or other custom partitioning for sharded collections in clusters. By using this “tag aware” sharding, you can automatically ensure that data in a sharded database system is always on specific shards. For example, with tag aware sharding, you can ensure that data is closest to the application servers that use that data most frequently.

Shard tagging controls data location, and is complementary but separate from replica set tagging, which controls read preference and write concern. For example, shard tagging can pin all “USA” data to one or more logical shards, while replica set tagging can control which mongod instances (e.g. “production” or “reporting”) the application uses to service requests.

See the documentation for the following helpers in the mongo shell that support tagged sharding configuration:

sh.addShardTag()

sh.addTagRange()

sh.removeShardTag()

Also, see Tag Aware Sharding and Manage Shard Tags.

Fully Supported Read Preference Semantics

All MongoDB clients and drivers now support full read preferences, including consistent support for a full range of read preference modes and tag sets. This support extends to the mongos and applies identically to single replica sets and to the replica sets for each shard in a sharded cluster.

Additional read preference support now exists in the mongo shell using the readPref() cursor method.

Compatibility Changes

Authentication Changes

MongoDB 2.2 provides more reliable and robust support for authentication clients, including drivers and mongos instances.

If your cluster runs with authentication:

For all drivers, use the latest release of your driver and check its release notes.

In sharded environments, to ensure that your cluster remains available during the upgrade process you must use the upgrade procedure for sharded clusters.

findAndModify Returns Null Value for Upserts that Perform Inserts

In version 2.2, for upsert that perform inserts with the new option set to false, findAndModify commands will now return the following output:

{ 'ok': 1.0, 'value': null }

In the mongo shell, upsert findAndModify operations that perform inserts (with new set to false.)only output a null value.

In version 2.0 these operations would return an empty document, e.g. { }.

See: SERVER-6226 [https://jira.mongodb.org/browse/SERVER-6226] for more information.

mongodump 2.2 Output Incompatible with Pre-2.2 mongorestore

If you use the mongodump tool from the 2.2 distribution to create a dump of a database, you must use a 2.2 (or later) version of mongorestore to restore that dump.

See: SERVER-6961 [https://jira.mongodb.org/browse/SERVER-6961] for more information.

ObjectId().toString() Returns String Literal ObjectId("...")

In version 2.2, the toString() method returns the string representation of the ObjectId() object and has the format ObjectId("...").

Consider the following example that calls the toString() method on the ObjectId("507c7f79bcf86cd7994f6c0e") object:

ObjectId("507c7f79bcf86cd7994f6c0e").toString()

The method now returns the string ObjectId("507c7f79bcf86cd7994f6c0e").

Previously, in version 2.0, the method would return the hexadecimal string 507c7f79bcf86cd7994f6c0e.

If compatibility between versions 2.0 and 2.2 is required, use ObjectId().str, which holds the hexadecimal string value in both versions.

ObjectId().valueOf() Returns hexadecimal string

In version 2.2, the valueOf() method returns the value of the ObjectId() object as a lowercase hexadecimal string.

Consider the following example that calls the valueOf() method on the ObjectId("507c7f79bcf86cd7994f6c0e") object:

ObjectId("507c7f79bcf86cd7994f6c0e").valueOf()

The method now returns the hexadecimal string 507c7f79bcf86cd7994f6c0e.

Previously, in version 2.0, the method would return the object ObjectId("507c7f79bcf86cd7994f6c0e").

If compatibility between versions 2.0 and 2.2 is required, use ObjectId().str attribute, which holds the hexadecimal string value in both versions.

Behavioral Changes

Restrictions on Collection Names

In version 2.2, collection names cannot:

contain the $.

be an empty string (i.e. "").

This change does not affect collections created with now illegal names in earlier versions of MongoDB.

These new restrictions are in addition to the existing restrictions on collection names which are:

A collection name should begin with a letter or an underscore.

A collection name cannot contain the null character.

Begin with the system. prefix. MongoDB reserves system. for system collections, such as the system.indexes collection.

The maximum size of a collection name is 128 characters, including the name of the database. However, for maximum flexibility, collections should have names less than 80 characters.

Collections names may have any other valid UTF-8 string.

See the SERVER-4442 [https://jira.mongodb.org/browse/SERVER-4442] and the Are there any restrictions on the names of Collections? FAQ item.

Restrictions on Database Names for Windows

Database names running on Windows can no longer contain the following characters:

/\. "*<>:|?

The names of the data files include the database name. If you attempt to upgrade a database instance with one or more of these characters, mongod will refuse to start.

Change the name of these databases before upgrading. See SERVER-4584 [https://jira.mongodb.org/browse/SERVER-4584] and SERVER-6729 [https://jira.mongodb.org/browse/SERVER-6729] for more information.

_id Fields and Indexes on Capped Collections

All capped collections now have an _id field by default, if they exist outside of the local database, and now have indexes on the _id field. This change only affects capped collections created with 2.2 instances and does not affect existing capped collections.

See: SERVER-5516 [https://jira.mongodb.org/browse/SERVER-5516] for more information.

New $elemMatch Projection Operator

The $elemMatch operator allows applications to narrow the data returned from queries so that the query operation will only return the first matching element in an array. See the $elemMatch reference and the SERVER-2238 [https://jira.mongodb.org/browse/SERVER-2238] and SERVER-828 [https://jira.mongodb.org/browse/SERVER-828] issues for more information.

Windows Specific Changes

Windows XP is Not Supported

As of 2.2, MongoDB does not support Windows XP. Please upgrade to a more recent version of Windows to use the latest releases of MongoDB. See SERVER-5648 [https://jira.mongodb.org/browse/SERVER-5648] for more information.

Service Support for mongos.exe

You may now run mongos.exe instances as a Windows Service. See the mongos.exe reference and Configure a Windows Service for MongoDB and SERVER-1589 [https://jira.mongodb.org/browse/SERVER-1589] for more information.

Log Rotate Command Support

MongoDB for Windows now supports log rotation by way of the logRotate database command. See SERVER-2612 [https://jira.mongodb.org/browse/SERVER-2612] for more information.

New Build Using SlimReadWrite Locks for Windows Concurrency

Labeled “2008+” on the Downloads Page [http://www.mongodb.org/downloads], this build for 64-bit versions of Windows Server 2008 R2 and for Windows 7 or newer, offers increased performance over the standard 64-bit Windows build of MongoDB. See SERVER-3844 [https://jira.mongodb.org/browse/SERVER-3844] for more information.

Tool Improvements

Index Definitions Handled by mongodump and mongorestore

When you specify the --collection option to mongodump, mongodump will now backup the definitions for all indexes that exist on the source database. When you attempt to restore this backup with mongorestore, the target mongod will rebuild all indexes. See SERVER-808 [https://jira.mongodb.org/browse/SERVER-808] for more information.

mongorestore now includes the --noIndexRestore option to provide the preceding behavior. Use --noIndexRestore to prevent mongorestore from building previous indexes.

mongooplog for Replaying Oplogs

The mongooplog tool makes it possible to pull oplog entries from mongod instance and apply them to another mongod instance. You can use mongooplog to achieve point-in-time backup of a MongoDB data set. See the SERVER-3873 [https://jira.mongodb.org/browse/SERVER-3873] case and the mongooplog reference.

Authentication Support for mongotop and mongostat

mongotop and mongostat now contain support for username/password authentication. See SERVER-3875 [https://jira.mongodb.org/browse/SERVER-3875] and SERVER-3871 [https://jira.mongodb.org/browse/SERVER-3871] for more information regarding this change. Also consider the documentation of the following options for additional information:

mongotop --username

mongotop --password

mongostat --username

mongostat --password

Write Concern Support for mongoimport and mongorestore

mongoimport now provides an option to halt the import if the operation encounters an error, such as a network interruption, a duplicate key exception, or a write error. The --stopOnError option will produce an error rather than silently continue importing data. See SERVER-3937 [https://jira.mongodb.org/browse/SERVER-3937] for more information.

In mongorestore, the --w option provides support for configurable write concern.

mongodump Support for Reading from Secondaries

You can now run mongodump when connected to a secondary member of a replica set. See SERVER-3854 [https://jira.mongodb.org/browse/SERVER-3854] for more information.

mongoimport Support for full 16MB Documents

Previously, mongoimport would only import documents that were less than 4 megabytes in size. This issue is now corrected, and you may use mongoimport to import documents that are at least 16 megabytes ins size. See SERVER-4593 [https://jira.mongodb.org/browse/SERVER-4593] for more information.

Timestamp() Extended JSON format

MongoDB extended JSON now includes a new Timestamp() type to represent the Timestamp type that MongoDB uses for timestamps in the oplog among other contexts.

This permits tools like mongooplog and mongodump to query for specific timestamps. Consider the following mongodump operation:

mongodump --db local --collection oplog.rs --query '{"ts":{"$gt":{"$timestamp" : {"t": 1344969612000, "i": 1 }}}}'  --out oplog-dump

See SERVER-3483 [https://jira.mongodb.org/browse/SERVER-3483] for more information.

Shell Improvements

Improved Shell User Interface

2.2 includes a number of changes that improve the overall quality and consistency of the user interface for the mongo shell:

Full Unicode support.

Bash-like line editing features. See SERVER-4312 [https://jira.mongodb.org/browse/SERVER-4312] for more information.

Multi-line command support in shell history. See SERVER-3470 [https://jira.mongodb.org/browse/SERVER-3470] for more information.

Windows support for the edit command. See SERVER-3998 [https://jira.mongodb.org/browse/SERVER-3998] for more information.

Helper to load Server-Side Functions

The db.loadServerScripts() loads the contents of the current database’s system.js collection into the current mongo shell session. See SERVER-1651 [https://jira.mongodb.org/browse/SERVER-1651] for more information.

Support for Bulk Inserts

If you pass an array of documents to the insert() method, the mongo shell will now perform a bulk insert operation. See SERVER-3819 [https://jira.mongodb.org/browse/SERVER-3819] and SERVER-2395 [https://jira.mongodb.org/browse/SERVER-2395] for more information.

Note

For bulk inserts on sharded clusters, the getLastError command alone is insufficient to verify success. Applications should must verify the success of bulk inserts in application logic.

Operations

Support for Logging to Syslog

See the SERVER-2957 [https://jira.mongodb.org/browse/SERVER-2957] case and the documentation of the syslogFacility run-time option or the mongod --syslog and mongos --syslog command line-options.

touch Command

Added the touch command to read the data and/or indexes from a collection into memory. See: SERVER-2023 [https://jira.mongodb.org/browse/SERVER-2023] and touch for more information.

indexCounters No Longer Report Sampled Data

indexCounters now report actual counters that reflect index use and state. In previous versions, these data were sampled. See SERVER-5784 [https://jira.mongodb.org/browse/SERVER-5784] and indexCounters for more information.

Padding Specifiable on compact Command

See the documentation of the compact and the SERVER-4018 [https://jira.mongodb.org/browse/SERVER-4018] issue for more information.

Added Build Flag to Use System Libraries

The Boost library, version 1.49, is now embedded in the MongoDB code base.

If you want to build MongoDB binaries using system Boost libraries, you can pass scons using the --use-system-boost flag, as follows:

scons --use-system-boost

When building MongoDB, you can also pass scons a flag to compile MongoDB using only system libraries rather than the included versions of the libraries. For example:

scons --use-system-all

See the SERVER-3829 [https://jira.mongodb.org/browse/SERVER-3829] and SERVER-5172 [https://jira.mongodb.org/browse/SERVER-5172] issues for more information.

Memory Allocator Changed to TCMalloc

To improve performance, MongoDB 2.2 uses the TCMalloc memory allocator from Google Perftools. For more information about this change see the SERVER-188 [https://jira.mongodb.org/browse/SERVER-188] and SERVER-4683 [https://jira.mongodb.org/browse/SERVER-4683]. For more information about TCMalloc, see the documentation of TCMalloc [http://goog-perftools.sourceforge.net/doc/tcmalloc.html] itself.

Replication

Improved Logging for Replica Set Lag

When secondary members of a replica set fall behind in replication, mongod now provides better reporting in the log. This makes it possible to track replication in general and identify what process may produce errors or halt replication. See SERVER-3575 [https://jira.mongodb.org/browse/SERVER-3575] for more information.

Replica Set Members can Sync from Specific Members

The new replSetSyncFrom command and new rs.syncFrom() helper in the mongo shell make it possible for you to manually configure from which member of the set a replica will poll oplog entries. Use these commands to override the default selection logic if needed. Always exercise caution with replSetSyncFrom when overriding the default behavior.

Replica Set Members will not Sync from Members Without Indexes Unless buildIndexes: false

To prevent inconsistency between members of replica sets, if the member of a replica set has buildIndexes set to true, other members of the replica set will not sync from this member, unless they also have buildIndexes set to true. See SERVER-4160 [https://jira.mongodb.org/browse/SERVER-4160] for more information.

New Option To Configure Index Pre-Fetching during Replication

By default, when replicating options, secondaries will pre-fetch Indexes associated with a query to improve replication throughput in most cases. The replication.secondaryIndexPrefetch setting and --replIndexPrefetch option allow administrators to disable this feature or allow the mongod to pre-fetch only the index on the _id field. See SERVER-6718 [https://jira.mongodb.org/browse/SERVER-6718] for more information.

Map Reduce Improvements

In 2.2 Map Reduce received the following improvements:

Improved support for sharded MapReduce [https://jira.mongodb.org/browse/SERVER-4521], and

MapReduce will retry jobs following a config error [https://jira.mongodb.org/browse/SERVER-4158].

Sharding Improvements

Index on Shard Keys Can Now Be a Compound Index

If your shard key uses the prefix of an existing index, then you do not need to maintain a separate index for your shard key in addition to your existing index. This index, however, cannot be a multi-key index. See the Shard Key Indexes documentation and SERVER-1506 [https://jira.mongodb.org/browse/SERVER-1506] for more information.

Migration Thresholds Modified

The migration thresholds have changed in 2.2 to permit more even distribution of chunks in collections that have smaller quantities of data. See the Migration Thresholds documentation for more information.

Licensing Changes

Added License notice for Google Perftools (TCMalloc Utility). See the License Notice [https://github.com/mongodb/mongo/blob/v2.2/distsrc/THIRD-PARTY-NOTICES#L231] and the SERVER-4683 [https://jira.mongodb.org/browse/SERVER-4683] for more information.

Resources

MongoDB Downloads [http://mongodb.org/downloads].

All JIRA issues resolved in 2.2 [https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+fixVersion+in+%28%222.1.0%22%2C+%222.1.1%22%2C+%222.1.2%22%2C+%222.2.0-rc0%22%2C+%222.2.0-rc1%22%2C+%222.2.0-rc2%22%29+ORDER+BY+component+ASC%2C+key+DESC].

All backwards incompatible changes [https://jira.mongodb.org/issues/?filter=11225&jql=project%20%3D%20SERVER%20AND%20fixVersion%20in%20(10483%2C%2010893%2C%2010894%2C%2010213)%20AND%20%22Backwards%20Compatibility%22%20in%20%20(%22Major%20Change%22%2C%20%22Minor%20Change%22)%20%20ORDER%20BY%20votes%20DESC%2C%20issuetype%20DESC%2C%20key%20DESC].

All third party license notices [https://github.com/mongodb/mongo/blob/v2.2/distsrc/THIRD-PARTY-NOTICES].

What’s New in MongoDB 2.2 Online Conference [http://www.mongodb.com/events/webinar/mongodb-online-conference-sept].

Release Notes for MongoDB 2.0

Upgrading

Although the major version number has changed, MongoDB 2.0 is a standard, incremental production release and works as a drop-in replacement for MongoDB 1.8.

Preparation

Read through all release notes before upgrading, and ensure that no changes will affect your deployment.

If you create new indexes in 2.0, then downgrading to 1.8 is possible but you must reindex the new collections.

mongoimport and mongoexport now correctly adhere to the CSV spec for handling CSV input/output. This may break existing import/export workflows that relied on the previous behavior. For more information see SERVER-1097 [https://jira.mongodb.org/browse/SERVER-1097].

Journaling is enabled by default in 2.0 for 64-bit builds. If you still prefer to run without journaling, start mongod with the --nojournal run-time option. Otherwise, MongoDB creates journal files during startup. The first time you start mongod with journaling, you will see a delay as mongod creates new files. In addition, you may see reduced write throughput.

2.0 mongod instances are interoperable with 1.8 mongod instances; however, for best results, upgrade your deployments using the following procedures:

Upgrading a Standalone mongod

Download the v2.0.x binaries from the MongoDB Download Page [http://downloads.mongodb.org/].

Shutdown your mongod instance. Replace the existing binary with the 2.0.x mongod binary and restart MongoDB.

Upgrading a Replica Set

Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 1.8 binary with the 2.0.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

To avoid losing the last few updates on failover you can temporarily halt your application (failover should take less than 10 seconds), or you can set write concern in your application code to confirm that each update reaches multiple servers.

Use the rs.stepDown() to step down the primary to allow the normal failover procedure.

rs.stepDown() and replSetStepDown provide for shorter and more consistent failover procedures than simply shutting down the primary directly.

When the primary has stepped down, shut down its instance and upgrade by replacing the mongod binary with the 2.0.x binary.

Upgrading a Sharded Cluster

Upgrade all config server instances first, in any order. Since config servers use two-phase commit, shard configuration metadata updates will halt until all are up and running.

Upgrade mongos routers in any order.

Changes

Compact Command

A compact command is now available for compacting a single collection and its indexes. Previously, the only way to compact was to repair the entire database.

Concurrency Improvements

When going to disk, the server will yield the write lock when writing data that is not likely to be in memory. The initial implementation of this feature now exists:

See SERVER-2563 [https://jira.mongodb.org/browse/SERVER-2563] for more information.

The specific operations yield in 2.0 are:

Updates by _id

Removes

Long cursor iterations

Default Stack Size

MongoDB 2.0 reduces the default stack size. This change can reduce total memory usage when there are many (e.g., 1000+) client connections, as there is a thread per connection. While portions of a thread’s stack can be swapped out if unused, some operating systems do this slowly enough that it might be an issue. The default stack size is lesser of the system setting or 1MB.

Index Performance Enhancements

v2.0 includes significant improvements to the index. Indexes are often 25% smaller and 25% faster (depends on the use case). When upgrading from previous versions, the benefits of the new index type are realized only if you create a new index or re-index an old one.

Dates are now signed, and the max index key size has increased slightly from 819 to 1024 bytes.

All operations that create a new index will result in a 2.0 index by default. For example:

Reindexing results on an older-version index results in a 2.0 index. However, reindexing on a secondary does not work in versions prior to 2.0. Do not reindex on a secondary. For a workaround, see SERVER-3866 [https://jira.mongodb.org/browse/SERVER-3866].

The repairDatabase command converts indexes to a 2.0 indexes.

To convert all indexes for a given collection to the 2.0 type, invoke the compact command.

Once you create new indexes, downgrading to 1.8.x will require a re-index of any indexes created using 2.0. See Build Old Style Indexes.

Sharding Authentication

Applications can now use authentication with sharded clusters.

Replica Sets

Hidden Nodes in Sharded Clusters

In 2.0, mongos instances can now determine when a member of a replica set becomes “hidden” without requiring a restart. In 1.8, mongos if you reconfigured a member as hidden, you had to restart mongos to prevent queries from reaching the hidden member.

Priorities

Each replica set member can now have a priority value consisting of a floating-point from 0 to 1000, inclusive. Priorities let you control which member of the set you prefer to have as primary the member with the highest priority that can see a majority of the set will be elected primary.

For example, suppose you have a replica set with three members, A, B, and C, and suppose that their priorities are set as follows:

A‘s priority is 2.

B‘s priority is 3.

C‘s priority is 1.

During normal operation, the set will always chose B as primary. If B becomes unavailable, the set will elect A as primary.

For more information, see the priority documentation.

Data-Center Awareness

You can now “tag” replica set members to indicate their location. You can use these tags to design custom write rules across data centers, racks, specific servers, or any other architecture choice.

For example, an administrator can define rules such as “very important write” or customerData or “audit-trail” to replicate to certain servers, racks, data centers, etc. Then in the application code, the developer would say:

db.foo.insert(doc, {w : "very important write"})

which would succeed if it fulfilled the conditions the DBA defined for “very important write”.

For more information, see Data Center Awareness.

Drivers may also support tag-aware reads. Instead of specifying slaveOk, you specify slaveOk with tags indicating which data-centers to read from. For details, see the Drivers [http://docs.mongodb.org/ecosystem/drivers] documentation.

w : majority

You can also set w to majority to ensure that the write propagates to a majority of nodes, effectively committing it. The value for “majority” will automatically adjust as you add or remove nodes from the set.

For more information, see Write Concern.

Reconfiguration with a Minority Up

If the majority of servers in a set has been permanently lost, you can now force a reconfiguration of the set to bring it back online.

For more information see Reconfigure a Replica Set with Unavailable Members.

Primary Checks for a Caught up Secondary before Stepping Down

To minimize time without a primary, the rs.stepDown() method will now fail if the primary does not see a secondary within 10 seconds of its latest optime. You can force the primary to step down anyway, but by default it will return an error message.

See also Force a Member to Become Primary.

Extended Shutdown on the Primary to Minimize Interruption

When you call the shutdown command, the primary will refuse to shut down unless there is a secondary whose optime is within 10 seconds of the primary. If such a secondary isn’t available, the primary will step down and wait up to a minute for the secondary to be fully caught up before shutting down.

Note that to get this behavior, you must issue the shutdown command explicitly; sending a signal to the process will not trigger this behavior.

You can also force the primary to shut down, even without an up-to-date secondary available.

Maintenance Mode

When repair or compact runs on a secondary, the secondary will automatically drop into “recovering” mode until the operation finishes. This prevents clients from trying to read from it while it’s busy.

Geospatial Features

Multi-Location Documents

Indexing is now supported on documents which have multiple location objects, embedded either inline or in embedded documents. Additional command options are also supported, allowing results to return with not only distance but the location used to generate the distance.

For more information, see Multi-location Documents for 2d Indexes.

Polygon searches

Polygonal $within queries are also now supported for simple polygon shapes. For details, see the $within operator documentation.

Journaling Enhancements

Journaling is now enabled by default for 64-bit platforms. Use the --nojournal command line option to disable it.

The journal is now compressed for faster commits to disk.

A new --journalCommitInterval run-time option exists for specifying your own group commit interval. The default settings do not change.

A new { getLastError: { j: true } } option is available to wait for the group commit. The group commit will happen sooner when a client is waiting on {j: true}. If journaling is disabled, {j: true} is a no-op.

New ContinueOnError Option for Bulk Insert

Set the continueOnError option for bulk inserts, in the driver, so that bulk insert will continue to insert any remaining documents even if an insert fails, as is the case with duplicate key exceptions or network interruptions. The getLastError command will report whether any inserts have failed, not just the last one. If multiple errors occur, the client will only receive the most recent getLastError results.

See OP_INSERT [http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol#op-insert].

Note

For bulk inserts on sharded clusters, the getLastError command alone is insufficient to verify success. Applications should must verify the success of bulk inserts in application logic.

Map Reduce

Output to a Sharded Collection

Using the new sharded flag, it is possible to send the result of a map/reduce to a sharded collection. Combined with the reduce or merge flags, it is possible to keep adding data to very large collections from map/reduce jobs.

For more information, see Map-Reduce and the mapReduce reference.

Performance Improvements

Map/reduce performance will benefit from the following:

Larger in-memory buffer sizes, reducing the amount of disk I/O needed during a job

Larger javascript heap size, allowing for larger objects and less GC

Supports pure JavaScript execution with the jsMode flag. See the mapReduce reference.

New Querying Features

Additional regex options: s

Allows the dot (.) to match all characters including new lines. This is in addition to the currently supported i, m and x. See $regex.

$and

A special boolean $and query operator is now available.

Command Output Changes

The output of the validate command and the documents in the system.profile collection have both been enhanced to return information as BSON objects with keys for each value rather than as free-form strings.

Shell Features

Custom Prompt

You can define a custom prompt for the mongo shell. You can change the prompt at any time by setting the prompt variable to a string or a custom JavaScript function returning a string. For examples, see Use a Custom Prompt.

Default Shell Init Script

On startup, the shell will check for a .mongorc.js file in the user’s home directory. The shell will execute this file after connecting to the database and before displaying the prompt.

If you would like the shell not to run the .mongorc.js file automatically, start the shell with --norc.

For more information, see the mongo reference.

Most Commands Require Authentication

In 2.0, when running with authentication (e.g. authorization) all database commands require authentication, except the following commands.

isMaster

authenticate

getnonce

buildInfo

ping

isdbgrid

Resources

MongoDB Downloads [http://mongodb.org/downloads]

All JIRA Issues resolved in 2.0 [https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=11002]

All Backward Incompatible Changes [https://jira.mongodb.org/issues/?filter=11023&jql=project%20%3D%20SERVER%20AND%20fixVersion%20in%20(10889%2C%2010886%2C%2010784%2C%2010596%2C%2010380%2C%2010261%2C%2010232)%20AND%20%22Backwards%20Compatibility%22%20in%20%20(%22Major%20Change%22%2C%20%22Minor%20Change%22)%20ORDER%20BY%20votes%20DESC%2C%20issuetype%20DESC%2C%20key%20DESC]

Release Notes for MongoDB 1.8

Upgrading

MongoDB 1.8 is a standard, incremental production release and works as a drop-in replacement for MongoDB 1.6, except:

Replica set members should be upgraded in a particular order, as described in Upgrading a Replica Set.

The mapReduce command has changed in 1.8, causing incompatibility with previous releases. mapReduce no longer generates temporary collections (thus, keepTemp has been removed). Now, you must always supply a value for out. See the out field options in the mapReduce document. If you use MapReduce, this also likely means you need a recent version of your client driver.

Preparation

Read through all release notes before upgrading and ensure that no changes will affect your deployment.

Upgrading a Standalone mongod

Download the v1.8.x binaries from the MongoDB Download Page [http://downloads.mongodb.org/].

Shutdown your mongod instance.

Replace the existing binary with the 1.8.x mongod binary.

Restart MongoDB.

Upgrading a Replica Set

1.8.x secondaries can replicate from 1.6.x primaries.

1.6.x secondaries cannot replicate from 1.8.x primaries.

Thus, to upgrade a replica set you must replace all of your secondaries first, then the primary.

For example, suppose you have a replica set with a primary, an arbiter and several secondaries. To upgrade the set, do the following:

For the arbiter:

Shut down the arbiter.

Restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

Change your config (optional) to prevent election of a new primary.

It is possible that, when you start shutting down members of the set, a new primary will be elected. To prevent this, you can give all of the secondaries a priority of 0 before upgrading, and then change them back afterwards. To do so:

Record your current config. Run rs.config() and paste the results into a text file.

Update your config so that all secondaries have priority 0. For example:

config = rs.conf()
{
     "_id" : "foo",
     "version" : 3,
     "members" : [
             {
                     "_id" : 0,
                     "host" : "ubuntu:27017"
             },
             {
                     "_id" : 1,
                     "host" : "ubuntu:27018"
             },
             {
                     "_id" : 2,
                     "host" : "ubuntu:27019",
                     "arbiterOnly" : true
             }
             {
                     "_id" : 3,
                     "host" : "ubuntu:27020"
             },
             {
                     "_id" : 4,
                     "host" : "ubuntu:27021"
             },
     ]
}
config.version++
3
rs.isMaster()
{
     "setName" : "foo",
     "ismaster" : false,
     "secondary" : true,
     "hosts" : [
             "ubuntu:27017",
             "ubuntu:27018"
     ],
     "arbiters" : [
             "ubuntu:27019"
     ],
     "primary" : "ubuntu:27018",
     "ok" : 1
}
// for each secondary
config.members[0].priority = 0
config.members[3].priority = 0
config.members[4].priority = 0
rs.reconfig(config)

For each secondary:

Shut down the secondary.

Restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

If you changed the config, change it back to its original state:

config = rs.conf()
config.version++
config.members[0].priority = 1
config.members[3].priority = 1
config.members[4].priority = 1
rs.reconfig(config)

Shut down the primary (the final 1.6 server), and then restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

Upgrading a Sharded Cluster

Turn off the balancer:

mongo <a_mongos_hostname>
use config
db.settings.update({_id:"balancer"},{$set : {stopped:true}}, true)

For each shard:

If the shard is a replica set, follow the directions above for Upgrading a Replica Set.

If the shard is a single mongod process, shut it down and then restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

For each mongos:

Shut down the mongos process.

Restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

For each config server:

Shut down the config server process.

Restart it with the 1.8.x binary from the MongoDB Download Page [http://downloads.mongodb.org/].

Turn on the balancer:

use config
db.settings.update({_id:"balancer"},{$set : {stopped:false}})

Returning to 1.6

If for any reason you must move back to 1.6, follow the steps above in reverse. Please be careful that you have not inserted any documents larger than 4MB while running on 1.8 (where the max size has increased to 16MB). If you have you will get errors when the server tries to read those documents.

Journaling

Returning to 1.6 after using 1.8 Journaling works fine, as journaling does not change anything about the data file format. Suppose you are running 1.8.x with journaling enabled and you decide to switch back to 1.6. There are two scenarios:

If you shut down cleanly with 1.8.x, just restart with the 1.6 mongod binary.

If 1.8.x shut down uncleanly, start 1.8.x up again and let the journal files run to fix any damage (incomplete writes) that may have existed at the crash. Then shut down 1.8.x cleanly and restart with the 1.6 mongod binary.

Changes

Journaling

MongoDB now supports write-ahead Journaling Mechanics to facilitate fast crash recovery and durability in the storage engine. With journaling enabled, a mongod can be quickly restarted following a crash without needing to repair the collections. The aggregation framework makes it possible to do aggregation

Sparse and Covered Indexes

Sparse Indexes are indexes that only include documents that contain the fields specified in the index. Documents missing the field will not appear in the index at all. This can significantly reduce index size for indexes of fields that contain only a subset of documents within a collection.

Covered Indexes enable MongoDB to answer queries entirely from the index when the query only selects fields that the index contains.

Incremental MapReduce Support

The mapReduce command supports new options that enable incrementally updating existing collections. Previously, a MapReduce job could output either to a temporary collection or to a named permanent collection, which it would overwrite with new data.

You now have several options for the output of your MapReduce jobs:

You can merge MapReduce output into an existing collection. Output from the Reduce phase will replace existing keys in the output collection if it already exists. Other keys will remain in the collection.

You can now re-reduce your output with the contents of an existing collection. Each key output by the reduce phase will be reduced with the existing document in the output collection.

You can replace the existing output collection with the new results of the MapReduce job (equivalent to setting a permanent output collection in previous releases)

You can compute MapReduce inline and return results to the caller without persisting the results of the job. This is similar to the temporary collections generated in previous releases, except results are limited to 8MB.

For more information, see the out field options in the mapReduce document.

Additional Changes and Enhancements

1.8.1

Sharding migrate fix when moving larger chunks.

Durability fix with background indexing.

Fixed mongos concurrency issue with many incoming connections.

1.8.0

All changes from 1.7.x series.

1.7.6

Bug fixes.

1.7.5

Journaling.

Extent allocation improvements.

Improved replica set connectivity for mongos.

getLastError improvements for sharding.

1.7.4

mongos routes slaveOk queries to secondaries in replica sets.

New mapReduce output options.

Sparse Indexes.

1.7.3

Initial covered index support.

Distinct can use data from indexes when possible.

mapReduce can merge or reduce results into an existing collection.

mongod tracks and mongostat displays network usage. See mongostat.

Sharding stability improvements.

1.7.2

$rename operator allows renaming of fields in a document.

db.eval() not to block.

Geo queries with sharding.

mongostat --discover option

Chunk splitting enhancements.

Replica sets network enhancements for servers behind a nat.

1.7.1

Many sharding performance enhancements.

Better support for $elemMatch on primitives in embedded arrays.

Query optimizer enhancements on range queries.

Window service enhancements.

Replica set setup improvements.

$pull works on primitives in arrays.

1.7.0

Sharding performance improvements for heavy insert loads.

Slave delay support for replica sets.

getLastErrorDefaults for replica sets.

Auto completion in the shell.

Spherical distance for geo search.

All fixes from 1.6.1 and 1.6.2.

Release Announcement Forum Pages

1.8.1 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/v09MbhEm62Y], 1.8.0 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/JeHQOnam6Qk]

1.7.6 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/3t6GNZ1qGYc], 1.7.5 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/S5R0Tx9wkEg], 1.7.4 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/9Om3Vuw-y9c], 1.7.3 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/DfNUrdbmflI], 1.7.2 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/df7mwK6Xixo], 1.7.1 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/HUR9zYtTpA8], 1.7.0 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/TUnJCg9161A]

Resources

MongoDB Downloads [http://mongodb.org/downloads]

All JIRA Issues resolved in 1.8 [https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=10172]

Release Notes for MongoDB 1.6

Upgrading

MongoDB 1.6 is a drop-in replacement for 1.4. To upgrade, simply shutdown mongod then restart with the new binaries.

Please note that you should upgrade to the latest version of whichever driver you’re using. Certain drivers, including the Ruby driver, will require the upgrade, and all the drivers will provide extra features for connecting to replica sets.

Sharding

Sharding is now production-ready, making MongoDB horizontally scalable, with no single point of failure. A single instance of mongod can now be upgraded to a distributed cluster with zero downtime when the need arises.

Sharding

Deploy a Sharded Cluster

Convert a Replica Set to a Replicated Sharded Cluster

Replica Sets

Replica sets, which provide automated failover among a cluster of n nodes, are also now available.

Please note that replica pairs are now deprecated; we strongly recommend that replica pair users upgrade to replica sets.

Replication

Deploy a Replica Set

Convert a Standalone to a Replica Set

Other Improvements

The w option (and wtimeout) forces writes to be propagated to n servers before returning success (this works especially well with replica sets)

$or queries

Improved concurrency

$slice operator for returning subsets of arrays

64 indexes per collection (formerly 40 indexes per collection)

64-bit integers can now be represented in the shell using NumberLong

The findAndModify command now supports upserts. It also allows you to specify fields to return

$showDiskLoc option to see disk location of a document

Support for IPv6 and UNIX domain sockets

Installation

Windows service improvements

The C++ client is a separate tarball from the binaries

1.6.x Release Notes

1.6.5 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/06_QCC05Fpk]

1.5.x Release Notes

1.5.8 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/uJfF1QN6Thk]

1.5.7 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/OYvz40RWs90]

1.5.6 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/4l0N2U_H0cQ]

1.5.5 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/oO749nvTARY]

1.5.4 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/380V_Ec_q1c]

1.5.3 [https://groups.google.com/forum/?hl=en&fromgroups=#!topic/mongodb-user/hsUQL9CxTQw]

1.5.2 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/94EE3HVidAA]

1.5.1 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/7SBPQ2RSfdM]

1.5.0 [https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/VAhJcjDGTy0]

You can see a full list of all changes on JIRA [https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=10107].

Thank you everyone for your support and suggestions!

Release Notes for MongoDB 1.4

Upgrading

We’re pleased to announce the 1.4 release of MongoDB. 1.4 is a drop-in replacement for 1.2. To upgrade you just need to shutdown mongod, then restart with the new binaries. (Users upgrading from release 1.0 should review the 1.2 release notes, in particular the instructions for upgrading the DB format.)

Release 1.4 includes the following improvements over release 1.2:

Core Server Enhancements

concurrency improvements

indexing memory improvements

background index creation

better detection of regular expressions so the index can be used in more cases

Replication and Sharding

better handling for restarting slaves offline for a while

fast new slaves from snapshots (--fastsync)

configurable slave delay (--slavedelay)

replication handles clock skew on master

$inc replication fixes

sharding alpha 3 - notably 2-phase commit on config servers

Deployment and Production

configure “slow threshold” for profiling

ability to do fsync + lock for backing up raw files

option for separate directory per db (--directoryperdb)

http://localhost:28017/_status to get serverStatus via http

REST interface is off by default for security (--rest to enable)

can rotate logs with a db command, logRotate

enhancements to serverStatus command (db.serverStatus()) - counters and replication lag stats

new mongostat tool

Query Language Improvements

$all with regex

$not

partial matching of array elements $elemMatch

$ operator for updating arrays

$addToSet

$unset

$pull supports object matching

$set with array indexes

Geo

2d geospatial search

geo $center and $box searches

Release Notes for MongoDB 1.2.x

New Features

More indexes per collection

Faster index creation

Map/Reduce

Stored JavaScript functions

Configurable fsync time

Several small features and fixes

DB Upgrade Required

There are some changes that will require doing an upgrade if your previous version is <= 1.0.x. If you’re already using a version >= 1.1.x then these changes aren’t required. There are 2 ways to do it:

--upgrade

stop your mongod process

run ./mongod --upgrade

start mongod again

use a slave

start a slave on a different port and data directory

when its synced, shut down the master, and start the new slave on the regular port.

Ask in the forums or IRC for more help.

Replication Changes

There have been minor changes in replication. If you are upgrading a master/slave setup from <= 1.1.2 you have to update the slave first.

mongoimport

mongoimportjson has been removed and is replaced with mongoimport that can do json/csv/tsv

field filter changing

We’ve changed the semantics of the field filter a little bit. Previously only objects with those fields would be returned. Now the field filter only changes the output, not which objects are returned. If you need that behavior, you can use $exists

Default Write Concern Change

These release notes outline a change to all driver interfaces released in November 2012. See release notes for specific drivers for additional information.

Changes

As of the releases listed below, there are two major changes to all drivers:

All drivers will add a new top-level connection class that will increase consistency for all MongoDB client interfaces.

This change is non-backward breaking: existing connection classes will remain in all drivers for a time, and will continue to operate as expected. However, those previous connection classes are now deprecated as of these releases, and will eventually be removed from the driver interfaces.

The new top-level connection class is named MongoClient, or similar depending on how host languages handle namespacing.

The default write concern on the new MongoClient class will be to acknowledge all write operations [1]. This will allow your application to receive acknowledgment of all write operations.

See the documentation of Write Concern for more information about write concern in MongoDB.

Please migrate to the new MongoClient class expeditiously.

[1]
The drivers will call getLastError without arguments, which is logically equivalent to the w: 1 option; however, this operation allows replica set users to override the default write concern with the getLastErrorDefaults setting in the Replica Set Configuration.

Releases

The following driver releases will include the changes outlined in Changes. See each driver’s release notes for a full account of each release as well as other related driver-specific changes.

C#, version 1.7

Java, version 2.10.0

Node.js, version 1.2

Perl, version 0.501.1

PHP, version 1.4

Python, version 2.4

Ruby, version 1.8

Index

Symbols | _ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W

Symbols

$ (projection operator)

(update operator)

$add (aggregation framework transformation expression)

$addToSet (aggregation framework group expression)

(update operator)

$all (query)

$allElementsTrue (aggregation framework transformation expression)

$and (aggregation framework transformation expression)

(query)

$anyElementTrue (aggregation framework transformation expression)

$atomic (update operator)

$avg (aggregation framework group expression)

$bit (update operator)

$box (query)

$center (query)

$centerSphere (query)

$cmd

$cmp (aggregation framework transformation expression)

$comment (operator)

(query)

$concat (aggregation framework transformation expression)

$cond (aggregation framework transformation expression)

$currentDate (update operator)

$dayOfMonth (aggregation framework transformation expression)

$dayOfWeek (aggregation framework transformation expression)

$dayOfYear (aggregation framework transformation expression)

$divide (aggregation framework transformation expression)

$each (update operator)

$elemMatch (projection operator)

(query)

$eq (aggregation framework transformation expression)

$exists (query)

$explain (operator)

$first (aggregation framework group expression)

$geoIntersects (query)

$geometry (query)

$geoNear (aggregation framework pipeline operator)

$geoWithin (query)

$group (aggregation framework pipeline operator)

$gt (aggregation framework transformation expression)

(query)

$gte (aggregation framework transformation expression)

(query)

$hint (operator)

$hour (aggregation framework transformation expression)

$ifNull (aggregation framework transformation expression)

$in (query)

$inc (update operator)

$isolated (update operator)

$last (aggregation framework group expression)

$let (aggregation framework transformation expression)

$limit (aggregation framework pipeline operator)

$literal (aggregation framework transformation expression)

$lt (aggregation framework transformation expression)

(query)

$lte (aggregation framework transformation expression)

(query)

$map (aggregation framework transformation expression)

$match (aggregation framework pipeline operator)

$max (aggregation framework group expression)

(operator)

(update operator)

$maxDistance (query)

$maxScan (operator)

$maxTimeMS (operator)

$meta (aggregation framework transformation expression)

(projection operator)

$millisecond (aggregation framework transformation expression)

$min (aggregation framework group expression)

(operator)

(update operator)

$minDistance (query)

$minute (aggregation framework transformation expression)

$mod (aggregation framework transformation expression)

(query)

$month (aggregation framework transformation expression)

$mul (update operator)

$multiply (aggregation framework transformation expression)

$natural (operator)

$ne (aggregation framework transformation expression)

(query)

$near (query)

$nearSphere (query)

$nin (query)

$nor (query)

$not (aggregation framework transformation expression)

(query)

$options (query)

$or (aggregation framework transformation expression)

(query)

$orderby (query)

$out (aggregation framework pipeline operator)

$polygon (query)

$pop (update operator)

$position (update operator)

$project (aggregation framework pipeline operator)

$pull (update operator)

$pullAll (update operator)

$push (aggregation framework group expression)

(update operator)

$pushAll (update operator)

$query (operator)

$redact (aggregation framework pipeline operator)

$regex (query)

$rename (update operator)

$returnKey (operator)

$second (aggregation framework transformation expression)

$set (update operator)

$setDifference (aggregation framework transformation expression)

$setEquals (aggregation framework transformation expression)

$setIntersection (aggregation framework transformation expression)

$setIsSubset (aggregation framework transformation expression)

$setOnInsert (update operator)

$setUnion (aggregation framework transformation expression)

$showDiskLoc (operator)

$size (aggregation framework transformation expression)

(query)

$skip (aggregation framework pipeline operator)

$slice (projection operator)

(update operator)

$snapshot (operator)

$sort (aggregation framework pipeline operator)

(update operator)

$strcasecmp (aggregation framework transformation expression)

$substr (aggregation framework transformation expression)

$subtract (aggregation framework transformation expression)

$sum (aggregation framework group expression)

$text (query)

$toLower (aggregation framework transformation expression)

$toUpper (aggregation framework transformation expression)

$type (query)

$uniqueDocs (query)

$unset (update operator)

$unwind (aggregation framework pipeline operator)

$week (aggregation framework transformation expression)

$where (query)

$within (query)

$year (aggregation framework transformation expression)

--all

command line option

--auditDestination

command line option, [1]

--auditFilter

command line option, [1]

--auditFormat

command line option, [1]

--auditPath

command line option, [1]

--auth

command line option

--authenticationDatabase <dbname>

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--authenticationMechanism <name>

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--autoresync

command line option

--bind_ip <ip address>

command line option, [1]

--chunkSize <value>

command line option

--clusterAuthMode <option>

command line option, [1]

--collection <collection>, -c <collection>

command line option, [1], [2], [3], [4], [5]

--config <filename>, -f <filename>

command line option, [1]

--configdb <config1>,<config2>,<config3>

command line option

--configsvr

command line option

--cpu

command line option

--csv

command line option

--db <database>, -d <database>

command line option, [1], [2], [3], [4], [5]

--dbpath <path>

command line option, [1], [2], [3], [4], [5], [6]

--diaglog <value>

command line option

--directoryperdb

command line option, [1], [2], [3], [4], [5], [6]

--discover

command line option

--drop

command line option, [1]

--dumpDbUsersAndRoles

command line option

--eval <javascript>

command line option

--fastsync

command line option

--fieldFile <filename>

command line option, [1]

--fields <field1[,field2]>, -f <field1[,field2]>

command line option, [1]

--file <filename>

command line option

--filter <JSON>

command line option, [1]

--forceTableScan

command line option, [1]

--fork

command line option, [1]

--forward <host><:port>

command line option

--from <host[:port]>

command line option

--gssapiHostName

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--gssapiServiceName

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--headerline

command line option

--help

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9]

--help, -h

command line option, [1], [2], [3]

--host <hostname>

command line option

--host <hostname><:port>

command line option

--host <hostname><:port>, -h <hostname><:port>

command line option, [1], [2], [3], [4], [5], [6]

--http

command line option

--httpinterface

command line option, [1]

--ignoreBlanks

command line option

--install

command line option, [1]

--ipv6

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--journal

command line option, [1], [2], [3], [4], [5], [6]

--journalCommitInterval <value>

command line option

--journalOptions <arguments>

command line option

--jsonArray

command line option, [1]

--jsonp

command line option, [1]

--keepIndexVersion

command line option

--keyFile <file>

command line option, [1]

--limit <number>

command line option

--local <filename>, -l <filename>

command line option

--localThreshold

command line option

--locks

command line option

--logappend

command line option, [1]

--logpath <path>

command line option, [1]

--master

command line option

--maxConns <number>

command line option, [1]

--noauth

command line option

--noAutoSplit

command line option

--nodb

command line option

--noheaders

command line option

--nohttpinterface

command line option

--noIndexBuildRetry

command line option

--noIndexRestore

command line option

--nojournal

command line option

--noobjcheck

command line option, [1], [2]

--noOptionsRestore

command line option

--noprealloc

command line option

--norc

command line option

--noscripting

command line option, [1]

--notablescan

command line option

--nounixsocket

command line option, [1]

--nssize <value>

command line option

--objcheck

command line option, [1], [2], [3]

--only <arg>

command line option

--oplog

command line option

--oplogLimit <timestamp>

command line option

--oplogns <namespace>

command line option

--oplogReplay

command line option

--oplogSize <value>

command line option

--out <file>, -o <file>

command line option

--out <path>, -o <path>

command line option

--password <password>, -p <password>

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--pidfilepath <path>

command line option, [1]

--port

command line option

--port <port>

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9]

--profile <level>

command line option

--query <JSON>, -q <JSON>

command line option

--query <json>, -q <json>

command line option

--quiet

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--quota

command line option

--quotaFiles <number>

command line option

--reinstall

command line option, [1]

--remove

command line option, [1]

--repair

command line option, [1]

--repairpath <path>

command line option

--replace, -r

command line option

--replIndexPrefetch

command line option

--replSet <setname>

command line option

--rest

command line option

--restoreDbUsersAndRoles

command line option

--rowcount <number>, -n <number>

command line option

--seconds <number>, -s <number>

command line option

--serviceDescription <description>

command line option, [1]

--serviceDisplayName <name>

command line option, [1]

--serviceName name

command line option, [1]

--servicePassword <password>

command line option, [1]

--serviceUser <user>

command line option, [1]

--setParameter <options>

command line option, [1]

--shardsvr

command line option

--shell

command line option

--shutdown

command line option

--skip <number>

command line option

--slave

command line option

--slavedelay <value>

command line option

--slaveOk, -k

command line option

--slowms <integer>

command line option

--smallfiles

command line option

--snmp-master

command line option

--snmp-subagent

command line option

--sort <JSON>

command line option

--source <host><:port>

command line option

--source <NET [interface]>, <FILE [filename]>, <DIAGLOG [filename]>

command line option

--ssl

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--sslAllowInvalidCertificates

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslCAFile <filename>

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslClusterFile <filename>

command line option, [1]

--sslClusterPassword <value>

command line option, [1]

--sslCRLFile <filename>

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslFIPSMode

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslMode <mode>

command line option, [1]

--sslOnNormalPorts

command line option, [1]

--sslPEMKeyFile <filename>

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslPEMKeyPassword <value>

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslWeakCertificateValidation

command line option, [1]

--stopOnError

command line option

--syncdelay <value>

command line option

--sysinfo

command line option

--syslog

command line option, [1]

--syslogFacility <string>

command line option, [1]

--timeStampFormat <string>

command line option, [1]

--traceExceptions

command line option

--type <=json|=debug>

command line option

--type <json|csv|tsv>

command line option

--type <MIME>

command line option

--unixSocketPrefix <path>

command line option, [1]

--upgrade

command line option, [1]

--upsert

command line option

--upsertFields <field1[,field2]>

command line option

--username <username>, -u <username>

command line option, [1], [2], [3], [4], [5], [6], [7], [8]

--verbose

command line option

--verbose, -v

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--version

command line option, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

--w <number of replicas per write>

command line option

0 (error code)

100 (error code)

12 (error code)

14 (error code)

2 (error code)

20 (error code)

2d Geospatial queries cannot use the $or operator (MongoDB system limit)

3 (error code)

4 (error code)

45 (error code)

47 (error code)

48 (error code)

49 (error code)

5 (error code)

<database>.system.indexes (MongoDB reporting output)

<database>.system.js (MongoDB reporting output)

<database>.system.namespaces (MongoDB reporting output)

<database>.system.profile (MongoDB reporting output)

_

__system (user role)

_hashBSONElement (database command)

_hashBSONElement.key (MongoDB reporting output)

_hashBSONElement.ok (MongoDB reporting output)

_hashBSONElement.out (MongoDB reporting output)

_hashBSONElement.seed (MongoDB reporting output)

_id, [1]

_id index

_isSelf (database command)

_isWindows (shell method)

_migrateClone (database command)

_rand (shell method)

_recvChunkAbort (database command)

_recvChunkCommit (database command)

_recvChunkStart (database command)

_recvChunkStatus (database command)

_skewClockCommand (database command)

_srand (shell method)

_startMongoProgram (shell method)

_testDistLockWithSkew (database command)

_testDistLockWithSyncCluster (database command)

_transferMods (database command)

A

accumulator

action

addShard (database command)

(user action)

admin database

admin.system.roles (MongoDB reporting output)

admin.system.roles.db (MongoDB reporting output)

admin.system.roles.privileges (MongoDB reporting output)

admin.system.roles.privileges[n].actions (MongoDB reporting output)

admin.system.roles.privileges[n].resource (MongoDB reporting output)

admin.system.roles.role (MongoDB reporting output)

admin.system.roles.roles (MongoDB reporting output)

admin.system.roles.roles[n].db (MongoDB reporting output)

admin.system.roles.roles[n].role (MongoDB reporting output)

admin.system.users (MongoDB reporting output)

admin.system.users.credentials (MongoDB reporting output)

admin.system.users.customData (MongoDB reporting output)

admin.system.users.db (MongoDB reporting output)

admin.system.users.roles (MongoDB reporting output)

admin.system.users.roles[n].db (MongoDB reporting output)

admin.system.users.roles[n].role (MongoDB reporting output)

admin.system.users.user (MongoDB reporting output)

admin.system.version (MongoDB reporting output)

administration tutorials

aggregate (database command)

aggregation

aggregation framework

Aggregation Pipeline Operation (MongoDB system limit)

anyAction (user action)

appendOplogNote (user action)

applicationMessage (user action)

applyOps (database command)

arbiter

ARBITER (replica set state)

Area of GeoJSON Polygons (MongoDB system limit)

auditAuthorizationSuccess (setParameter option)

auditLog (setting)

auditLog.destination (setting)

auditLog.filter (setting)

auditLog.format (setting)

auditLog.path (setting)

authenticate (database command)

authentication

authenticationMechanisms (setParameter option)

authorization

authSchemaUpgrade (database command)

(user action)

availableQueryOptions (database command)

B

B-tree

backup (user role)

balancer

balancing

configure

internals

migration

operations

secondary throttle

batchType (MongoDB reporting output)

BSON

BSON Document Size (MongoDB system limit)

BSON types

bsondump (program), [1]

buildInfo (database command)

(MongoDB reporting output)

buildInfo.allocator (MongoDB reporting output)

buildInfo.bits (MongoDB reporting output)

buildInfo.compilerFlags (MongoDB reporting output)

buildInfo.debug (MongoDB reporting output)

buildInfo.gitVersion (MongoDB reporting output)

buildInfo.javascriptEngine (MongoDB reporting output)

buildInfo.loaderFlags (MongoDB reporting output)

buildInfo.maxBsonObjectSize (MongoDB reporting output)

buildInfo.sysInfo (MongoDB reporting output)

buildInfo.versionArray (MongoDB reporting output)

Bulk (shell method)

Bulk.execute (shell method)

Bulk.find (shell method)

Bulk.find.remove (shell method)

Bulk.find.removeOne (shell method)

Bulk.find.replaceOne (shell method)

Bulk.find.update (shell method)

Bulk.find.updateOne (shell method)

Bulk.find.upsert (shell method)

Bulk.getOperations (shell method)

Bulk.insert (shell method)

Bulk.tojson (shell method)

Bulk.toString (shell method)

BulkWriteResult (shell method)

BulkWriteResult.nInserted (MongoDB reporting output)

BulkWriteResult.nMatched (MongoDB reporting output)

BulkWriteResult.nModified (MongoDB reporting output)

BulkWriteResult.nRemoved (MongoDB reporting output)

BulkWriteResult.nUpserted (MongoDB reporting output)

BulkWriteResult.upserted (MongoDB reporting output)

BulkWriteResult.upserted._id (MongoDB reporting output)

BulkWriteResult.upserted.index (MongoDB reporting output)

BulkWriteResult.writeConcernError (MongoDB reporting output)

BulkWriteResult.writeConcernError.code (MongoDB reporting output)

BulkWriteResult.writeConcernError.errInfo (MongoDB reporting output)

BulkWriteResult.writeConcernError.errmsg (MongoDB reporting output)

BulkWriteResult.writeErrors (MongoDB reporting output)

BulkWriteResult.writeErrors.code (MongoDB reporting output)

BulkWriteResult.writeErrors.errmsg (MongoDB reporting output)

BulkWriteResult.writeErrors.index (MongoDB reporting output)

BulkWriteResult.writeErrors.op (MongoDB reporting output)

C

CAP Theorem

capped collection

captrunc (database command)

cat (shell method)

cd (shell method)

changeCustomData (user action)

changeOwnCustomData (user action)

changeOwnPassword (user action)

changePassword (user action)

checkShardingIndex (database command)

checksum

chunk

chunks._id (MongoDB reporting output)

chunks.data (MongoDB reporting output)

chunks.files_id (MongoDB reporting output)

chunks.n (MongoDB reporting output)

clean (database command)

cleanupOrphaned (database command)

(user action)

cleanupOrphaned.ok (MongoDB reporting output)

cleanupOrphaned.stoppedAtKey (MongoDB reporting output)

clearRawMongoProgramOutput (shell method)

client

clone (database command)

cloneCollection (database command)

cloneCollectionAsCapped (database command)

closeAllDatabases (database command)

(user action)

cluster

clusterAdmin (user role)

clusterAuthMode (setParameter option)

clusterManager (user role)

clusterMonitor (user role)

collection

system

collection scan

collMod (database command)

(user action)

collStats (database command)

(user action)

collStats.avgObjSize (MongoDB reporting output)

collStats.capped (MongoDB reporting output)

collStats.count (MongoDB reporting output)

collStats.flags (MongoDB reporting output)

collStats.indexSizes (MongoDB reporting output)

collStats.lastExtentSize (MongoDB reporting output)

collStats.max (MongoDB reporting output)

collStats.nindexes (MongoDB reporting output)

collStats.ns (MongoDB reporting output)

collStats.numExtents (MongoDB reporting output)

collStats.paddingFactor (MongoDB reporting output)

collStats.size (MongoDB reporting output)

collStats.storageSize (MongoDB reporting output)

collStats.systemFlags (MongoDB reporting output)

collStats.totalIndexSize (MongoDB reporting output)

collStats.userFlags (MongoDB reporting output)

command line option

--all

--auditDestination, [1]

--auditFilter, [1]

--auditFormat, [1]

--auditPath, [1]

--auth

--authenticationDatabase <dbname>, [1], [2], [3], [4], [5], [6], [7], [8]

--authenticationMechanism <name>, [1], [2], [3], [4], [5], [6], [7], [8]

--autoresync

--bind_ip <ip address>, [1]

--chunkSize <value>

--clusterAuthMode <option>, [1]

--collection <collection>, -c <collection>, [1], [2], [3], [4], [5]

--config <filename>, -f <filename>, [1]

--configdb <config1>,<config2>,<config3>

--configsvr

--cpu

--csv

--db <database>, -d <database>, [1], [2], [3], [4], [5]

--dbpath <path>, [1], [2], [3], [4], [5], [6]

--diaglog <value>

--directoryperdb, [1], [2], [3], [4], [5], [6]

--discover

--drop, [1]

--dumpDbUsersAndRoles

--eval <javascript>

--fastsync

--fieldFile <filename>, [1]

--fields <field1[,field2]>, -f <field1[,field2]>, [1]

--file <filename>

--filter <JSON>, [1]

--forceTableScan, [1]

--fork, [1]

--forward <host><:port>

--from <host[:port]>

--gssapiHostName, [1], [2], [3], [4], [5], [6], [7], [8]

--gssapiServiceName, [1], [2], [3], [4], [5], [6], [7], [8]

--headerline

--help, [1], [2], [3], [4], [5], [6], [7], [8], [9]

--help, -h, [1], [2], [3]

--host <hostname>

--host <hostname><:port>

--host <hostname><:port>, -h <hostname><:port>, [1], [2], [3], [4], [5], [6]

--http

--httpinterface, [1]

--ignoreBlanks

--install, [1]

--ipv6, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--journal, [1], [2], [3], [4], [5], [6]

--journalCommitInterval <value>

--journalOptions <arguments>

--jsonArray, [1]

--jsonp, [1]

--keepIndexVersion

--keyFile <file>, [1]

--limit <number>

--local <filename>, -l <filename>

--localThreshold

--locks

--logappend, [1]

--logpath <path>, [1]

--master

--maxConns <number>, [1]

--noAutoSplit

--noIndexBuildRetry

--noIndexRestore

--noOptionsRestore

--noauth

--nodb

--noheaders

--nohttpinterface

--nojournal

--noobjcheck, [1], [2]

--noprealloc

--norc

--noscripting, [1]

--notablescan

--nounixsocket, [1]

--nssize <value>

--objcheck, [1], [2], [3]

--only <arg>

--oplog

--oplogLimit <timestamp>

--oplogReplay

--oplogSize <value>

--oplogns <namespace>

--out <file>, -o <file>

--out <path>, -o <path>

--password <password>, -p <password>, [1], [2], [3], [4], [5], [6], [7], [8]

--pidfilepath <path>, [1]

--port

--port <port>, [1], [2], [3], [4], [5], [6], [7], [8], [9]

--profile <level>

--query <JSON>, -q <JSON>

--query <json>, -q <json>

--quiet, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--quota

--quotaFiles <number>

--reinstall, [1]

--remove, [1]

--repair, [1]

--repairpath <path>

--replIndexPrefetch

--replSet <setname>

--replace, -r

--rest

--restoreDbUsersAndRoles

--rowcount <number>, -n <number>

--seconds <number>, -s <number>

--serviceDescription <description>, [1]

--serviceDisplayName <name>, [1]

--serviceName name, [1]

--servicePassword <password>, [1]

--serviceUser <user>, [1]

--setParameter <options>, [1]

--shardsvr

--shell

--shutdown

--skip <number>

--slave

--slaveOk, -k

--slavedelay <value>

--slowms <integer>

--smallfiles

--snmp-master

--snmp-subagent

--sort <JSON>

--source <NET [interface]>, <FILE [filename]>, <DIAGLOG [filename]>

--source <host><:port>

--ssl, [1], [2], [3], [4], [5], [6], [7], [8]

--sslAllowInvalidCertificates, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslCAFile <filename>, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslCRLFile <filename>, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslClusterFile <filename>, [1]

--sslClusterPassword <value>, [1]

--sslFIPSMode, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslMode <mode>, [1]

--sslOnNormalPorts, [1]

--sslPEMKeyFile <filename>, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslPEMKeyPassword <value>, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--sslWeakCertificateValidation, [1]

--stopOnError

--syncdelay <value>

--sysinfo

--syslog, [1]

--syslogFacility <string>, [1]

--timeStampFormat <string>, [1]

--traceExceptions

--type <=json|=debug>

--type <MIME>

--type <json|csv|tsv>

--unixSocketPrefix <path>, [1]

--upgrade, [1]

--upsert

--upsertFields <field1[,field2]>

--username <username>, -u <username>, [1], [2], [3], [4], [5], [6], [7], [8]

--verbose

--verbose, -v, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

--version, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

--w <number of replicas per write>

compact (database command)

(user action)

compound index, [1]

config

(MongoDB reporting output)

config database

config databases

config server

config servers

config.changelog (MongoDB reporting output)

config.changelog._id (MongoDB reporting output)

config.changelog.clientAddr (MongoDB reporting output)

config.changelog.details (MongoDB reporting output)

config.changelog.ns (MongoDB reporting output)

config.changelog.server (MongoDB reporting output)

config.changelog.time (MongoDB reporting output)

config.changelog.what (MongoDB reporting output)

config.chunks (MongoDB reporting output)

config.collections (MongoDB reporting output)

config.databases (MongoDB reporting output)

config.lockpings (MongoDB reporting output)

config.locks (MongoDB reporting output)

config.mongos (MongoDB reporting output)

config.settings (MongoDB reporting output)

config.shards (MongoDB reporting output)

config.tags (MongoDB reporting output)

config.version (MongoDB reporting output)

configureFailPoint (database command)

connect (shell method)

connection pooling

read operations

connections

connection string format

options

connectionStatus (database command)

connectionStatus.authInfo (MongoDB reporting output)

connectionStatus.authinfo.authenticatedUserRoles (MongoDB reporting output)

connectionStatus.authinfo.authenticatedUserRoles[n].db (MongoDB reporting output)

connectionStatus.authinfo.authenticatedUserRoles[n].role (MongoDB reporting output)

connectionStatus.authinfo.authenticatedUsers (MongoDB reporting output)

connectionStatus.authInfo.authenticatedUsers[n].db (MongoDB reporting output)

connectionStatus.authInfo.authenticatedUsers[n].user (MongoDB reporting output)

connectionStatus.ok (MongoDB reporting output)

connPoolMaxConnectionsPerHost (setParameter option)

connPoolMaxShardedConnectionsPerHost (setParameter option)

connPoolStats (database command)

(user action)

connPoolStats.createdByType (MongoDB reporting output)

connPoolStats.createdByType.master (MongoDB reporting output)

connPoolStats.createdByType.set (MongoDB reporting output)

connPoolStats.createdByType.sync (MongoDB reporting output)

connPoolStats.hosts (MongoDB reporting output)

connPoolStats.hosts.[host].available (MongoDB reporting output)

connPoolStats.hosts.[host].created (MongoDB reporting output)

connPoolStats.numAScopedConnection (MongoDB reporting output)

connPoolStats.numDBClientConnection (MongoDB reporting output)

connPoolStats.replicaSets (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].addr (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].hidden (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].ismaster (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].ok (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].pingTimeMillis (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].secondary (MongoDB reporting output)

connPoolStats.replicaSets.[shard].host[n].tags (MongoDB reporting output)

connPoolStats.replicaSets.[shard].master (MongoDB reporting output)

connPoolStats.replicaSets.[shard].nextSlave (MongoDB reporting output)

connPoolStats.replicaSets.shard (MongoDB reporting output)

connPoolStats.totalAvailable (MongoDB reporting output)

connPoolStats.totalCreated (MongoDB reporting output)

connPoolSync (database command)

(user action)

consistency

rollbacks

control script

convertToCapped (database command)

(user action)

copydb (database command)

copydbgetnonce (database command)

copyDbpath (shell method)

count (database command)

Covered Queries in Sharded Clusters (MongoDB system limit)

cpuProfiler (user action)

create (database command)

createCollection (user action)

createIndex (user action)

createIndexes (database command)

createIndexes.code (MongoDB reporting output)

createIndexes.createdCollectionAutomatically (MongoDB reporting output)

createIndexes.errmsg (MongoDB reporting output)

createIndexes.note (MongoDB reporting output)

createIndexes.numIndexesAfter (MongoDB reporting output)

createIndexes.numIndexesBefore (MongoDB reporting output)

createIndexes.ok (MongoDB reporting output)

createRole (database command)

(user action)

createUser (database command)

(user action)

crud

write operations

CRUD

CSV

CURRENT (system variable available in aggregation)

currentOp.active (MongoDB reporting output)

currentOp.client (MongoDB reporting output)

currentOp.connectionId (MongoDB reporting output)

currentOp.desc (MongoDB reporting output)

currentOp.insert (MongoDB reporting output)

currentOp.killPending (MongoDB reporting output)

currentOp.locks (MongoDB reporting output)

currentOp.locks.^ (MongoDB reporting output)

currentOp.locks.^<database> (MongoDB reporting output)

currentOp.locks.^local (MongoDB reporting output)

currentOp.lockStats (MongoDB reporting output)

currentOp.microsecs_running (MongoDB reporting output)

currentOp.msg (MongoDB reporting output)

currentOp.ns (MongoDB reporting output)

currentOp.numYields (MongoDB reporting output)

currentOp.op (MongoDB reporting output)

currentOp.opid (MongoDB reporting output)

currentOp.planSummary (MongoDB reporting output)

currentOp.progress (MongoDB reporting output)

currentOp.progress.done (MongoDB reporting output)

currentOp.progress.total (MongoDB reporting output)

currentOp.query (MongoDB reporting output)

currentOp.secs_running (MongoDB reporting output)

currentOp.threadId (MongoDB reporting output)

currentOp.timeAcquiringMicros (MongoDB reporting output)

currentOp.timeAcquiringMicros.R (MongoDB reporting output)

currentOp.timeAcquiringMicros.r (MongoDB reporting output)

currentOp.timeAcquiringMicros.w (MongoDB reporting output)

currentOp.timeAcquiringMicros.W (MongoDB reporting output)

currentOp.timeLockedMicros (MongoDB reporting output)

currentOp.timeLockedMicros.r (MongoDB reporting output)

currentOp.timeLockedMicros.R (MongoDB reporting output)

currentOp.timeLockedMicros.W (MongoDB reporting output)

currentOp.timeLockedMicros.w (MongoDB reporting output)

currentOp.waitingForLock (MongoDB reporting output)

cursor

cursor.addOption (shell method)

cursor.batchSize (shell method)

cursor.count (shell method)

cursor.explain (shell method)

cursor.forEach (shell method)

cursor.hasNext (shell method)

cursor.hint (shell method)

cursor.limit (shell method)

cursor.map (shell method)

cursor.max (shell method)

cursor.maxTimeMS (shell method)

cursor.min (shell method)

cursor.next (shell method)

cursor.objsLeftInBatch (shell method)

cursor.readPref (shell method)

cursor.showDiskLoc (shell method)

cursor.size (shell method)

cursor.skip (shell method)

cursor.snapshot (shell method)

cursor.sort (shell method)

cursor.toArray (shell method)

cursorInfo (database command)

(user action)

D

daemon

data directory

Data Size (MongoDB system limit)

data-center awareness

data_binary (BSON type)

data_date (BSON type)

data_maxkey (BSON type)

data_minkey (BSON type)

data_numberlong (BSON type)

data_oid (BSON type)

data_ref (BSON type)

data_regex (BSON type)

data_timestamp (BSON type)

data_undefined (BSON type)

database, [1]

local

database command

Database Name Case Sensitivity (MongoDB system limit)

database profiler

database references

dataSize (database command)

Date (shell method)

datum

db.addUser (shell method)

db.auth (shell method)

db.changeUserPassword (shell method)

db.cloneCollection (shell method)

db.cloneDatabase (shell method)

db.collection.aggregate (shell method)

db.collection.copyTo (shell method)

db.collection.count (shell method)

db.collection.createIndex (shell method)

db.collection.dataSize (shell method)

db.collection.distinct (shell method)

db.collection.drop (shell method)

db.collection.dropIndex (shell method)

db.collection.dropIndexes (shell method)

db.collection.ensureIndex (shell method)

db.collection.find (shell method)

db.collection.findAndModify (shell method)

db.collection.findOne (shell method)

db.collection.getIndexes (shell method)

db.collection.getIndexStats (shell method)

db.collection.getPlanCache (shell method)

db.collection.getShardDistribution (shell method)

db.collection.getShardVersion (shell method)

db.collection.group (shell method)

db.collection.indexStats (shell method)

db.collection.initializeOrderedBulkOp (shell method)

db.collection.initializeUnorderedBulkOp (shell method)

db.collection.insert (shell method)

db.collection.isCapped (shell method)

db.collection.mapReduce (shell method)

db.collection.reIndex (shell method)

db.collection.remove (shell method)

db.collection.renameCollection (shell method)

db.collection.save (shell method)

db.collection.stats (shell method)

db.collection.storageSize (shell method)

db.collection.totalIndexSize (shell method)

db.collection.totalSize (shell method)

db.collection.update (shell method)

db.collection.validate (shell method)

db.commandHelp (shell method)

db.copyDatabase (shell method)

db.createCollection (shell method)

db.createRole (shell method)

db.createUser (shell method)

db.currentOp (shell method)

db.dropAllRoles (shell method)

db.dropAllUsers (shell method)

db.dropDatabase (shell method)

db.dropRole (shell method)

db.dropUser (shell method)

db.eval (shell method)

db.fsyncLock (shell method)

db.fsyncUnlock (shell method)

db.getCollection (shell method)

db.getCollectionNames (shell method)

db.getLastError (shell method)

db.getLastErrorObj (shell method)

db.getMongo (shell method)

db.getName (shell method)

db.getPrevError (shell method)

db.getProfilingLevel (shell method)

db.getProfilingStatus (shell method)

db.getReplicationInfo (shell method)

db.getReplicationInfo.errmsg (MongoDB reporting output)

db.getReplicationInfo.logSizeMB (MongoDB reporting output)

db.getReplicationInfo.now (MongoDB reporting output)

db.getReplicationInfo.oplogMainRowCount (MongoDB reporting output)

db.getReplicationInfo.tFirst (MongoDB reporting output)

db.getReplicationInfo.timeDiff (MongoDB reporting output)

db.getReplicationInfo.timeDiffHours (MongoDB reporting output)

db.getReplicationInfo.tLast (MongoDB reporting output)

db.getReplicationInfo.usedMB (MongoDB reporting output)

db.getRole (shell method)

db.getRoles (shell method)

db.getSiblingDB (shell method)

db.getUser (shell method)

db.getUsers (shell method)

db.grantPrivilegesToRole (shell method)

db.grantRolesToRole (shell method)

db.grantRolesToUser (shell method)

db.help (shell method)

db.hostInfo (shell method)

db.isMaster (shell method)

db.killOp (shell method)

db.listCommands (shell method)

db.loadServerScripts (shell method)

db.logout (shell method)

db.printCollectionStats (shell method)

db.printReplicationInfo (shell method)

db.printShardingStatus (shell method)

db.printSlaveReplicationInfo (shell method)

db.removeUser (shell method)

db.repairDatabase (shell method)

db.resetError (shell method)

db.revokePrivilegesFromRole (shell method)

db.revokeRolesFromRole (shell method)

db.revokeRolesFromUser (shell method)

db.runCommand (shell method)

db.serverBuildInfo (shell method)

db.serverCmdLineOpts (shell method)

db.serverStatus (shell method)

db.setProfilingLevel (shell method)

db.shutdownServer (shell method)

db.stats (shell method)

db.updateRole (shell method)

db.updateUser (shell method)

db.upgradeCheck (shell method)

db.upgradeCheckAllDBs (shell method)

db.version (shell method)

dbAdmin (user role)

dbAdminAnyDatabase (user role)

dbHash (database command)

(user action)

dbOwner (user role)

dbpath

DBQuery.Option.awaitData (MongoDB reporting output)

DBQuery.Option.exhaust (MongoDB reporting output)

DBQuery.Option.noTimeout (MongoDB reporting output)

DBQuery.Option.oplogReplay (MongoDB reporting output)

DBQuery.Option.partial (MongoDB reporting output)

DBQuery.Option.slaveOk (MongoDB reporting output)

DBQuery.Option.tailable (MongoDB reporting output)

DBRef

dbStats (database command)

(user action)

dbStats.avgObjSize (MongoDB reporting output)

dbStats.collections (MongoDB reporting output)

dbStats.dataFileVersion (MongoDB reporting output)

dbStats.dataFileVersion.major (MongoDB reporting output)

dbStats.dataFileVersion.minor (MongoDB reporting output)

dbStats.dataSize (MongoDB reporting output)

dbStats.db (MongoDB reporting output)

dbStats.fileSize (MongoDB reporting output)

dbStats.indexes (MongoDB reporting output)

dbStats.indexSize (MongoDB reporting output)

dbStats.nsSizeMB (MongoDB reporting output)

dbStats.numExtents (MongoDB reporting output)

dbStats.objects (MongoDB reporting output)

dbStats.storageSize (MongoDB reporting output)

delayed member

delete (database command)

delete.n (MongoDB reporting output)

delete.ok (MongoDB reporting output)

delete.writeConcernError (MongoDB reporting output)

delete.writeConcernError.code (MongoDB reporting output)

delete.writeConcernError.errmsg (MongoDB reporting output)

delete.writeErrors (MongoDB reporting output)

delete.writeErrors.code (MongoDB reporting output)

delete.writeErrors.errmsg (MongoDB reporting output)

delete.writeErrors.index (MongoDB reporting output)

DESCEND (system variable available in aggregation)

development tutorials

diagLogging (database command)

(user action)

diagnostic log

distinct (database command)

document

space allocation

dot notation

DOWN (replica set state)

draining

driver

driverOIDTest (database command)

drop (database command)

dropAllRolesFromDatabase (database command)

dropAllUsersFromDatabase (database command)

dropCollection (user action)

dropDatabase (database command)

(user action)

dropIndex (user action)

dropIndexes (database command)

dropRole (database command)

(user action)

dropUser (database command)

(user action)

E

EDITOR, [1], [2]

election

emptycapped (database command)

(user action)

enableLocalhostAuthBypass (setParameter option)

enableProfiler (user action)

enableSharding (database command)

(user action)

enableTestCommands (setParameter option)

environment variable

EDITOR, [1], [2], [3]

HOME, [1], [2]

HOMEDRIVE, [1]

HOMEPATH

eval (database command)

eventual consistency

expireAfterSeconds

explain.allPlans (MongoDB reporting output)

explain.clauses (MongoDB reporting output)

explain.clusteredType (MongoDB reporting output)

explain.cursor (MongoDB reporting output)

explain.filterSet (MongoDB reporting output)

explain.indexBounds (MongoDB reporting output)

explain.indexOnly (MongoDB reporting output)

explain.isMultiKey (MongoDB reporting output)

explain.millis (MongoDB reporting output)

explain.millisShardAvg (MongoDB reporting output)

explain.millisShardTotal (MongoDB reporting output)

explain.n (MongoDB reporting output)

explain.nChunkSkips (MongoDB reporting output)

explain.nscanned (MongoDB reporting output)

explain.nscannedAllPlans (MongoDB reporting output)

explain.nscannedObjects (MongoDB reporting output)

explain.nscannedObjectsAllPlans (MongoDB reporting output)

explain.numQueries (MongoDB reporting output)

explain.numShards (MongoDB reporting output)

explain.nYields (MongoDB reporting output)

explain.oldPlan (MongoDB reporting output)

explain.scanAndOrder (MongoDB reporting output)

explain.server (MongoDB reporting output)

explain.shards (MongoDB reporting output)

expression

F

failIndexKeyTooLong (setParameter option)

failover

replica set

FATAL (replica set state)

features (database command)

field

field path

Fields with 2dsphere Indexes can only hold Geometries (MongoDB system limit)

filemd5 (database command)

files._id (MongoDB reporting output)

files.aliases (MongoDB reporting output)

files.chunkSize (MongoDB reporting output)

files.contentType (MongoDB reporting output)

files.filename (MongoDB reporting output)

files.length (MongoDB reporting output)

files.md5 (MongoDB reporting output)

files.metadata (MongoDB reporting output)

files.uploadDate (MongoDB reporting output)

find (user action)

findAndModify (database command)

firewall

flushRouterConfig (database command)

(user action)

forceerror (database command)

fsync

(database command)

(user action)

fundamentals

sharding

fuzzFile (shell method)

G

geohash

GeoJSON

geoNear (database command)

geoNear.ok (MongoDB reporting output)

geoNear.results (MongoDB reporting output)

geoNear.results[n].dis (MongoDB reporting output)

geoNear.results[n].obj (MongoDB reporting output)

geoNear.stats (MongoDB reporting output)

geoNear.stats.avgDistance (MongoDB reporting output)

geoNear.stats.maxDistance (MongoDB reporting output)

geoNear.stats.nscanned (MongoDB reporting output)

geoNear.stats.objectsLoaded (MongoDB reporting output)

geoNear.stats.time (MongoDB reporting output)

geoSearch (database command)

geospatial

geospatial queries

exact

geoWalk (database command)

getCmdLineOpts (database command)

(user action)

getHostName (shell method)

getLastError (database command)

getLastError.code (MongoDB reporting output)

getLastError.connectionId (MongoDB reporting output)

getLastError.err (MongoDB reporting output)

getLastError.lastOp (MongoDB reporting output)

getLastError.n (MongoDB reporting output)

getLastError.ok (MongoDB reporting output)

getLastError.shards (MongoDB reporting output)

getLastError.singleShard (MongoDB reporting output)

getLastError.updatedExisting (MongoDB reporting output)

getLastError.upserted (MongoDB reporting output)

getLastError.waited (MongoDB reporting output)

getLastError.wnote (MongoDB reporting output)

getLastError.wtime (MongoDB reporting output)

getLastError.wtimeout (MongoDB reporting output)

getLog (database command)

(user action)

getMemInfo (shell method)

getnonce (database command)

getoptime (database command)

getParameter (database command)

(user action)

getPrevError (database command)

getShardMap (database command)

(user action)

getShardVersion (database command)

(user action)

godinsert (database command)

grantPrivilegesToRole (database command)

grantRole (user action)

grantRolesToRole (database command)

grantRolesToUser (database command)

GridFS, [1], [2]

chunks collection

collections

files collection

index

initialize

group (database command)

H

handshake (database command)

hashed shard key

haystack index

hidden (built-in class)

hidden member

HOME, [1]

HOMEDRIVE

hostInfo (database command)

(MongoDB reporting output)

(user action)

hostInfo.extra (MongoDB reporting output)

hostInfo.extra.alwaysFullSync (MongoDB reporting output)

hostInfo.extra.cpuFeatures (MongoDB reporting output)

hostInfo.extra.cpuFrequencyMHz (MongoDB reporting output)

hostInfo.extra.kernelVersion (MongoDB reporting output)

hostInfo.extra.libcVersion (MongoDB reporting output)

hostInfo.extra.maxOpenFiles (MongoDB reporting output)

hostInfo.extra.nfsAsync (MongoDB reporting output)

hostInfo.extra.numPages (MongoDB reporting output)

hostInfo.extra.pageSize (MongoDB reporting output)

hostInfo.extra.scheduler (MongoDB reporting output)

hostInfo.extra.versionString (MongoDB reporting output)

hostInfo.os (MongoDB reporting output)

hostInfo.os.name (MongoDB reporting output)

hostInfo.os.type (MongoDB reporting output)

hostInfo.os.version (MongoDB reporting output)

hostInfo.system (MongoDB reporting output)

hostInfo.system.cpuAddrSize (MongoDB reporting output)

hostInfo.system.cpuArch (MongoDB reporting output)

hostInfo.system.currentTime (MongoDB reporting output)

hostInfo.system.hostname (MongoDB reporting output)

hostInfo.system.memSizeMB (MongoDB reporting output)

hostInfo.system.numaEnabled (MongoDB reporting output)

hostInfo.system.numCores (MongoDB reporting output)

hostManager (user role)

hostname (shell method)

I

idempotent

index

TTL index

_id

background creation

compound, [1]

create, [1]

create in background

drop duplicates, [1]

duplicates, [1]

embedded fields

hashed, [1]

list indexes, [1]

measure use

monitor index building

multikey

name

options

overview

rebuild

remove

replica set

sort order

sparse, [1]

subdocuments

unique, [1]

index (collection flag)

Index Key Limit (MongoDB system limit)

Index Name Length (MongoDB system limit)

index types

primary key

indexStats (database command)

(user action)

indexStats.bucketBodyBytes (MongoDB reporting output)

indexStats.depth (MongoDB reporting output)

indexStats.index (MongoDB reporting output)

indexStats.isIdIndex (MongoDB reporting output)

indexStats.keyPattern (MongoDB reporting output)

indexStats.overall (MongoDB reporting output)

indexStats.overall.bsonRatio (MongoDB reporting output)

indexStats.overall.fillRatio (MongoDB reporting output)

indexStats.overall.keyCount (MongoDB reporting output)

indexStats.overall.keyNodeRatio (MongoDB reporting output)

indexStats.overall.numBuckets (MongoDB reporting output)

indexStats.overall.usedKeyCount (MongoDB reporting output)

indexStats.perLevel (MongoDB reporting output)

indexStats.perLevel.bsonRatio (MongoDB reporting output)

indexStats.perLevel.fillRatio (MongoDB reporting output)

indexStats.perLevel.keyCount (MongoDB reporting output)

indexStats.perLevel.keyNodeRatio (MongoDB reporting output)

indexStats.perLevel.numBuckets (MongoDB reporting output)

indexStats.perLevel.usedKeyCount (MongoDB reporting output)

indexStats.storageNs (MongoDB reporting output)

indexStats.version (MongoDB reporting output)

initial sync

inprog (user action)

insert (database command)

(user action)

insert.n (MongoDB reporting output)

insert.ok (MongoDB reporting output)

insert.writeConcernError (MongoDB reporting output)

insert.writeConcernError.code (MongoDB reporting output)

insert.writeConcernError.errmsg (MongoDB reporting output)

insert.writeErrors (MongoDB reporting output)

insert.writeErrors.code (MongoDB reporting output)

insert.writeErrors.errmsg (MongoDB reporting output)

insert.writeErrors.index (MongoDB reporting output)

installation

installation guides

installation tutorials

internal (user action)

internals

config database

interrupt point

invalidateUserCache (database command)

(user action)

IPv6

isdbgrid (database command)

isMaster (database command)

isMaster.arbiterOnly (MongoDB reporting output)

isMaster.arbiters (MongoDB reporting output)

isMaster.hidden (MongoDB reporting output)

isMaster.hosts (MongoDB reporting output)

isMaster.ismaster (MongoDB reporting output)

isMaster.localTime (MongoDB reporting output)

isMaster.maxBsonObjectSize (MongoDB reporting output)

isMaster.maxMessageSizeBytes (MongoDB reporting output)

isMaster.maxWireVersion (MongoDB reporting output)

isMaster.me (MongoDB reporting output)

isMaster.minWireVersion (MongoDB reporting output)

isMaster.msg (MongoDB reporting output)

isMaster.passive (MongoDB reporting output)

isMaster.passives (MongoDB reporting output)

isMaster.primary (MongoDB reporting output)

isMaster.secondary (MongoDB reporting output)

isMaster.setName (MongoDB reporting output)

isMaster.tags (MongoDB reporting output)

ISODate

J

JavaScript

journal

journalCommitInterval (setParameter option)

journalLatencyTest (database command)

JSON

JSON document

JSONP

K

KEEP (system variable available in aggregation)

killCursors (user action)

killop (user action)

L

least privilege

legacy coordinate pairs

Length of Database Names (MongoDB system limit)

LineString

listCommands (database command)

listDatabases (database command)

(user action)

listFiles (shell method)

listShards (database command)

(user action)

load (shell method)

load balancer

local database

local.oplog.$main (MongoDB reporting output)

local.oplog.rs (MongoDB reporting output)

local.replset.minvalid (MongoDB reporting output)

local.slaves (MongoDB reporting output), [1]

local.sources (MongoDB reporting output)

local.startup_log (MongoDB reporting output)

local.startup_log._id (MongoDB reporting output)

local.startup_log.buildinfo (MongoDB reporting output)

local.startup_log.cmdLine (MongoDB reporting output)

local.startup_log.hostname (MongoDB reporting output)

local.startup_log.pid (MongoDB reporting output)

local.startup_log.startTime (MongoDB reporting output)

local.startup_log.startTimeLocal (MongoDB reporting output)

local.system.replset (MongoDB reporting output)

local.system.replset._id (MongoDB reporting output)

local.system.replset.members (MongoDB reporting output)

local.system.replset.members[n]._id (MongoDB reporting output)

local.system.replset.members[n].arbiterOnly (MongoDB reporting output)

local.system.replset.members[n].buildIndexes (MongoDB reporting output)

local.system.replset.members[n].hidden (MongoDB reporting output)

local.system.replset.members[n].host (MongoDB reporting output)

local.system.replset.members[n].priority (MongoDB reporting output)

local.system.replset.members[n].slaveDelay (MongoDB reporting output)

local.system.replset.members[n].tags (MongoDB reporting output)

local.system.replset.members[n].votes (MongoDB reporting output)

local.system.replset.settings (MongoDB reporting output)

local.system.replset.settings.chainingAllowed (MongoDB reporting output)

local.system.replset.settings.getLastErrorDefaults (MongoDB reporting output)

local.system.replset.settings.getLastErrorModes (MongoDB reporting output)

local.system.replset.settings.heartbeatTimeoutSecs (MongoDB reporting output)

local.system.replset.version (MongoDB reporting output)

lock

logApplicationMessage (database command)

logLevel (setParameter option)

logout (database command)

logRotate (database command)

(user action)

logUserIds (setParameter option)

ls (shell method)

LVM

M

map-reduce

mapping type

mapReduce (database command)

mapReduce.counts (MongoDB reporting output)

mapReduce.counts.emit (MongoDB reporting output)

mapReduce.counts.input (MongoDB reporting output)

mapReduce.counts.output (MongoDB reporting output)

mapReduce.counts.reduce (MongoDB reporting output)

mapReduce.ok (MongoDB reporting output)

mapReduce.result (MongoDB reporting output)

mapReduce.results (MongoDB reporting output)

mapreduce.shardedfinish (database command)

mapReduce.timeMillis (MongoDB reporting output)

master

Maximum Number of Documents in a Capped Collection (MongoDB system limit)

Maximum Number of Documents Per Chunk to Migrate (MongoDB system limit)

Maximum Size of Auto-Created Oplog (MongoDB system limit)

md5

md5sumFile (shell method)

medianKey (database command)

mergeChunks (database command)

MIB

MIME

mkdir (shell method)

mongo

(program), [1]

Mongo (shell method)

Mongo.getDB (shell method)

Mongo.getReadPrefMode (shell method)

Mongo.getReadPrefTagSet (shell method)

Mongo.setReadPref (shell method)

Mongo.setSlaveOk (shell method)

mongod

(program), [1]

mongod.exe (program), [1]

MongoDB

MongoDB Enterprise

mongodump (program), [1]

mongoexport (program), [1]

mongofiles (program), [1]

mongoimport (program), [1]

mongooplog (program), [1]

mongoperf (program), [1]

mongoperf.fileSizeMB (setting)

mongoperf.mmf (setting)

mongoperf.nThreads (setting)

mongoperf.r (setting)

mongoperf.recSizeKB (setting)

mongoperf.sleepMicros (setting)

mongoperf.syncDelay (setting)

mongoperf.w (setting)

mongorestore (program), [1]

mongos, [1], [2]

(program), [1]

mongos load balancer

mongos.exe (program), [1]

mongosniff (program), [1]

mongostat (program), [1]

mongotop (program), [1]

mongotop.<timestamp> (MongoDB reporting output)

mongotop.db (MongoDB reporting output)

mongotop.ns (MongoDB reporting output)

mongotop.read (MongoDB reporting output)

mongotop.total (MongoDB reporting output)

mongotop.write (MongoDB reporting output)

Monotonically Increasing Shard Keys Can Limit Insert Throughput (MongoDB system limit)

moveChunk (database command)

(user action)

movePrimary (database command)

N

namespace

local

system

Namespace Length (MongoDB system limit)

natural order

nearest (read preference mode)

Nested Depth for BSON Documents (MongoDB system limit)

net (setting)

net.bindIp (setting)

net.http.enabled (setting)

net.http.JSONPEnabled (setting)

net.http.RESTInterfaceEnabled (setting)

net.ipv6 (setting)

net.maxIncomingConnections (setting)

net.port (setting)

net.ssl.allowInvalidCertificates (setting)

net.ssl.CAFile (setting)

net.ssl.clusterFile (setting)

net.ssl.clusterPassword (setting)

net.ssl.CRLFile (setting)

net.ssl.FIPSMode (setting)

net.ssl.mode (setting)

net.ssl.PEMKeyFile (setting)

net.ssl.PEMKeyPassword (setting)

net.ssl.sslOnNormalPorts (setting)

net.ssl.weakCertificateValidation (setting)

net.unixDomainSocket.enabled (setting)

net.unixDomainSocket.pathPrefix (setting)

net.wireObjectCheck (setting)

netstat (database command)

(user action)

newCollectionsUsePowerOf2Sizes (setParameter option)

notablescan (setParameter option)

Number of Collections in a Database (MongoDB system limit)

Number of Indexed Fields in a Compound Index (MongoDB system limit)

Number of Indexes per Collection (MongoDB system limit)

Number of Members of a Replica Set (MongoDB system limit)

Number of Namespaces (MongoDB system limit)

Number of Voting Members of a Replica Set (MongoDB system limit)

O

ObjectId

ObjectId.getTimestamp (shell method)

ObjectId.toString (shell method)

ObjectId.valueOf (shell method)

operationProfiling (setting)

operationProfiling.mode (setting)

operationProfiling.slowOpThresholdMs (setting)

operations (MongoDB reporting output)

Operations Unavailable in Sharded Environments (MongoDB system limit)

operator

oplog

ordered query plan

originalZeroIndex (MongoDB reporting output)

orphaned document

P

padding

padding factor

page fault

parallelCollectionScan (database command)

parallelCollectionScan.cursors (MongoDB reporting output)

parallelCollectionScan.cursors.cursor (MongoDB reporting output)

parallelCollectionScan.cursors.cursor.firstBatch (MongoDB reporting output)

parallelCollectionScan.cursors.cursor.id (MongoDB reporting output)

parallelCollectionScan.cursors.cursor.ns (MongoDB reporting output)

parallelCollectionScan.cursors.ok (MongoDB reporting output)

parallelCollectionScan.ok (MongoDB reporting output)

partition

passive member

pcap

PID

ping (database command)

pipe

pipeline

PlanCache.clear (shell method)

PlanCache.clearPlansByQuery (shell method)

PlanCache.getPlansByQuery (shell method)

PlanCache.help (shell method)

PlanCache.listQueryShapes (shell method)

planCacheClear (database command)

planCacheClearFilters (database command)

planCacheListFilters (database command)

planCacheListFilters.filters (MongoDB reporting output)

planCacheListFilters.filters.indexes (MongoDB reporting output)

planCacheListFilters.filters.projection (MongoDB reporting output)

planCacheListFilters.filters.query (MongoDB reporting output)

planCacheListFilters.filters.sort (MongoDB reporting output)

planCacheListFilters.ok (MongoDB reporting output)

planCacheListPlans (database command)

planCacheListQueryShapes (database command)

planCacheRead (user action)

planCacheSetFilter (database command)

planCacheWrite (user action)

Point

Polygon

powerOf2Sizes

pre-splitting

primary

(read preference mode)

PRIMARY (replica set state)

primary key

primary shard

primaryPreferred (read preference mode)

priority

privilege

processManagement (setting)

processManagement.fork (setting)

processManagement.pidFilePath (setting)

processManagement.windowsService.description (setting)

processManagement.windowsService.displayName (setting)

processManagement.windowsService.serviceName (setting)

processManagement.windowsService.servicePassword (setting)

processManagement.windowsService.serviceUser (setting)

profile (database command)

projection

PRUNE (system variable available in aggregation)

pwd (shell method)

Q

Queries cannot use both text and Geospatial Indexes (MongoDB system limit)

query

query optimizer, [1]

query shape

quiet (setParameter option)

quit (shell method)

R

rawMongoProgramOutput (shell method)

RDBMS

read (user role)

read lock

read operation

architecture

connection pooling

read operations

query

read preference, [1]

background

behavior

member selection

modes

mongos

nearest

ping time

semantics

sharding

tag sets, [1]

readAnyDatabase (user role)

readWrite (user role)

readWriteAnyDatabase (user role)

record size

recovering

RECOVERING (replica set state)

references

reIndex (database command)

(user action)

releaseConnectionsAfterResponse (setParameter option)

remove (user action)

REMOVED (replica set state)

removeFile (shell method)

removeShard (database command)

(user action)

renameCollection (database command)

renameCollectionSameDB (user action)

repairDatabase (database command)

(user action)

replApplyBatchSize (setParameter option)

replica pairs

replica set

elections

failover, [1]

index

local database

network partitions

reconfiguration

resync, [1]

rollbacks

sync, [1]

tag sets

replica set members

arbiters

delayed

hidden

non-voting

replication

(setting)

replication lag

replication.localPingThresholdMs (setting)

replication.oplogSizeMB (setting)

replication.replSetName (setting)

replication.secondaryIndexPrefetch (setting)

replIndexPrefetch (setParameter option)

replSetConfigure (user action)

replSetElect (database command)

replSetFreeze (database command)

replSetFresh (database command)

replSetGetRBID (database command)

replSetGetStatus (database command)

(user action)

replSetGetStatus.date (MongoDB reporting output)

replSetGetStatus.members (MongoDB reporting output)

replSetGetStatus.members.electionDate (MongoDB reporting output)

replSetGetStatus.members.electionTime (MongoDB reporting output)

replSetGetStatus.members.electionTime.i (MongoDB reporting output)

replSetGetStatus.members.electionTime.t (MongoDB reporting output)

replSetGetStatus.members.health (MongoDB reporting output)

replSetGetStatus.members.lastHeartbeat (MongoDB reporting output)

replSetGetStatus.members.lastHeartbeatMessage (MongoDB reporting output)

replSetGetStatus.members.lastHeartbeatRecv (MongoDB reporting output)

replSetGetStatus.members.name (MongoDB reporting output)

replSetGetStatus.members.optime (MongoDB reporting output)

replSetGetStatus.members.optime.i (MongoDB reporting output)

replSetGetStatus.members.optime.t (MongoDB reporting output)

replSetGetStatus.members.optimeDate (MongoDB reporting output)

replSetGetStatus.members.pingMs (MongoDB reporting output)

replSetGetStatus.members.self (MongoDB reporting output), [1]

replSetGetStatus.members.state (MongoDB reporting output)

replSetGetStatus.members.stateStr (MongoDB reporting output)

replSetGetStatus.members.uptime (MongoDB reporting output)

replSetGetStatus.myState (MongoDB reporting output)

replSetGetStatus.set (MongoDB reporting output)

replSetGetStatus.syncingTo (MongoDB reporting output)

replSetHeartbeat (database command)

(user action)

replSetInitiate (database command)

replSetMaintenance (database command)

replSetReconfig (database command)

replSetStateChange (user action)

replSetStepDown (database command)

replSetSyncFrom (database command)

replSetTest (database command)

resetDbpath (shell method)

resetError (database command)

resident memory

resource

REST

restore (user role)

Restriction on Collection Names (MongoDB system limit)

Restrictions on Database Names for Unix and Linux Systems (MongoDB system limit)

Restrictions on Database Names for Windows (MongoDB system limit)

Restrictions on Field Names (MongoDB system limit)

resync (database command)

(user action)

revokePrivilegesFromRole (database command)

revokeRole (user action)

revokeRolesFromRole (database command)

revokeRolesFromUser (database command)

RFC

RFC 4180

role

rolesInfo (database command)

rolesInfo.db (MongoDB reporting output)

rolesInfo.inheritedPrivileges (MongoDB reporting output)

rolesInfo.inheritedRoles (MongoDB reporting output)

rolesInfo.isBuiltin (MongoDB reporting output)

rolesInfo.privileges (MongoDB reporting output)

rolesInfo.role (MongoDB reporting output)

rolesInfo.roles (MongoDB reporting output)

rollback

ROLLBACK (replica set state)

rollbacks

ROOT (system variable available in aggregation)

root (user role)

rs.add (shell method)

rs.addArb (shell method)

rs.conf (shell method)

rs.config (shell method)

rs.freeze (shell method)

rs.help (shell method)

rs.initiate (shell method)

rs.printReplicationInfo (shell method)

rs.printSlaveReplicationInfo (shell method)

rs.reconfig (shell method)

rs.remove (shell method)

rs.slaveOk (shell method)

rs.status (shell method)

rs.stepDown (shell method)

rs.syncFrom (shell method)

run (shell method)

runMongoProgram (shell method)

runProgram (shell method)

S

saslauthdPath (setParameter option)

saslHostName (setParameter option)

saslServiceName (setParameter option)

secondary

(read preference mode)

SECONDARY (replica set state)

secondary index

secondary throttle

secondaryPreferred (read preference mode)

security (setting)

security.authorization (setting)

security.clusterAuthMode (setting)

security.javascriptEnabled (setting)

security.keyFile (setting)

security.sasl.hostName (setting)

security.sasl.saslauthdSocketPath (setting)

security.sasl.serviceName (setting)

serverStatus (database command)

(user action)

serverStatus.asserts (MongoDB reporting output)

serverStatus.asserts.msg (MongoDB reporting output)

serverStatus.asserts.regular (MongoDB reporting output)

serverStatus.asserts.rollovers (MongoDB reporting output)

serverStatus.asserts.user (MongoDB reporting output)

serverStatus.asserts.warning (MongoDB reporting output)

serverStatus.backgroundFlushing (MongoDB reporting output)

serverStatus.backgroundFlushing.average_ms (MongoDB reporting output)

serverStatus.backgroundFlushing.flushes (MongoDB reporting output)

serverStatus.backgroundFlushing.last_finished (MongoDB reporting output)

serverStatus.backgroundFlushing.last_ms (MongoDB reporting output)

serverStatus.backgroundFlushing.total_ms (MongoDB reporting output)

serverStatus.connections (MongoDB reporting output)

serverStatus.connections.available (MongoDB reporting output)

serverStatus.connections.current (MongoDB reporting output)

serverStatus.connections.totalCreated (MongoDB reporting output)

serverStatus.cursors (MongoDB reporting output)

serverStatus.cursors.clientCursors_size (MongoDB reporting output)

serverStatus.cursors.note (MongoDB reporting output)

serverStatus.cursors.pinned (MongoDB reporting output)

serverStatus.cursors.timedOut (MongoDB reporting output)

serverStatus.cursors.totalNoTimeout (MongoDB reporting output)

serverStatus.cursors.totalOpen (MongoDB reporting output)

serverStatus.dur (MongoDB reporting output)

serverStatus.dur.commits (MongoDB reporting output)

serverStatus.dur.commitsInWriteLock (MongoDB reporting output)

serverStatus.dur.compression (MongoDB reporting output)

serverStatus.dur.earlyCommits (MongoDB reporting output)

serverStatus.dur.journaledMB (MongoDB reporting output)

serverStatus.dur.timeMS (MongoDB reporting output)

serverStatus.dur.timeMS.dt (MongoDB reporting output)

serverStatus.dur.timeMS.prepLogBuffer (MongoDB reporting output)

serverStatus.dur.timeMS.remapPrivateView (MongoDB reporting output)

serverStatus.dur.timeMS.writeToDataFiles (MongoDB reporting output)

serverStatus.dur.timeMS.writeToJournal (MongoDB reporting output)

serverStatus.dur.writeToDataFilesMB (MongoDB reporting output)

serverStatus.extra_info (MongoDB reporting output)

serverStatus.extra_info.heap_usage_bytes (MongoDB reporting output)

serverStatus.extra_info.note (MongoDB reporting output)

serverStatus.extra_info.page_faults (MongoDB reporting output)

serverStatus.globalLock (MongoDB reporting output)

serverStatus.globalLock.activeClients (MongoDB reporting output)

serverStatus.globalLock.activeClients.readers (MongoDB reporting output)

serverStatus.globalLock.activeClients.total (MongoDB reporting output)

serverStatus.globalLock.activeClients.writers (MongoDB reporting output)

serverStatus.globalLock.currentQueue (MongoDB reporting output)

serverStatus.globalLock.currentQueue.readers (MongoDB reporting output)

serverStatus.globalLock.currentQueue.total (MongoDB reporting output)

serverStatus.globalLock.currentQueue.writers (MongoDB reporting output)

serverStatus.globalLock.lockTime (MongoDB reporting output)

serverStatus.globalLock.ratio (MongoDB reporting output)

serverStatus.globalLock.totalTime (MongoDB reporting output)

serverStatus.host (MongoDB reporting output)

serverStatus.indexCounters (MongoDB reporting output)

serverStatus.indexCounters.accesses (MongoDB reporting output)

serverStatus.indexCounters.hits (MongoDB reporting output)

serverStatus.indexCounters.misses (MongoDB reporting output)

serverStatus.indexCounters.missRatio (MongoDB reporting output)

serverStatus.indexCounters.resets (MongoDB reporting output)

serverStatus.localTime (MongoDB reporting output)

serverStatus.locks (MongoDB reporting output)

serverStatus.locks.. (MongoDB reporting output)

serverStatus.locks...timeAcquiringMicros (MongoDB reporting output)

serverStatus.locks...timeAcquiringMicros.R (MongoDB reporting output)

serverStatus.locks...timeAcquiringMicros.W (MongoDB reporting output)

serverStatus.locks...timeLockedMicros (MongoDB reporting output)

serverStatus.locks...timeLockedMicros.r (MongoDB reporting output)

serverStatus.locks...timeLockedMicros.R (MongoDB reporting output)

serverStatus.locks...timeLockedMicros.W (MongoDB reporting output)

serverStatus.locks...timeLockedMicros.w (MongoDB reporting output)

serverStatus.locks.<database> (MongoDB reporting output)

serverStatus.locks.<database>.timeAcquiringMicros (MongoDB reporting output)

serverStatus.locks.<database>.timeAcquiringMicros.r (MongoDB reporting output)

serverStatus.locks.<database>.timeAcquiringMicros.w (MongoDB reporting output)

serverStatus.locks.<database>.timeLockedMicros (MongoDB reporting output)

serverStatus.locks.<database>.timeLockedMicros.r (MongoDB reporting output)

serverStatus.locks.<database>.timeLockedMicros.w (MongoDB reporting output)

serverStatus.locks.admin (MongoDB reporting output)

serverStatus.locks.admin.timeAcquiringMicros (MongoDB reporting output)

serverStatus.locks.admin.timeAcquiringMicros.r (MongoDB reporting output)

serverStatus.locks.admin.timeAcquiringMicros.w (MongoDB reporting output)

serverStatus.locks.admin.timeLockedMicros (MongoDB reporting output)

serverStatus.locks.admin.timeLockedMicros.r (MongoDB reporting output)

serverStatus.locks.admin.timeLockedMicros.w (MongoDB reporting output)

serverStatus.locks.local (MongoDB reporting output)

serverStatus.locks.local.timeAcquiringMicros (MongoDB reporting output)

serverStatus.locks.local.timeAcquiringMicros.r (MongoDB reporting output)

serverStatus.locks.local.timeAcquiringMicros.w (MongoDB reporting output)

serverStatus.locks.local.timeLockedMicros (MongoDB reporting output)

serverStatus.locks.local.timeLockedMicros.r (MongoDB reporting output)

serverStatus.locks.local.timeLockedMicros.w (MongoDB reporting output)

serverStatus.mem (MongoDB reporting output)

serverStatus.mem.bits (MongoDB reporting output)

serverStatus.mem.mapped (MongoDB reporting output)

serverStatus.mem.mappedWithJournal (MongoDB reporting output)

serverStatus.mem.resident (MongoDB reporting output)

serverStatus.mem.supported (MongoDB reporting output)

serverStatus.mem.virtual (MongoDB reporting output)

serverStatus.metrics (MongoDB reporting output)

serverStatus.metrics.cursor (MongoDB reporting output)

serverStatus.metrics.cursor.open (MongoDB reporting output)

serverStatus.metrics.cursor.open.noTimeout (MongoDB reporting output)

serverStatus.metrics.cursor.open.pinned (MongoDB reporting output)

serverStatus.metrics.cursor.open.total (MongoDB reporting output)

serverStatus.metrics.cursor.timedOut (MongoDB reporting output)

serverStatus.metrics.document (MongoDB reporting output)

serverStatus.metrics.document.deleted (MongoDB reporting output)

serverStatus.metrics.document.inserted (MongoDB reporting output)

serverStatus.metrics.document.returned (MongoDB reporting output)

serverStatus.metrics.document.updated (MongoDB reporting output)

serverStatus.metrics.getLastError (MongoDB reporting output)

serverStatus.metrics.getLastError.wtime (MongoDB reporting output)

serverStatus.metrics.getLastError.wtime.num (MongoDB reporting output)

serverStatus.metrics.getLastError.wtime.totalMillis (MongoDB reporting output)

serverStatus.metrics.getLastError.wtimeouts (MongoDB reporting output)

serverStatus.metrics.operation (MongoDB reporting output)

serverStatus.metrics.operation.fastmod (MongoDB reporting output)

serverStatus.metrics.operation.idhack (MongoDB reporting output)

serverStatus.metrics.operation.scanAndOrder (MongoDB reporting output)

serverStatus.metrics.queryExecutor (MongoDB reporting output)

serverStatus.metrics.queryExecutor.scanned (MongoDB reporting output)

serverStatus.metrics.record (MongoDB reporting output)

serverStatus.metrics.record.moves (MongoDB reporting output)

serverStatus.metrics.repl (MongoDB reporting output)

serverStatus.metrics.repl.apply (MongoDB reporting output)

serverStatus.metrics.repl.apply.batches (MongoDB reporting output)

serverStatus.metrics.repl.apply.batches.num (MongoDB reporting output)

serverStatus.metrics.repl.apply.batches.totalMillis (MongoDB reporting output)

serverStatus.metrics.repl.apply.ops (MongoDB reporting output)

serverStatus.metrics.repl.buffer (MongoDB reporting output)

serverStatus.metrics.repl.buffer.count (MongoDB reporting output)

serverStatus.metrics.repl.buffer.maxSizeBytes (MongoDB reporting output)

serverStatus.metrics.repl.buffer.sizeBytes (MongoDB reporting output)

serverStatus.metrics.repl.network (MongoDB reporting output)

serverStatus.metrics.repl.network.bytes (MongoDB reporting output)

serverStatus.metrics.repl.network.getmores (MongoDB reporting output)

serverStatus.metrics.repl.network.getmores.num (MongoDB reporting output)

serverStatus.metrics.repl.network.getmores.totalMillis (MongoDB reporting output)

serverStatus.metrics.repl.network.ops (MongoDB reporting output)

serverStatus.metrics.repl.network.readersCreated (MongoDB reporting output)

serverStatus.metrics.repl.oplog (MongoDB reporting output)

serverStatus.metrics.repl.oplog.insert (MongoDB reporting output)

serverStatus.metrics.repl.oplog.insert.num (MongoDB reporting output)

serverStatus.metrics.repl.oplog.insert.totalMillis (MongoDB reporting output)

serverStatus.metrics.repl.oplog.insertBytes (MongoDB reporting output)

serverStatus.metrics.repl.preload (MongoDB reporting output)

serverStatus.metrics.repl.preload.docs (MongoDB reporting output)

serverStatus.metrics.repl.preload.docs.num (MongoDB reporting output)

serverStatus.metrics.repl.preload.docs.totalMillis (MongoDB reporting output)

serverStatus.metrics.repl.preload.indexes (MongoDB reporting output)

serverStatus.metrics.repl.preload.indexes.num (MongoDB reporting output)

serverStatus.metrics.repl.preload.indexes.totalMillis (MongoDB reporting output)

serverStatus.metrics.ttl (MongoDB reporting output)

serverStatus.metrics.ttl.deletedDocuments (MongoDB reporting output)

serverStatus.metrics.ttl.passes (MongoDB reporting output)

serverStatus.network (MongoDB reporting output)

serverStatus.network.bytesIn (MongoDB reporting output)

serverStatus.network.bytesOut (MongoDB reporting output)

serverStatus.network.numRequests (MongoDB reporting output)

serverStatus.opcounters (MongoDB reporting output)

serverStatus.opcounters.command (MongoDB reporting output)

serverStatus.opcounters.delete (MongoDB reporting output)

serverStatus.opcounters.getmore (MongoDB reporting output)

serverStatus.opcounters.insert (MongoDB reporting output)

serverStatus.opcounters.query (MongoDB reporting output)

serverStatus.opcounters.update (MongoDB reporting output)

serverStatus.opcountersRepl (MongoDB reporting output)

serverStatus.opcountersRepl.command (MongoDB reporting output)

serverStatus.opcountersRepl.delete (MongoDB reporting output)

serverStatus.opcountersRepl.getmore (MongoDB reporting output)

serverStatus.opcountersRepl.insert (MongoDB reporting output)

serverStatus.opcountersRepl.query (MongoDB reporting output)

serverStatus.opcountersRepl.update (MongoDB reporting output)

serverStatus.process (MongoDB reporting output)

serverStatus.recordStats (MongoDB reporting output)

serverStatus.recordStats.<database>.accessesNotInMemory (MongoDB reporting output)

serverStatus.recordStats.<database>.pageFaultExceptionsThrown (MongoDB reporting output)

serverStatus.recordStats.accessesNotInMemory (MongoDB reporting output)

serverStatus.recordStats.admin.accessesNotInMemory (MongoDB reporting output)

serverStatus.recordStats.admin.pageFaultExceptionsThrown (MongoDB reporting output)

serverStatus.recordStats.local.accessesNotInMemory (MongoDB reporting output)

serverStatus.recordStats.local.pageFaultExceptionsThrown (MongoDB reporting output)

serverStatus.recordStats.pageFaultExceptionsThrown (MongoDB reporting output)

serverStatus.repl (MongoDB reporting output)

serverStatus.repl.hosts (MongoDB reporting output)

serverStatus.repl.ismaster (MongoDB reporting output)

serverStatus.repl.secondary (MongoDB reporting output)

serverStatus.repl.setName (MongoDB reporting output)

serverStatus.storage.freelist.search.bucketExhausted (MongoDB reporting output)

serverStatus.storage.freelist.search.requests (MongoDB reporting output)

serverStatus.storage.freelist.search.scanned (MongoDB reporting output)

serverStatus.uptime (MongoDB reporting output)

serverStatus.uptimeEstimate (MongoDB reporting output)

serverStatus.version (MongoDB reporting output)

serverStatus.workingSet (MongoDB reporting output)

serverStatus.workingSet.computationTimeMicros (MongoDB reporting output)

serverStatus.workingSet.note (MongoDB reporting output)

serverStatus.workingSet.overSeconds (MongoDB reporting output)

serverStatus.workingSet.pagesInMemory (MongoDB reporting output)

serverStatus.writeBacksQueued (MongoDB reporting output)

set name

setParameter (database command)

(setting)

(user action)

setShardVersion (database command)

sh._adminCommand (shell method)

sh._checkFullName (shell method)

sh._checkMongos (shell method)

sh._lastMigration (shell method)

sh._lastMigration._id (MongoDB reporting output)

sh._lastMigration.clientAddr (MongoDB reporting output)

sh._lastMigration.details (MongoDB reporting output)

sh._lastMigration.ns (MongoDB reporting output)

sh._lastMigration.server (MongoDB reporting output)

sh._lastMigration.time (MongoDB reporting output)

sh._lastMigration.what (MongoDB reporting output)

sh.addShard (shell method)

sh.addShardTag (shell method)

sh.addTagRange (shell method)

sh.disableBalancing (shell method)

sh.enableBalancing (shell method)

sh.enableSharding (shell method)

sh.getBalancerHost (shell method)

sh.getBalancerState (shell method)

sh.help (shell method)

sh.isBalancerRunning (shell method)

sh.moveChunk (shell method)

sh.removeShardTag (shell method)

sh.setBalancerState (shell method)

sh.shardCollection (shell method)

sh.splitAt (shell method)

sh.splitFind (shell method)

sh.startBalancer (shell method)

sh.status (shell method)

sh.status.databases._id (MongoDB reporting output)

sh.status.databases.chunk-details (MongoDB reporting output)

sh.status.databases.chunks (MongoDB reporting output)

sh.status.databases.partitioned (MongoDB reporting output)

sh.status.databases.primary (MongoDB reporting output)

sh.status.databases.shard-key (MongoDB reporting output)

sh.status.databases.tag (MongoDB reporting output)

sh.status.sharding-version._id (MongoDB reporting output)

sh.status.sharding-version.clusterId (MongoDB reporting output)

sh.status.sharding-version.currentVersion (MongoDB reporting output)

sh.status.sharding-version.minCompatibleVersion (MongoDB reporting output)

sh.status.sharding-version.version (MongoDB reporting output)

sh.status.shards._id (MongoDB reporting output)

sh.status.shards.host (MongoDB reporting output)

sh.status.shards.tags (MongoDB reporting output)

sh.stopBalancer (shell method)

sh.waitForBalancer (shell method)

sh.waitForBalancerOff (shell method)

sh.waitForDLock (shell method)

sh.waitForPingChange (shell method)

shard

shard key, [1]

cardinality

query isolation

write scaling

Shard Key Index Type (MongoDB system limit)

Shard Key is Immutable (MongoDB system limit)

Shard Key Size (MongoDB system limit)

Shard Key Value in a Document is Immutable (MongoDB system limit)

shardCollection (database command)

shardConnPoolStats (database command)

shardConnPoolStats.createdByType (MongoDB reporting output)

shardConnPoolStats.createdByType.master (MongoDB reporting output)

shardConnPoolStats.createdByType.set (MongoDB reporting output)

shardConnPoolStats.createdByType.sync (MongoDB reporting output)

shardConnPoolStats.hosts (MongoDB reporting output)

shardConnPoolStats.hosts.<host>.available (MongoDB reporting output)

shardConnPoolStats.hosts.<host>.created (MongoDB reporting output)

shardConnPoolStats.replicaSets (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].addr (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].hidden (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].ismaster (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].ok (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].pingTimeMillis (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].secondary (MongoDB reporting output)

shardConnPoolStats.replicaSets.<name>.host[n].tags (MongoDB reporting output)

shardConnPoolStats.threads (MongoDB reporting output)

shardConnPoolStats.threads.hosts (MongoDB reporting output)

shardConnPoolStats.threads.hosts.avail (MongoDB reporting output)

shardConnPoolStats.threads.hosts.created (MongoDB reporting output)

shardConnPoolStats.threads.hosts.host (MongoDB reporting output)

shardConnPoolStats.threads.seenNS (MongoDB reporting output)

shardConnPoolStats.totalAvailable (MongoDB reporting output)

shardConnPoolStats.totalCreated (MongoDB reporting output)

sharded cluster

sharded clusters

sharding

chunk size

config database

config servers

localhost

shard key

shard key indexes

shards

sharding (setting)

Sharding Existing Collection Data Size (MongoDB system limit)

sharding.archiveMovedChunks (setting)

sharding.autoSplit (setting)

sharding.chunkSize (setting)

sharding.clusterRole (setting)

sharding.configDB (setting)

shardingState (database command)

(user action)

shards

shell helper

shutdown (database command)

(user action)

Single Document Modification Operations in Sharded Collections (MongoDB system limit)

single-master replication

Size of Namespace File (MongoDB system limit)

slave

slaveOk

sleep (database command)

snmp (setting)

snmp.master (setting)

snmp.subagent (setting)

Sorted Documents (MongoDB system limit)

split

(database command)

splitChunk (database command)

(user action)

splitVector (database command)

(user action)

SQL

SSD

sslMode (setParameter option)

stale

standalone

STARTUP (replica set state)

STARTUP2 (replica set state)

stopMongod (shell method)

stopMongoProgram (shell method)

stopMongoProgramByPid (shell method)

storage (setting)

storage order

storage.dbPath (setting)

storage.directoryPerDB (setting)

storage.indexBuildRetry (setting)

storage.journal.commitIntervalMs (setting)

storage.journal.debugFlags (setting)

storage.journal.enabled (setting)

storage.nsSize (setting)

storage.preallocDataFiles (setting)

storage.quota.enforced (setting)

storage.quota.maxFilesPerDB (setting)

storage.repairPath (setting)

storage.smallFiles (setting)

storage.syncPeriodSecs (setting)

storageDetails (user action)

strict consistency

supportCompatibilityFormPrivilegeDocuments (setParameter option)

sync

syncdelay (setParameter option)

syslog

system

collections

namespace

system.indexes.key (MongoDB reporting output)

system.indexes.name (MongoDB reporting output)

system.indexes.ns (MongoDB reporting output)

system.indexes.v (MongoDB reporting output)

system.profile.client (MongoDB reporting output)

system.profile.command (MongoDB reporting output)

system.profile.cursorid (MongoDB reporting output)

system.profile.keyUpdates (MongoDB reporting output)

system.profile.lockStats (MongoDB reporting output)

system.profile.lockStats.timeAcquiringMicros (MongoDB reporting output)

system.profile.lockStats.timeLockedMicros (MongoDB reporting output)

system.profile.millis (MongoDB reporting output)

system.profile.moved (MongoDB reporting output)

system.profile.nmoved (MongoDB reporting output)

system.profile.nreturned (MongoDB reporting output)

system.profile.ns (MongoDB reporting output)

system.profile.nscanned (MongoDB reporting output)

system.profile.ntoreturn (MongoDB reporting output)

system.profile.ntoskip (MongoDB reporting output)

system.profile.numYield (MongoDB reporting output)

system.profile.nupdated (MongoDB reporting output)

system.profile.op (MongoDB reporting output)

system.profile.query (MongoDB reporting output)

system.profile.responseLength (MongoDB reporting output)

system.profile.scanAndOrder (MongoDB reporting output)

system.profile.ts (MongoDB reporting output)

system.profile.updateobj (MongoDB reporting output)

system.profile.user (MongoDB reporting output)

systemLog (setting)

systemLog.destination (setting)

systemLog.logAppend (setting)

systemLog.path (setting)

systemLog.quiet (setting)

systemLog.syslogFacility (setting)

systemLog.timeStampFormat (setting)

systemLog.traceAllExceptions (setting)

systemLog.verbosity (setting)

T

tag

tag sets

configuration

tailable cursor

text (database command)

text search tutorials

textSearchEnabled (setParameter option)

top (database command)

(user action)

topology

touch (database command)

(user action)

traceExceptions (setParameter option)

TSV

TTL

TTL index

ttlMonitorEnabled (setParameter option)

tutorials

administration

development patterns

installation

text search

U

unique index

Unique Indexes in Sharded Collections (MongoDB system limit)

unix epoch

UNKNOWN (replica set state)

unlock (user action)

unordered query plan

unsetSharding (database command)

update (database command)

(user action)

update.n (MongoDB reporting output)

update.nModified (MongoDB reporting output)

update.ok (MongoDB reporting output)

update.upserted (MongoDB reporting output)

update.upserted._id (MongoDB reporting output)

update.upserted.index (MongoDB reporting output)

update.writeConcernError (MongoDB reporting output)

update.writeConcernError.code (MongoDB reporting output)

update.writeConcernError.errmsg (MongoDB reporting output)

update.writeErrors (MongoDB reporting output)

update.writeErrors.code (MongoDB reporting output)

update.writeErrors.errmsg (MongoDB reporting output)

update.writeErrors.index (MongoDB reporting output)

updateRole (database command)

updateUser (database command)

upsert

uri.authMechanism (MongoDB reporting output)

uri.authSource (MongoDB reporting output)

uri.connectTimeoutMS (MongoDB reporting output)

uri.gssapiServiceName (MongoDB reporting output)

uri.journal (MongoDB reporting output)

uri.maxIdleTimeMS (MongoDB reporting output)

uri.maxPoolSize (MongoDB reporting output)

uri.minPoolSize (MongoDB reporting output)

uri.readPreference (MongoDB reporting output)

uri.readPreferenceTags (MongoDB reporting output)

uri.replicaSet (MongoDB reporting output)

uri.socketTimeoutMS (MongoDB reporting output)

uri.ssl (MongoDB reporting output)

uri.uuidRepresentation (MongoDB reporting output)

uri.w (MongoDB reporting output)

uri.waitQueueMultiple (MongoDB reporting output)

uri.waitQueueTimeoutMS (MongoDB reporting output)

uri.wtimeoutMS (MongoDB reporting output)

usePowerOf2Sizes

(collection flag)

userAdmin (user role)

userAdminAnyDatabase (user role)

userCacheInvalidationIntervalSecs (setParameter option)

usersInfo (database command)

UUID (shell method)

V

validate (database command)

(user action)

validate.bytesWithHeaders (MongoDB reporting output)

validate.bytesWithoutHeaders (MongoDB reporting output)

validate.datasize (MongoDB reporting output)

validate.deletedCount (MongoDB reporting output)

validate.deletedSize (MongoDB reporting output)

validate.errors (MongoDB reporting output)

validate.extentCount (MongoDB reporting output)

validate.extents (MongoDB reporting output)

validate.extents.firstRecord (MongoDB reporting output)

validate.extents.lastRecord (MongoDB reporting output)

validate.extents.loc (MongoDB reporting output)

validate.extents.nsdiag (MongoDB reporting output)

validate.extents.size (MongoDB reporting output)

validate.extents.xnext (MongoDB reporting output)

validate.extents.xprev (MongoDB reporting output)

validate.firstExtent (MongoDB reporting output)

validate.firstExtentDetails (MongoDB reporting output)

validate.firstExtentDetails.firstRecord (MongoDB reporting output)

validate.firstExtentDetails.lastRecord (MongoDB reporting output)

validate.firstExtentDetails.loc (MongoDB reporting output)

validate.firstExtentDetails.nsdiag (MongoDB reporting output)

validate.firstExtentDetails.size (MongoDB reporting output)

validate.firstExtentDetails.xnext (MongoDB reporting output)

validate.firstExtentDetails.xprev (MongoDB reporting output)

validate.invalidObjects (MongoDB reporting output)

validate.keysPerIndex (MongoDB reporting output)

validate.lastExtent (MongoDB reporting output)

validate.lastExtentSize (MongoDB reporting output)

validate.nIndexes (MongoDB reporting output)

validate.nrecords (MongoDB reporting output)

validate.ns (MongoDB reporting output)

validate.objectsFound (MongoDB reporting output)

validate.ok (MongoDB reporting output)

validate.padding (MongoDB reporting output)

validate.valid (MongoDB reporting output)

version (shell method)

viewRole (user action)

viewUser (user action)

virtual memory

W

waitMongoProgramOnPort (shell method)

waitProgram (shell method)

WGS84

whatsmyuri (database command)

working set

Write Command Operation Limit Size (MongoDB system limit)

write concern, [1]

write lock

write operations

writebacklisten (database command)

writeBacks

writeBacksQueued (database command)

writeBacksQueued.hasOpsQueued (MongoDB reporting output)

writeBacksQueued.queues (MongoDB reporting output)

writeBacksQueued.queues.minutesSinceLastCall (MongoDB reporting output)

writeBacksQueued.queues.n (MongoDB reporting output)

writeBacksQueued.totalOpsQueued (MongoDB reporting output)

WriteResult (shell method)

WriteResult._id (MongoDB reporting output)

WriteResult.hasWriteConcernError (shell method)

WriteResult.hasWriteError (shell method)

WriteResult.nInserted (MongoDB reporting output)

WriteResult.nMatched (MongoDB reporting output)

WriteResult.nModified (MongoDB reporting output)

WriteResult.nRemoved (MongoDB reporting output)

WriteResult.nUpserted (MongoDB reporting output)

WriteResult.writeConcernError (MongoDB reporting output)

WriteResult.writeConcernError.code (MongoDB reporting output)

WriteResult.writeConcernError.errInfo (MongoDB reporting output)

WriteResult.writeError (MongoDB reporting output)

WriteResult.writeError.code (MongoDB reporting output)

WriteResult.writeError.errmsg (MongoDB reporting output), [1]