Mongo db manual

MongoDBDocumentation
Release 2.6.4
MongoDB Documentation Project
September 16, 2014

2

Contents
1 Introduction to MongoDB 3
1.1 What is MongoDB
2 Install MongoDB 5
2.1 Installation Guides
2.2 First Steps with MongoDB
3 MongoDB CRUD Operations
3.1 MongoDB CRUD Introduction
3.2 MongoDB CRUD Concepts
3.3 MongoDB CRUD Tutorials
3.4 MongoDB CRUD Reference
4 Data Models 131
4.1 Data Modeling Introduction
4.2 Data Modeling Concepts
4.3 Data Model Examples and Patterns
4.4 Data Model Reference
5 Administration 171
5.1 Administration Concepts
5.2 Administration Tutorials
5.3 Administration Reference
6 Security 279
6.1 Security Introduction
6.2 Security Concepts
6.3 Security Tutorials
6.4 Security Reference
7 Aggregation 387
7.1 Aggregation Introduction
7.2 Aggregation Concepts
7.3 Aggregation Examples
7.4 Aggregation Reference
8 Indexes 431
8.1 Index Introduction
8.2 Index Concepts
i

8.3 Indexing Tutorials
8.4 Indexing Reference
9 Replication 503
9.1 Replication Introduction
9.2 Replication Concepts
9.3 Replica Set Tutorials
9.4 Replication Reference
10 Sharding 607
10.1 Sharding Introduction
10.2 Sharding Concepts
10.3 Sharded Cluster Tutorials
10.4 Sharding Reference
11 Frequently Asked Questions
11.1 FAQ: MongoDB Fundamentals
11.2 FAQ: MongoDB for Application Developers
11.3 FAQ: ThemongoShell
11.4 FAQ: Concurrency
11.5 FAQ: Sharding with MongoDB
11.6 FAQ: Replication and Replica Sets
11.7 FAQ: MongoDB Storage
11.8 FAQ: Indexes
11.9 FAQ: MongoDB Diagnostics
12 Release Notes 725
12.1 Current Stable Release
12.2 Previous Stable Releases
12.3 Other MongoDB Release Notes
12.4 MongoDB Version Numbers
13 About MongoDB Documentation
13.1 License
13.2 Editions
13.3 Version and Revisions
13.4 Report an Issue or Make a Change Request
13.5 Contribute to the Documentation
Index 829
ii

MongoDB Documentation, Release 2.6.4
SeeAbout MongoDB Documentation(page 811) for more information about the MongoDB Documentation project,
this Manual and additional editions of this text.
Note:This version of the PDF doesnotinclude the reference section, see
1
for a PDF
edition of all MongoDB Reference Material.
1
http://docs.mongodb.org/master/MongoDB-reference-manual.pdf
Contents 1

MongoDB Documentation, Release 2.6.4
2 Contents

CHAPTER1
Introduction to MongoDB
Welcome to MongoDB. This document provides a brief introduction to MongoDB and some key concepts. See the
installation guides(page 5) for information on downloading and installing MongoDB.
1.1
MongoDB is an open-source document database that provides high performance, high availability, and automatic
scaling.
1.1.1
A record in MongoDB is a document, which is a data structure composed of eld and value pairs. MongoDB docu-
ments are similar to JSON objects. The values of elds may include other documents, arrays, and arrays of documents.
Figure 1.1: A MongoDB document.
The advantages of using documents are:

3

MongoDB Documentation, Release 2.6.4
1.1.2
High Performance
MongoDB provides high performance data persistence. In particular,

High Availability
To provide high availability, MongoDB's replication facility, called replica sets, provide:
automaticfailover.

Areplica set(page 503) is a group of MongoDB servers that maintain the same data set, providing redundancy and
increasing data availability.
Automatic Scaling
MongoDB provides horizontal scalability as part of itscorefunctionality.
sharding(page 607) distributes data across a cluster of machines.

4 Chapter 1. Introduction to MongoDB

CHAPTER2
Install MongoDB
MongoDB runs on most platforms and supports both 32-bit and 64-bit architectures.
2.1
See theRelease Notes(page 725) for information about specic releases of MongoDB.
Install on Linux(page 6)Documentations for installing the ofcial MongoDB distribution on Linux-based systems.
Install on Red Hat(page 6)Install MongoDB on Red Hat Enterprise, CentOS, Fedora and related Linux sys-
tems using.rpmpackages.
Install on Ubuntu(page 9)Install MongoDB on Ubuntu Linux systems using.debpackages.
Install on Debian(page 12)Install MongoDB on Debian systems using.debpackages.
Install on Other Linux Systems(page 14)Install the ofcial build of MongoDB on other Linux systems from
MongoDB archives.
Install on OS X(page 16)Install the ofcial build of MongoDB on OS X systems from Homebrew packages or from
MongoDB archives.
Install on Windows(page 19)Install MongoDB on Windows systems and optionally start MongoDB as a Windows
service.
Install MongoDB Enterprise(page 24)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(page 24)Install the MongoDB Enterprise build and required depen-
dencies on Red Hat Enterprise or CentOS Systems using packages.
Install MongoDB Enterprise on Ubuntu(page 27)Install the MongoDB Enterprise build and required depen-
dencies on Ubuntu Linux Systems using packages.
Install MongoDB Enterprise on Debian(page 30)Install the MongoDB Enterprise build and required depen-
dencies on Debian Linux Systems using packages.
Install MongoDB Enterprise on SUSE(page 32)Install the MongoDB Enterprise build and required depen-
dencies on SUSE Enterprise Linux.
Install MongoDB Enterprise on Amazon AMI(page 34)Install the MongoDB Enterprise build and required
dependencies on Amazon Linux AMI.
Install MongoDB Enterprise on Windows(page 36)Install the MongoDB Enterprise build and required de-
pendencies using the.msiinstaller.
5

MongoDB Documentation, Release 2.6.4
2.1.1
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(page 6)Install MongoDB on Red Hat Enterprise, CentOS, Fedora and related Linux systems
using.rpmpackages.
Install on Ubuntu(page 9)Install MongoDB on Ubuntu Linux systems using.debpackages.
Install on Debian(page 12)Install MongoDB on Debian systems using.debpackages.
For systems without supported packages, refer to the Manual Installation tutorial.
Manual Installation
Although packages are the preferred installation method, for Linux systems without supported packages, see the
following guide:
Install on Other Linux Systems(page 14)Install the ofcial build of MongoDB on other Linux systems from Mon-
goDB archives.
Install MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux
OverviewUse this tutorial to install MongoDB on Red Hat Enterprise Linux, CentOS Linux, Fedora Linux, or a
related system from.rpmpackages. While some of these distributions include their own MongoDB packages, the
ofcial MongoDB packages are generally more up to date.
PackagesMongoDB provides packages of the ofcially supported MongoDB builds in it's own repository. This
repository provides the MongoDB distribution in the following packages:
mongodb-org
This package is ametapackagethat will automatically install the four component packages listed below.
mongodb-org-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-org-mongos
This package contains themongosdaemon.
mongodb-org-shell
This package contains themongoshell.
mongodb-org-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
6 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Control ScriptsThemongodb-orgpackage includes variouscontrol scripts, including the init script
/etc/rc.d/init.d/mongod . These scripts are used to stop, start, and restart daemon processes.
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts. See
http://docs.mongodb.org/manualreference/configuration-options for documentation of the
conguration le.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script for use in such environments. See the
mongosreference for conguration details.
Warning:With the introduction ofsystemdin Fedora 15, the control scripts included in the packages available
in the MongoDB downloads repository are not compatible with Fedora systems. A correction is forthcoming; see
SERVER-7285
a
for more information. In the mean time use your own control scriptsorinstall using the procedure
outlined inInstall MongoDB on Linux Systems(page 14).
a
https://jira.mongodb.org/browse/SERVER-7285
ConsiderationsFor production deployments, always run MongoDB on 64-bit systems.
The default/etc/mongodb.conf conguration le supplied by the 2.6 series packages hasbind_ip`set to
127.0.0.1by default. Modify this setting as needed for your environment before initializing areplica set.
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation of an older release, please refer to the documentation for the appropriate version.
Install MongoDB
Step 1: Congure the package management system (YUM).Create a/etc/yum.repos.d/mongodb.repo
le to hold the following conguration information for the MongoDB repository:
If you are running a 64-bit system, use the following conguration:
[mongodb]
name=MongoDB Repository
baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64/
gpgcheck=0
enabled=1
If you are running a 32-bit system, which is not recommended for production deployments, use the following cong-
uration:
[mongodb]
name=MongoDB Repository
baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/i686/
gpgcheck=0
enabled=1
Step 2: Install the MongoDB packages and associated tools.When you install the packages, you choose whether
to install the current release or a previous one. This step provides the commands for both.
To install the latest stable version of MongoDB, issue the following command:
sudo yum install -y mongodb-org
2.1. Installation Guides 7

MongoDB Documentation, Release 2.6.4
To install a specic release of MongoDB, specify each component package individually and append the version number
to the package name, as in the following example that installs the2.6.1`release of MongoDB:
sudo yum 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
You can specify any available version of MongoDB. Howeveryumwill upgrade the packages when a newer version
becomes available. To prevent unintended upgrades, pin the package. To pin a package, add the followingexclude
directive to your/etc/yum.confle:
exclude=mongodb-org,mongodb-org-server,mongodb-org-shell,mongodb-org-mongos,mongodb-org-tools
Previous versions of MongoDB packages use different naming conventions. See the
more information
1
.
Run MongoDB
Important:You must congure SELinux to allow MongoDB to start on Red Hat Linux-based systems (Red Hat
Enterprise Linux, CentOS, Fedora). Administrators have three options:
Default MongoDB Port(page 380) for more
information on MongoDB's default ports. For default settings, this can be accomplished by running
semanage port -a -t mongodb_port_t -p tcp 27017
permissivemode in/etc/selinux.conf. The line
SELINUX=enforcing
should be changed to
SELINUX=permissive

SELINUX=disabled
All three options requirerootprivileges. 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 les in/var/lib/mongoand its log les in/var/log/mongodb
by default, and runs using themongoduser account. You can specify alternate log and data le directories in
/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongoand/var/log/mongodbdirectories to give this users access to these directories.
Step 1: Start MongoDB.You can start themongodprocess by issuing the following command:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyYou can verify that themongodprocess has started suc-
cessfully by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
1
http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-linux
8 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:
sudo chkconfig mongod on
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.You can restart themongodprocess 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 le.
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB on Ubuntu
OverviewUse this tutorial to install MongoDB on Ubuntu Linux systems from.debpackages. While Ubuntu
includes its own MongoDB packages, the ofcial MongoDB packages are generally more up-to-date.
Note:If you use an older Ubuntu that doesnotuse Upstart (i.e. any version before 9.10 Karmic), please follow the
instructions on theInstall MongoDB on Debian(page 12) tutorial.
PackagesMongoDB provides packages of the ofcially supported MongoDB builds in it's own repository. This
repository provides the MongoDB distribution in the following packages:
mongodb-org
This package is ametapackagethat will automatically install the four component packages listed below.
mongodb-org-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-org-mongos
This package contains themongosdaemon.
mongodb-org-shell
This package contains themongoshell.
mongodb-org-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
2.1. Installation Guides 9

MongoDB Documentation, Release 2.6.4
Control ScriptsThemongodb-orgpackage includes variouscontrol scripts, including the init script
/etc/init.d/mongod. These scripts are used to stop, start, and restart daemon processes.
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts. See
http://docs.mongodb.org/manualreference/configuration-options for documentation of the
conguration le.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script for use in such environments. See the
mongosreference for conguration details.
ConsiderationsFor production deployments, always run MongoDB on 64-bit systems.
You cannot install this package concurrently with themongodb,mongodb-server, ormongodb-clientspack-
ages provided by Ubuntu.
The default/etc/mongodb.conf conguration le supplied by the 2.6 series packages hasbind_ip`set to
127.0.0.1by default. Modify this setting as needed for your environment before initializing areplica set.
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation of an older release, please refer to the documentation for the appropriate version.
Install MongoDB
Step 1: Import the public key used by the package management system.The Ubuntu package management tools
(i.e.dpkgandapt) ensure package consistency and authenticity by requiring that distributors sign packages with
GPG keys. Issue the following command to import the
2
:
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10
Step 2: Create a list le for MongoDB.Create the/etc/apt/sources.list.d/mongodb.list list le
using the following command:
echo
Step 3: Reload local package database.Issue the following command to reload the local package database:
sudo apt-get update
Step 4: Install the MongoDB packages.You can install either the latest stable version of MongoDB or a specic
version of MongoDB.
Install the latest stable version of MongoDB.Issue the following command:
sudo apt-get install -y mongodb-org
Install a specic release of MongoDB.Specify each component package individually and append the version num-
ber to the package name, as in the following example that installs the2.6.1release of MongoDB:
2
http://docs.mongodb.org/10gen-gpg-key.asc
10 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
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 specic version of MongoDB.Although you can specify any available version of MongoDB,apt-getwill
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
echo
echo
echo
echo
Previous versions of MongoDB packages use different naming conventions. See the
more information
3
.
Run MongoDB The MongoDB instance stores its data les in/var/lib/mongodb and its log les in
/var/log/mongodbby default, and runs using themongodbuser account. You can specify alternate log and
data le directories in/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional
information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongodband/var/log/mongodbdirectories to give this users access to these directories.
Step 1: Start MongoDB.Issue the following command to startmongod:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyVerify that themongodprocess has started successfully
by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.Issue the following command to restartmongod:
sudo service mongod restart
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
3
http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu
2.1. Installation Guides 11

MongoDB Documentation, Release 2.6.4
Install MongoDB on Debian
OverviewUse this tutorial to install MongoDB on Debian systems from.debpackages. While some Debian
distributions include their own MongoDB packages, the ofcial 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 theInstall MongoDB on Ubuntu(page 9) tutorial.
PackagesMongoDB provides packages of the ofcially supported MongoDB builds in it's own repository. This
repository provides the MongoDB distribution in the following packages:
mongodb-org
This package is ametapackagethat will automatically install the four component packages listed below.
mongodb-org-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-org-mongos
This package contains themongosdaemon.
mongodb-org-shell
This package contains themongoshell.
mongodb-org-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
Control ScriptsThemongodb-orgpackage includes variouscontrol scripts, including the init script
/etc/init.d/mongod. These scripts are used to stop, start, and restart daemon processes.
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts. See
http://docs.mongodb.org/manualreference/configuration-options for documentation of the
conguration le.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script for use in such environments. See the
mongosreference for conguration details.
ConsiderationsFor production deployments, always run MongoDB on 64-bit systems.
You cannot install this package concurrently with themongodb,mongodb-server, ormongodb-clientspack-
ages that your release of Debian may include.
The default/etc/mongodb.conf conguration le supplied by the 2.6 series packages hasbind_ip`set to
127.0.0.1by default. Modify this setting as needed for your environment before initializing areplica set.
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation of an older release, please refer to the documentation for the appropriate version.
Install MongoDBThe Debian package management tools (i.e.dpkgandapt) ensure package consistency and
authenticity by requiring that distributors sign packages with GPG keys.
12 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Step 1: Import the public key used by the package management system.Issue the following command to add
the
4
to the system key ring.
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
Step 2: Create a/etc/apt/sources.list.d/mongodb.list le for MongoDB.Create the list le using
the following command:
echo
Step 3: Reload local package database.Issue the following command to reload the local package database:
sudo apt-get update
Step 4: Install the MongoDB packages.You can install either the latest stable version of MongoDB or a specic
version of MongoDB.
Install the latest stable version of MongoDB.Issue the following command:
sudo apt-get install -y mongodb-org
Install a specic release of MongoDB.Specify each component package individually and append the version num-
ber to the package name, as in the following example that installs the2.6.1release 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 specic version of MongoDB.Although you can specify any available version of MongoDB,apt-getwill
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
echo
echo
echo
echo
Previous versions of MongoDB packages use different naming conventions. See the
more information
5
.
Run MongoDB The MongoDB instance stores its data les in/var/lib/mongodb and its log les in
/var/log/mongodbby default, and runs using themongodbuser account. You can specify alternate log and
data le directories in/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional
information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongodband/var/log/mongodbdirectories to give this users access to these directories.
4
http://docs.mongodb.org/10gen-gpg-key.asc
5
http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-ubuntu
2.1. Installation Guides 13

MongoDB Documentation, Release 2.6.4
Step 1: Start MongoDB.Issue the following command to startmongod:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyVerify that themongodprocess has started successfully
by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.Issue the following command to restartmongod:
sudo service mongod restart
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB on Linux Systems
OverviewCompiled versions of MongoDB for Linux provide a simple option for installing MongoDB for other
Linux systems without supported packages.
ConsiderationsFor production deployments, always run MongoDB on 64-bit systems.
Install MongoDBMongoDB provides archives for both 64-bit and 32-bit Linux. Follow the installation procedure
appropriate for your system.
Install for 64-bit Linux
Step 1: Download the binary les 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.4.tgz
Step 2: Extract the les from the downloaded archive.For example, from a system shell, you can extract through
thetarcommand:
tar -zxvf mongodb-linux-x86_64-2.6.4.tgz
14 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
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.4/ mongodb
Step 4: Ensure the location of the binaries is in thePATHvariable.The MongoDB binaries are in thebin/
directory of the archive. To ensure that the binaries are in yourPATH, you can modify yourPATH.
For example, you can add the following line to your shell'srcle (e.g.~/.bashrc):
export=<mongodb-install-directory>/bin:$PATH
Replace<mongodb-install-directory> with the path to the extracted MongoDB archive.
Install for 32-bit Linux
Step 1: Download the binary les 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-i686-2.6.4.tgz
Step 2: Extract the les from the downloaded archive.For example, from a system shell, you can extract through
thetarcommand:
tar -zxvf mongodb-linux-i686-2.6.4.tgz
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.4/ mongodb
Step 4: Ensure the location of the binaries is in thePATHvariable.The MongoDB binaries are in thebin/
directory of the archive. To ensure that the binaries are in yourPATH, you can modify yourPATH.
For example, you can add the following line to your shell'srcle (e.g.~/.bashrc):
export=<mongodb-install-directory>/bin:$PATH
Replace<mongodb-install-directory> with the path to the extracted MongoDB archive.
Run MongoDB
Step 1: Create the data directory.Before you start MongoDB for the rst time, create the directory to which
themongodprocess will write data. By default, themongodprocess uses the/data/dbdirectory. If you create a
directory other than this one, you must specify that directory in thedbpathoption when starting themongodprocess
later in this procedure.
The following example command creates the default/data/dbdirectory:
2.1. Installation Guides 15

MongoDB Documentation, Release 2.6.4
mkdir -p /data/db
Step 2: Set permissions for the data directory.Before runningmongodfor the rst time, ensure that the user
account runningmongodhas read and write permissions for the directory.
Step 3: Run MongoDB.To run MongoDB, run themongodprocess at the system prompt. If necessary, specify the
path of themongodor the data directory. See the following examples.
Run without specifying pathsIf your systemPATHvariable includes the location of themongodbinary and if you
use the default data directory (i.e.,/data/db), simply entermongodat the system prompt:
mongod
Specify the path of themongodIf yourPATHdoes not include the location of themongodbinary, enter the full
path to themongodbinary at the system prompt:
<path to binary>/mongod
Specify the path of the data directoryIf you do not use the default data directory (i.e.,/data/db), specify the
path to the data directory using the--dbpathoption:
mongod --dbpath <path to data directory>
Step 4: Stop MongoDB as needed.To stop MongoDB, pressControl+Cin the terminal where themongod
instance is running.
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
2.1.2
Overview
Use this tutorial to install MongoDB on 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
6
or through the
site
7
.
Install MongoDB
You can install MongoDB with
8
or manually. This section describes both.
6
http://brew.sh/
7
http://www.mongodb.org/downloads
8
http://brew.sh/
16 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Install MongoDB with Homebrew
Homebrew
9
installs binary packages based on published formulae. This section describes how to updatebrewto
the latest packages and install MongoDB. Homebrew requires some initial setup and conguration, which is beyond
the scope of this document.
Step 1: Update Homebrew's package database.
In a system shell, issue the following command:
brew update
Step 2: Install MongoDB.
You can install MongoDB with viabrewwith several different options. Use one of the following operations:
Install the MongoDB BinariesTo install the MongoDB binaries, issue the following command in a system shell:
brew install mongodb
Build MongoDB from Source with SSL SupportTo build MongoDB from the source les and include SSL sup-
port, issue the following from a system shell:
brew install mongodb --with-openssl
Install the Latest Development Release of MongoDBTo 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 usehomebrew(page 17).
Step 1: Download the binary les for the desired release of MongoDB.
Download the binaries fromhttps://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.4.tgz
Step 2: Extract the les from the downloaded archive.
For example, from a system shell, you can extract through thetarcommand:
9
http://brew.sh/
2.1. Installation Guides 17

MongoDB Documentation, Release 2.6.4
tar -zxvf mongodb-osx-x86_64-2.6.4.tgz
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.4/ mongodb
Step 4: Ensure the location of the binaries is in thePATHvariable.
The MongoDB binaries are in thebin/directory of the archive. To ensure that the binaries are in yourPATH, you
can modify yourPATH.
For example, you can add the following line to your shell'srcle (e.g.~/.bashrc):
export=<mongodb-install-directory>/bin:$PATH
Replace<mongodb-install-directory> with the path to the extracted MongoDB archive.
Run MongoDB
Step 1: Create the data directory.
Before you start MongoDB for the rst time, create the directory to which themongodprocess will write data. By
default, themongodprocess uses the/data/dbdirectory. If you create a directory other than this one, you must
specify that directory in thedbpathoption when starting themongodprocess later in this procedure.
The following example command creates the default/data/dbdirectory:
mkdir -p /data/db
Step 2: Set permissions for the data directory.
Before runningmongodfor the rst time, ensure that the user account runningmongodhas read and write permis-
sions for the directory.
Step 3: Run MongoDB.
To run MongoDB, run themongodprocess at the system prompt. If necessary, specify the path of themongodor the
data directory. See the following examples.
Run without specifying pathsIf your systemPATHvariable includes the location of themongodbinary and if you
use the default data directory (i.e.,/data/db), simply entermongodat the system prompt:
mongod
18 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Specify the path of themongodIf yourPATHdoes not include the location of themongodbinary, enter the full
path to themongodbinary at the system prompt:
<path to binary>/mongod
Specify the path of the data directoryIf you do not use the default data directory (i.e.,/data/db), specify the
path to the data directory using the--dbpathoption:
mongod --dbpath <path to data directory>
Step 4: Stop MongoDB as needed.
To stop MongoDB, pressControl+Cin the terminal where themongodinstance is running.
Step 5: Begin using MongoDB.
To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also consider theProduction Notes
(page 188) document before deploying MongoDB in a production environment.
2.1.3
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
resolve an issue with memory mapped les on Windows
10
.
Install MongoDB
Step 1: Determine which MongoDB build you need.
There are three builds of MongoDB for Windows:
MongoDB for Windows Server 2008 R2 edition(i.e. 2008R2) 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 64-bitruns on any 64-bit version of Windows newer than Windows XP, including Windows
Server 2008 R2 and Windows 7 64-bit.
MongoDB for Windows 32-bitruns on any 32-bit version of Windows newer than Windows XP. 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.
10
http://support.microsoft.com/kb/2731284
2.1. Installation Guides 19

MongoDB Documentation, Release 2.6.4
To nd which version of Windows you are running, enter the following command in theCommand Prompt:
wmic os get osarchitecture
Step 2: Download MongoDB for Windows.
Download the latest production release of MongoDB from the
11
. 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 3: Install the downloaded le.
In Windows Explorer, locate the downloaded MongoDB msi le, which typically is located in the defaultDownloads
folder. Double-click themsile. A set of screens will appear to guide you through the installation process.
Step 4: Move the MongoDB folder to another location (optional).
To move the MongoDB folder, you must issue the move command as an Administrator. For example, to move the
folder toC:\mongodb:
SelectStart Menu>All Programs>Accessories.
Right-clickCommand Promptand selectRun as Administratorfrom the popup menu.
Issue the following commands:
cd \
move C:\mongodb-win32- *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: est\mongodb)
Run MongoDB
Warning:Do not makemongod.exevisible on public networks without running in Secure Mode with the
authsetting. MongoDB is designed to be run in trusted environments, and the database does not enable Secure
Mode by default.
Step 1: Set up the MongoDB environment.
MongoDB requires adata directoryto store all data. MongoDB's default data directory path is\data\db. Create
this folder using the following commands from aCommand Prompt:
md \data\db
You can specify an alternate path for data les using the--dbpathoption tomongod.exe, for example:
C:\mongodbin\mongod.exe --dbpath d: est\mongodb\data
If your path includes spaces, enclose the entire path in double quotes, for example:
11
http://www.mongodb.org/downloads
20 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
C:\mongodbin\mongod.exe --dbpath "d: est\mongo db data"
Step 2: Start MongoDB.
To start MongoDB, runmongod.exe. For example, from theCommand Prompt:
C:\Program Files\MongoDBin\mongod.exe
This starts the main MongoDB database process. Thewaiting for connections message in the console
output indicates that themongod.exeprocess is running successfully.
Depending on the security level of your system, Windows may pop up aSecurity Alertdialog box about block-
ing some features ofC:\Program Files\MongoDBin\mongod.exe from communicating on networks.
All users should selectPrivate Networks, such as my home or work network and clickAllow
access. For additional information on security and MongoDB, please see theSecurity Documentation(page 281).
Step 3: Connect to MongoDB.
To connect to MongoDB through themongo.exeshell, open anotherCommand Prompt. When connecting, specify
the data directory if necessary. This step provides several example connection commands.
If your MongoDB installation uses the default data directory, connect without specifying the data directory:
C:\mongodbin\mongo.exe
If you installation uses a different data directory, specify the directory when connecting, as in this example:
C:\mongodbin\mongod.exe --dbpath d: est\mongodb\data
If your path includes spaces, enclose the entire path in double quotes. For example:
C:\mongodbin\mongod.exe --dbpath "d: est\mongo db data"
If you want to develop applications using .NET, see the documentation of
12
for more information.
Step 4: Begin using MongoDB.
To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also consider theProduction Notes
(page 188) document before deploying MongoDB in a production environment.
Congure a Windows Service for MongoDB
Note:There is a known issue for MongoDB 2.6.0,
13
, which prevents the use of the instructions
in this section. For MongoDB 2.6.0, useManually Create a Windows Service for MongoDB(page 22) to create a
Windows Service for MongoDB instead.
12
http://docs.mongodb.org/ecosystem/drivers/csharp
13
https://jira.mongodb.org/browse/SERVER-13515
2.1. Installation Guides 21

MongoDB Documentation, Release 2.6.4
Step 1: Congure directories and les.
Create aconfiguration file and a directory path for MongoDB log output (logpath):
Create a specic directory for MongoDB log les:
mdC:\Program Files\MongoDB\log"
In theCommand Prompt, create a conguration le for thelogpathoption for MongoDB:
echo logpath="C:\Program Files\MongoDB\log\mongo.log"C:\Program Files\MongoDB\mongod.cfg"
Step 2: Run the MongoDB service.
Run all of the following commands inCommand Promptwith Administrative Privileges:
Install the MongoDB service. For--installto succeed, youmustspecify thelogpathrun-time option.
"C:\Program Files\MongoDBin\mongod.exe"C:\Program Files\MongoDB\mongod.cfg"
Modify the path to themongod.cfgle as needed.
To use an alternatedbpath, specify the path in the conguration le (e.g. C:\Program
Files\MongoDB\mongod.cfg ) or on the command line with the--dbpathoption.
If thedbpathdirectory does not exist,mongod.exewill not start. The default value fordbpathis\data\db.
If needed, you can install services for multiple instances ofmongod.exeormongos.exe. Install each service with
a unique--serviceNameand--serviceDisplayName . Use multiple instances only when sufcient system
resources exist and your system design requires it.
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:\Program Files\MongoDBin\mongod.exe"
Manually Create a Windows Service for MongoDB
The following procedure assumes you have installed MongoDB using the MSI installer, with the default path
C:\Program Files\MongoDB 2.6 Standard .
If you have installed in an alternative directory, you will need to adjust the paths as appropriate.
Step 1: Open an Administrator command prompt.
Windows 7 / Vista / Server 2008 (and R2)PressWin + R, then typecmd, then pressCtrl + Shift +
Enter.
22 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Windows 8PressWin + X, then pressA.
Execute the remaining steps from the Administrator command prompt.
Step 2: Create directories.
Create directories for your database and log les:
mkdir c:\data\db
mkdir c:\data\log
Step 3: Create a conguration le.
Create aconfiguration file. This le can include any of theconfiguration options formongod, but
mustinclude a valid setting forlogpath:
The following creates a conguration le, specifying both thelogpathand thedbpathsettings in the conguration
le:
echo logpath=c:\data\log\mongod.log> "C:\Program Files\MongoDB 2.6 Standard\mongod.cfg"
echo dbpath=c:\data\db>> "C:\Program Files\MongoDB 2.6 Standard\mongod.cfg"
Step 4: Create the MongoDB service.
Create the MongoDB service.
sc.exe create MongoDB binPath= "\"C:\Program Files\MongoDB 2.6 Standardin\mongod.exe\" --service --config=\"C:\Program Files\MongoDB 2.6 Standard\mongod.cfg\"" DisplayName= "MongoDB 2.6 Standard" start= "auto"
sc.exerequires a space between = and the conguration values (eg binPath= ), and a to escape double quotes.
If successfully created, the following log message will display:
[SC]
Step 5: Start the MongoDB service.
net start MongoDB
Step 6: 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, rst stop the service and then run the following command:
sc.exe delete MongoDB
2.1. Installation Guides 23

MongoDB Documentation, Release 2.6.4
2.1.4
These documents provide instructions to install MongoDB Enterprise for Linux and Windows Systems.
Install MongoDB Enterprise on Red Hat(page 24)Install the MongoDB Enterprise build and required dependen-
cies on Red Hat Enterprise or CentOS Systems using packages.
Install MongoDB Enterprise on Ubuntu(page 27)Install the MongoDB Enterprise build and required dependencies
on Ubuntu Linux Systems using packages.
Install MongoDB Enterprise on Debian(page 30)Install the MongoDB Enterprise build and required dependencies
on Debian Linux Systems using packages.
Install MongoDB Enterprise on SUSE(page 32)Install the MongoDB Enterprise build and required dependencies
on SUSE Enterprise Linux.
Install MongoDB Enterprise on Amazon AMI(page 34)Install the MongoDB Enterprise build and required depen-
dencies on Amazon Linux AMI.
Install MongoDB Enterprise on Windows(page 36)Install the MongoDB Enterprise build and required dependen-
cies using the.msiinstaller.
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.rpmpackages.
Packages
MongoDB provides packages of the ofcially 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 ametapackagethat will automatically install the four component packages listed below.
mongodb-enterprise-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-enterprise-mongos
This package contains themongosdaemon.
mongodb-enterprise-shell
This package contains themongoshell.
mongodb-enterprise-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
24 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Control Scripts
Themongodb-enterprise package includes variouscontrol scripts, including the init script
/etc/rc.d/init.d/mongod .
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script.
Considerations
MongoDB only provides Enterprise packages for Red Hat Enterprise Linux and CentOS Linux versions 5 and 6,
64-bit.
The default/etc/mongodb.conf conguration le supplied by the 2.6 series packages hasbind_ip`set to
127.0.0.1by default. Modify this setting as needed for your environment before initializing areplica set.
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation 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.
Step 1: Congure repository.Create an/etc/yum.repos.d/mongodb-enterprise.repo le so that
you can install MongoDB enterprise directly, usingyum.
Use the following repository le to specify thelateststable 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 installonlyversions of MongoDB for the2.6release. If you'd like to install Mon-
goDB Enterprise packages from a particularrelease series(page 808), such as 2.4 or 2.6, you can specify the re-
lease series in the repository conguration. For example, to restrict your system to the 2.6 release series, create a
/etc/yum.repos.d/mongodb-enterprise-2.6.repo le to hold the following conguration 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
.repoles for each release can also be found
14
. Remember that odd-numbered minor release
versions (e.g. 2.5) are development versions and are unsuitable for production deployment.
Step 1: Install the MongoDB Enterprise packages and associated tools.You can install either the latest stable
version of MongoDB Enterprise or a specic version of MongoDB Enterprise.
14
https://repo.mongodb.com/yum/redhat/
2.1. Installation Guides 25

MongoDB Documentation, Release 2.6.4
Install the latest stable version of MongoDB Enterprise.Issue the following command:
sudo yum install -y mongodb-enterprise
Step 2: Optional. Manage Installed Version
Install a specic 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 the2.6.1release 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 specic version of MongoDB Enterprise.Although you can specify any available version of MongoDB
Enterprise,yumwill upgrade the packages when a newer version becomes available. To prevent unintended upgrades,
pin the package. To pin a package, add the followingexcludedirective to your/etc/yum.confle:
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
more information
15
.
Step 3: When the install completes, you can run MongoDB.
Run MongoDB Enterprise
Important:You must congure SELinux to allow MongoDB to start on Red Hat Linux-based systems (Red Hat
Enterprise Linux, CentOS, Fedora). Administrators have three options:
Default MongoDB Port(page 380) for more
information on MongoDB's default ports. For default settings, this can be accomplished by running
semanage port -a -t mongodb_port_t -p tcp 27017
permissivemode in/etc/selinux.conf. The line
SELINUX=enforcing
should be changed to
SELINUX=permissive

SELINUX=disabled
All three options requirerootprivileges. 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 les in/var/lib/mongoand its log les in/var/log/mongodb
by default, and runs using themongoduser account. You can specify alternate log and data le directories in
/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional information.
15
http://docs.mongodb.org/v2.4/tutorial/install-mongodb-on-linux
26 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongoand/var/log/mongodbdirectories to give this users access to these directories.
Step 1: Start MongoDB.You can start themongodprocess by issuing the following command:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyYou can verify that themongodprocess has started suc-
cessfully by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:
sudo chkconfig mongod on
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.You can restart themongodprocess 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 le.
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB Enterprise on Ubuntu
Overview
Use this tutorial to install MongoDB Enterprise on Ubuntu Linux systems from.debpackages.
Packages
MongoDB provides packages of the ofcially 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 ametapackagethat will automatically install the four component packages listed below.
mongodb-enterprise-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-enterprise-mongos
This package contains themongosdaemon.
2.1. Installation Guides 27

MongoDB Documentation, Release 2.6.4
mongodb-enterprise-shell
This package contains themongoshell.
mongodb-enterprise-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
Control Scripts
Themongodb-enterprise package includes variouscontrol scripts, including the init script
/etc/rc.d/init.d/mongod .
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script.
Considerations
MongoDB only provides Enterprise packages for Ubuntu 12.04 LTS (Precise Pangolin).
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation of an older release, please refer to the documentation for the appropriate version.
Install MongoDB Enterprise
Step 1: Import the public key used by the package management system.The Ubuntu package management tools
(i.e.dpkgandapt) ensure package consistency and authenticity by requiring that distributors sign packages with
GPG keys. Issue the following command to import the
16
:
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10
Step 2: Create a/etc/apt/sources.list.d/mongodb-enterprise.list le for MongoDB.Create
the list le using the following command:
echo
If you'd like to install MongoDB Enterprise packages from a particularrelease series(page 808), such as 2.4 or 2.6,
you can specify the release series in the repository conguration. For example, to restrict your system to the 2.6 release
series, add the following repository:
echo
Step 3: Reload local package database.Issue the following command to reload the local package database:
sudo apt-get update
16
http://docs.mongodb.org/10gen-gpg-key.asc
28 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
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 specic 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 the2.6.1`release of MongoDB Enter-
prise:
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. Howeverapt-getwill 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
echo
echo
echo
echo
Previous versions of MongoDB Enterprise packages use different naming conventions. See the
mentation
17
for more information.
Run MongoDB Enterprise
The MongoDB instance stores its data les in/var/lib/mongodband its log les in/var/log/mongodb
by default, and runs using themongodbuser account. You can specify alternate log and data le directories in
/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongodband/var/log/mongodbdirectories to give this users access to these directories.
Step 1: Start MongoDB.Issue the following command to startmongod:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyVerify that themongodprocess has started successfully
by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.Issue the following command to restartmongod:
17
http://docs.mongodb.org/v2.4/tutorial/install-mongodb-enterprise
2.1. Installation Guides 29

MongoDB Documentation, Release 2.6.4
sudo service mongod restart
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB Enterprise on Debian
Overview
Use this tutorial to install MongoDB Enterprise on Debian Linux systems from.debpackages.
Packages
MongoDB provides packages of the ofcially 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 ametapackagethat will automatically install the four component packages listed below.
mongodb-enterprise-server
This package contains themongoddaemon and associated conguration and init scripts.
mongodb-enterprise-mongos
This package contains themongosdaemon.
mongodb-enterprise-shell
This package contains themongoshell.
mongodb-enterprise-tools
This package contains the following MongoDB tools:mongoimport bsondump ,mongodump,
mongoexport,mongofiles,mongoimport,mongooplog,mongoperf,mongorestore,
mongostat, andmongotop.
Control Scripts
Themongodb-enterprise package includes variouscontrol scripts, including the init script
/etc/rc.d/init.d/mongod .
The package congures MongoDB using the/etc/mongod.confle in conjunction with the control scripts.
As of version 2.6.4, there are no control scripts formongos. Themongosprocess is used only insharding(page 613).
You can use themongodinit script to derive your ownmongoscontrol script.
Considerations
Changed in version 2.6: The package structure and names have changed as of version 2.6. For instructions on instal-
lation 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.
30 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Install MongoDB Enterprise
Step 1: Import the public key used by the package management system.Issue the following command to add
the
18
to the system key ring.
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
Step 2: Create a/etc/apt/sources.list.d/mongodb-enterprise.list le for MongoDB.Create
the list le using the following command:
echo
If you'd like to install MongoDB Enterprise packages from a particularrelease series(page 808), such as 2.6, you can
specify the release series in the repository conguration. For example, to restrict your system to the 2.6 release series,
add the following repository:
echo
Step 3: Reload local package database.Issue the following command to reload the local package database:
sudo apt-get update
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 specic 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 the2.6.1`release of MongoDB Enter-
prise:
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. Howeverapt-getwill 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
echo
echo
echo
echo
Run MongoDB Enterprise
The MongoDB instance stores its data les in/var/lib/mongodband its log les in/var/log/mongodb
by default, and runs using themongodbuser account. You can specify alternate log and data le directories in
/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongodband/var/log/mongodbdirectories to give this users access to these directories.
18
http://docs.mongodb.org/10gen-gpg-key.asc
2.1. Installation Guides 31

MongoDB Documentation, Release 2.6.4
Step 1: Start MongoDB.Issue the following command to startmongod:
sudo service mongod start
Step 2: Verify that MongoDB has started successfullyVerify that themongodprocess has started successfully
by checking the contents of the log le at/var/log/mongodb/mongod.log for a line reading
[initandlisten] waiting for connections on port <port>
where<port>is the port congured in/etc/mongod.conf,27017by default.
Step 3: Stop MongoDB.As needed, you can stop themongodprocess by issuing the following command:
sudo service mongod stop
Step 4: Restart MongoDB.Issue the following command to restartmongod:
sudo service mongod restart
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB Enterprise on SUSE
Overview
Use this tutorial to installMongoDB Enterpriseon 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
32 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Install MongoDB Enterprise
Note:The Enterprise packages include an example SNMP conguration le namedmongod.conf. This le is not
a MongoDB conguration le.
Step 1: Download and install the MongoDB Enterprise packages. After you have in-
stalled the required prerequisite packages, download and install the MongoDB Enterprise packages
from. The MongoDB binaries are located in the
http://docs.mongodb.org/manualbin 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-subscription-suse11-2.6.4.tgz
tar -zxvf mongodb-linux-x86_64-subscription-suse11-2.6.4.tgz
cp -R -n mongodb-linux-x86_64-subscription-suse11-2.6.4/ mongodb
Step 2: Ensure the location of the MongoDB binaries is included in thePATHvariable.Once you have copied
the MongoDB binaries to their target location, ensure that the location is included in yourPATHvariable. If it is not,
either include it or create symbolic links from the binaries to a directory that is included.
Run MongoDB Enterprise
Step 1: Create the data directory.Before you start MongoDB for the rst time, create the directory to which
themongodprocess will write data. By default, themongodprocess uses the/data/dbdirectory. If you create a
directory other than this one, you must specify that directory in thedbpathoption when starting themongodprocess
later in this procedure.
The following example command creates the default/data/dbdirectory:
mkdir -p /data/db
Step 2: Set permissions for the data directory.Before runningmongodfor the rst time, ensure that the user
account runningmongodhas read and write permissions for the directory.
Step 3: Run MongoDB.To run MongoDB, run themongodprocess at the system prompt. If necessary, specify the
path of themongodor the data directory. See the following examples.
Run without specifying pathsIf your systemPATHvariable includes the location of themongodbinary and if you
use the default data directory (i.e.,/data/db), simply entermongodat the system prompt:
mongod
Specify the path of themongodIf yourPATHdoes not include the location of themongodbinary, enter the full
path to themongodbinary at the system prompt:
<path to binary>/mongod
2.1. Installation Guides 33

MongoDB Documentation, Release 2.6.4
Specify the path of the data directoryIf you do not use the default data directory (i.e.,/data/db), specify the
path to the data directory using the--dbpathoption:
mongod --dbpath <path to data directory>
Step 4: Stop MongoDB as needed.To stop MongoDB, pressControl+Cin the terminal where themongod
instance is running.
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB Enterprise on Amazon Linux AMI
Overview
Use this tutorial to installMongoDB Enterpriseon 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 conguration le namedmongod.conf. This le is not
a MongoDB conguration le.
Step 1: Download and install the MongoDB Enterprise packages. After you have in-
stalled the required prerequisite packages, download and install the MongoDB Enterprise packages
from. The MongoDB binaries are located in the
http://docs.mongodb.org/manualbin directory of the archive. To download and install, use the
following sequence of commands.
34 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
curl -O http://downloads.10gen.com/linux/mongodb-linux-x86_64-subscription-amzn64-2.6.4.tgz
tar -zxvf mongodb-linux-x86_64-subscription-amzn64-2.6.4.tgz
cp -R -n mongodb-linux-x86_64-subscription-amzn64-2.6.4/ mongodb
Step 2: Ensure the location of the MongoDB binaries is included in thePATHvariable.Once you have copied
the MongoDB binaries to their target location, ensure that the location is included in yourPATHvariable. 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 les in/var/lib/mongoand its log les in/var/log/mongodb
by default, and runs using themongoduser account. You can specify alternate log and data le directories in
/etc/mongodb.conf. SeesystemLog.pathandstorage.dbPathfor additional information.
If you change the user that runs the MongoDB process, youmustmodify the access control rights to the
/var/lib/mongoand/var/log/mongodbdirectories to give this users access to these directories.
Step 1: Create the data directory.Before you start MongoDB for the rst time, create the directory to which
themongodprocess will write data. By default, themongodprocess uses the/data/dbdirectory. If you create a
directory other than this one, you must specify that directory in thedbpathoption when starting themongodprocess
later in this procedure.
The following example command creates the default/data/dbdirectory:
mkdir -p /data/db
Step 2: Set permissions for the data directory.Before runningmongodfor the rst time, ensure that the user
account runningmongodhas read and write permissions for the directory.
Step 3: Run MongoDB.To run MongoDB, run themongodprocess at the system prompt. If necessary, specify the
path of themongodor the data directory. See the following examples.
Run without specifying pathsIf your systemPATHvariable includes the location of themongodbinary and if you
use the default data directory (i.e.,/data/db), simply entermongodat the system prompt:
mongod
Specify the path of themongodIf yourPATHdoes not include the location of themongodbinary, enter the full
path to themongodbinary at the system prompt:
<path to binary>/mongod
Specify the path of the data directoryIf you do not use the default data directory (i.e.,/data/db), specify the
path to the data directory using the--dbpathoption:
mongod --dbpath <path to data directory>
Step 4: Stop MongoDB as needed.To stop MongoDB, pressControl+Cin the terminal where themongod
instance is running.
2.1. Installation Guides 35

MongoDB Documentation, Release 2.6.4
Step 5: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Install MongoDB Enterprise on Windows
New in version 2.6.
Overview
Use this tutorial to installMongoDB Enterpriseon 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
Step 1: Download MongoDB Enterprise for Windows.Download the latest production release of
Enterprise
19
Step 2: Install MongoDB Enterprise for Windows.Run the downloaded MSI installer. Make conguration
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: est\mongodb ) and run it from there. The installation wizard includes an option to select an
installation directory.
Run MongoDB Enterprise
Warning:Do not makemongod.exevisible on public networks without running in Secure Mode with the
authsetting. MongoDB is designed to be run in trusted environments, and the database does not enable Secure
Mode by default.
Step 1: Set up the MongoDB environment.MongoDB requires adata directoryto store all data. MongoDB's
default data directory path is\data\db. Create this folder using the following commands from aCommand Prompt:
md \data\db
You can specify an alternate path for data les using the--dbpathoption tomongod.exe, for example:
C:\mongodbin\mongod.exe --dbpath d: est\mongodb\data
If your path includes spaces, enclose the entire path in double quotes, for example:
19
http://www.mongodb.com/products/mongodb-enterprise
36 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
C:\mongodbin\mongod.exe --dbpath "d: est\mongo db data"
Step 2: Start MongoDB.To start MongoDB, runmongod.exe. For example, from theCommand Prompt:
C:\Program Files\MongoDBin\mongod.exe
This starts the main MongoDB database process. Thewaiting for connections message in the console
output indicates that themongod.exeprocess is running successfully.
Depending on the security level of your system, Windows may pop up aSecurity Alertdialog box about block-
ing some features ofC:\Program Files\MongoDBin\mongod.exe from communicating on networks.
All users should selectPrivate Networks, such as my home or work network and clickAllow
access. For additional information on security and MongoDB, please see theSecurity Documentation(page 281).
Step 3: Connect to MongoDB.To connect to MongoDB through themongo.exeshell, open anotherCommand
Prompt. When connecting, specify the data directory if necessary. This step provides several example connection
commands.
If your MongoDB installation uses the default data directory, connect without specifying the data directory:
C:\mongodbin\mongo.exe
If you installation uses a different data directory, specify the directory when connecting, as in this example:
C:\mongodbin\mongod.exe --dbpath d: est\mongodb\data
If your path includes spaces, enclose the entire path in double quotes. For example:
C:\mongodbin\mongod.exe --dbpath "d: est\mongo db data"
If you want to develop applications using .NET, see the documentation of
20
for more information.
Step 4: Begin using MongoDB.To begin using MongoDB, seeGetting Started with MongoDB(page 43). Also
consider theProduction Notes(page 188) document before deploying MongoDB in a production environment.
Congure a Windows Service for MongoDB Enterprise
You can set up the MongoDB server as aWindows Servicethat starts automatically at boot time.
Step 1: Congure directories and les.Create aconfiguration file and a directory path for MongoDB log
output (logpath):
Create a specic directory for MongoDB log les:
mdC:\Program Files\MongoDB\log"
In theCommand Prompt, create a conguration le for thelogpathoption for MongoDB:
echo logpath="C:\Program Files\MongoDB\log\mongo.log"C:\Program Files\MongoDB\mongod.cfg"
20
http://docs.mongodb.org/ecosystem/drivers/csharp
2.1. Installation Guides 37

MongoDB Documentation, Release 2.6.4
Step 2: Run the MongoDB service.Run all of the following commands inCommand Promptwith Administrative
Privileges:
Install the MongoDB service. For--installto succeed, youmustspecify thelogpathrun-time option.
"C:\Program Files\MongoDBin\mongod.exe"C:\Program Files\MongoDB\mongod.cfg"
Modify the path to themongod.cfgle as needed.
To use an alternatedbpath, specify the path in the conguration le (e.g. C:\Program
Files\MongoDB\mongod.cfg ) or on the command line with the--dbpathoption.
If thedbpathdirectory does not exist,mongod.exewill not start. The default value fordbpathis\data\db.
If needed, you can install services for multiple instances ofmongod.exeormongos.exe. Install each service with
a unique--serviceNameand--serviceDisplayName . Use multiple instances only when sufcient system
resources exist and your system design requires it.
Step 3: Stop or remove the MongoDB service as needed.To stop the MongoDB service use the following com-
mand:
net stop MongoDB
To remove the MongoDB service use the following command:
"C:\Program Files\MongoDBin\mongod.exe"
Congure a Windows Service for MongoDB Enterprise
Note:There is a known issue for MongoDB 2.6.0,
21
, which prevents the use of the instructions
in this section. For MongoDB 2.6.0, useManually Create a Windows Service for MongoDB Enterprise(page 39) to
create a Windows Service for MongoDB.
You can set up the MongoDB server as aWindows Servicethat starts automatically at boot time.
Step 1: Congure directories and les.Create aconfiguration file and a directory path for MongoDB log
output (logpath):
Create a specic directory for MongoDB log les:
mdC:\Program Files\MongoDB\log"
In theCommand Prompt, create a conguration le for thelogpathoption for MongoDB:
echo logpath="C:\Program Files\MongoDB\log\mongo.log"C:\Program Files\MongoDB\mongod.cfg"
Step 2: Run the MongoDB service.Run all of the following commands inCommand Promptwith Administrative
Privileges:
Install the MongoDB service. For--installto succeed, youmustspecify thelogpathrun-time option.
"C:\Program Files\MongoDBin\mongod.exe"C:\Program Files\MongoDB\mongod.cfg"
21
https://jira.mongodb.org/browse/SERVER-13515
38 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Modify the path to themongod.cfgle as needed.
To use an alternatedbpath, specify the path in the conguration le (e.g. C:\Program
Files\MongoDB\mongod.cfg ) or on the command line with the--dbpathoption.
If thedbpathdirectory does not exist,mongod.exewill not start. The default value fordbpathis\data\db.
If needed, you can install services for multiple instances ofmongod.exeormongos.exe. Install each service with
a unique--serviceNameand--serviceDisplayName . Use multiple instances only when sufcient system
resources exist and your system design requires it.
Step 3: Stop or remove the MongoDB service as needed.To stop the MongoDB service use the following com-
mand:
net stop MongoDB
To remove the MongoDB service use the following command:
"C:\Program Files\MongoDBin\mongod.exe"
Manually Create a Windows Service for MongoDB Enterprise
The following procedure assumes you have installed MongoDB using the MSI installer, with the default path
C:\Program Files\MongoDB 2.6 Enterprise .
If you have installed in an alternative directory, you will need to adjust the paths as appropriate.
Step 1: Open an Administrator command prompt.PressWin + R, then typecmd, then pressCtrl + Shift
+ Enter.
Execute the remaining steps from the Administrator command prompt.
Step 2: Create directories.Create directories for your database and log les:
mkdir c:\data\db
mkdir c:\data\log
Step 3: Create a conguration le.Create aconfiguration file. This le can include any of the
configuration options formongod, butmustinclude a valid setting forlogpath:
The following creates a conguration le, specifying both thelogpathand thedbpathsettings in the conguration
le:
echo logpath=c:\data\log\mongod.log> "C:\Program Files\MongoDB 2.6 Standard\mongod.cfg"
echo dbpath=c:\data\db>> "C:\Program Files\MongoDB 2.6 Standard\mongod.cfg"
Step 4: Create the MongoDB service.Create the MongoDB service.
sc.exe create MongoDB binPath= "\"C:\Program Files\MongoDB 2.6 Enterprisein\mongod.exe\" --service --config=\"C:\Program Files\MongoDB 2.6 Standard\mongod.cfg\"" DisplayName= "MongoDB 2.6 Standard" start= "auto"
sc.exerequires a space between = and the conguration values (eg binPath= ), and a to escape double quotes.
If successfully created, the following log message will display:
2.1. Installation Guides 39

MongoDB Documentation, Release 2.6.4
[SC]
Step 5: Start the MongoDB service.
net start MongoDB
Step 6: Stop or remove the MongoDB service as needed.To stop the MongoDB service, use the following com-
mand:
net stop MongoDB
To remove the MongoDB service, rst stop the service and then run the following command:
sc.exe delete MongoDB
2.1.5
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 ofcial package release. MongoDB also publishes MD5 and
SHA hashes of the ofcial packages that you can use to conrm that you have a valid package.
Considerations
MongoDB signs each release branch with a different PGP key.
The public.ascand.pubkey les 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
Replace2.2with the appropriate release number to download public key. Keys are available for all MongoDB
releases beginning with 2.2.
Procedures
Use PGP/GPG
Step 1: Download the MongoDB installation le. Download the binaries from
https://www.mongodb.org/downloads based on your environment.
For example, to download the2.6.0release for OS X through the shell, type this command:
curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz
40 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Step 2: Download the public signature le.
curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.sig
Step 3: Download then import the key le.If you have not downloaded and imported the key le, 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
gpg: Total number processed: 1
gpg: imported: 1RSA: 1)
Step 4: Verify the MongoDB installation le.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
Download and import the key le, 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: Cant check signature: public key not found
gpgwill return the following message if the package is properly signed, but you do not currently trust the signing key
in your localtrustdb.
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.
Step 1: Download the MongoDB installation le. Download the binaries from
https://www.mongodb.org/downloads based on your environment.
For example, to download the2.6.0release 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 2: Download the SHA1 and SHA256 le.
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
2.1. Installation Guides 41

MongoDB Documentation, Release 2.6.4
Step 3: Use the SHA-256 checksum to verify the MongoDB package le.Compute the checksum of the package
le:
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 theshasumandcatcommands should be identical.
Step 3: Use the SHA-1 checksum to verify the MongoDB package le.Compute the checksum of the package
le:
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 theshasumandcatcommands should be identical.
Use MD5
Step 1: Download the MongoDB installation le. Download the binaries from
https://www.mongodb.org/downloads based on your environment.
For example, to download the2.6.0release 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 2: Download the MD5 le.
curl -LO http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.6.0.tgz.md5
Step 3: Verify the checksum values for the MongoDB package le (Linux).Compute the checksum of the pack-
age le:
md5 mongodb-linux-x86_64-2.6.0.tgz
which will generate this result:
42 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
MD5mongodb-linux-x86_64-2.6.0.tgz)
Enter this command:
cat mongodb-linux-x86_64-2.6.0.tgz.md5
which will generate this result:
a937d49881f90e1a024b58d642011dc4
The output of themd5andcatcommands should be identical.
Step 4: Verify the MongoDB installation le (OS X).Compute the checksum of the package le:
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
2.2
After you have installed MongoDB, consider the following documents as you begin to learn about MongoDB:
Getting Started with MongoDB(page 43)An introduction to the basic operation and use of MongoDB.
Generate Test Data(page 47)To support initial exploration, generate test data to facilitate testing.
2.2.1
This tutorial provides an introduction to basic database operations using themongoshell.mongois 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
22
documentation and themongoshellJavaScript 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 appropriateinstallation(page 5)
document.
Connect to a Database
In this section, you connect to the database server, which runs asmongod, and begin using themongoshell to select
a logical database within the database instance and access the help text in themongoshell.
Connect to amongod
From a system prompt, startmongoby issuing themongocommand, as follows:
mongo
22
http://api.mongodb.org/js
2.2. First Steps with MongoDB 43

MongoDB Documentation, Release 2.6.4
By default,mongolooks for a database server listening on port27017on thelocalhostinterface. To connect to
a server on a different port or interface, use the--portand--hostoptions.
Select a Database
After starting themongoshell your session will use thetestdatabase by default. At any time, issue the following
operation at themongoto report the name of the current database:
db
1. mongoshell, display the list of databases, with the following operation:
show dbs
2. mydb, with the following operation:
use mydb
3. mydbdatabase as context, by checking the value of thedbobject, which
returns the name of the current database, as follows:
db
At this point, if you issue theshow dbsoperation again, it will not include themydbdatabase. MongoDB
will not permanently create a database until you insert data into that database. TheCreate a Collection and
Insert Documents(page 44) section describes the process for inserting data.
New in version 2.4:show databasesalso returns a list of databases.
DisplaymongoHelp
At any point, you can access help for themongoshell using the following operation:
help
Furthermore, you can append the.help()method to some JavaScript methods, any cursor object, as well as thedb
anddb.collectionobjects to return additional help information.
Create a Collection and Insert Documents
In this section, you insert documents into a newcollectionnamedtestDatawithin the newdatabasenamedmydb.
MongoDB will create a collection implicitly upon its rst use. You do not need to create a collection before inserting
data. Furthermore, because MongoDB usesdynamic schemas(page 688), you also need not specify the structure of
your documents before inserting them into the collection.
1. mongoshell, conrm you are in themydbdatabase by issuing the following:
db
2. mongodoes not returnmydbfor the previous operation, set the context to themydbdatabase, with the
following operation:
use mydb
3. jandkby using the following sequence of JavaScript operations:
44 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
j
k
4. jandkdocuments into thetestDatacollection with the following sequence of operations:
db.testData.insert( j )
db.testData.insert( k )
When you insert the rst document, themongodwill create both themydbdatabase and thetestData
collection.
5. testDatacollection exists. Issue the following operation:
show collections
Themongoshell will return the list of the collections in the current (i.e.mydb) database. At this point, the only
collection istestData. Allmongoddatabases also have asystem.indexes(page 271) collection.
6. testDatacollection by issuing a query on the collection using the
find()method:
db.testData.find()
This operation returns the following results. TheObjectId(page 165) values will be unique:
{"4c2209f9f3924d31102bd84a"),
{"4c2209fef3924d31102bd84b"),
All MongoDB documents must have an_ideld with a unique value. These operations do not explicitly
specify a value for the_ideld, somongocreates a uniqueObjectId(page 165) value for the eld before
inserting it into the collection.
Insert Documents using a For Loop or a JavaScript Function
To perform the remaining procedures in this tutorial, rst add more documents to your database using one or both of
the procedures described inGenerate Test Data(page 47).
Working with the Cursor
When you query acollection, MongoDB returns a cursor object that contains the results of the query. Themongo
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 rst 20 results and then waits for a request to iterate over the remaining results. In
the shell, use enteritto 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,
seecrud-read-cursor.
Iterate over the Cursor with a Loop
Before using this procedure, add documents to a collection using one of the procedures inGenerate Test Data
(page 47). You can name your database and collections anything you choose, but this procedure will assume the
database namedtestand a collection namedtestData.
1. testDatacollection and assign the resulting cursor object to the
cvariable:
2.2. First Steps with MongoDB 45

MongoDB Documentation, Release 2.6.4
varc
2. whileloop to iterate over thecvariable:
while( c.hasNext() ) printjson( c.next() )
ThehasNext()function returns true if the cursor has documents. Thenext()method returns the next
document. Theprintjson()method renders the document in a JSON-like format.
The operation displays all documents:
{"51a7dc7b2cacf40b79990be6"),
{"51a7dc7b2cacf40b79990be7"),
{"51a7dc7b2cacf40b79990be8"),
...
Use Array Operations with the Cursor
The following procedure lets you manipulate a cursor object as if it were an array:
1. mongoshell, query thetestDatacollection and assign the resulting cursor object to thecvariable:
varc
2. 4, use the following operation:
printjson( c [
MongoDB returns the following:
{"51a7dc7b2cacf40b79990bea"),
When you access documents in a cursor using the array index notation,mongorst 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,mongomay run out of available memory.
For more information on the cursor, seecrud-read-cursor.
Query for Specic Documents
MongoDB has a rich query system that allows you to select and lter the documents in a collection along specic
elds and values. SeeQuery Documents(page 87) andRead Operations(page 55) for a full account of queries in
MongoDB.
In this procedure, you query for specic documents in thetestDatacollectionby passing a query document as a
parameter to thefind()method. A query document species the criteria the query must match to return a document.
In themongoshell, query for all documents where thexeld has a value of18by passing the{ x : 18 }query
document as a parameter to thefind()method:
db.testData.find( { x
MongoDB returns one document that ts this criteria:
{"51a7dc7b2cacf40b79990bf7"),
46 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Return a Single Document from a Collection
With thefindOne()method you can return a singledocumentfrom a MongoDB collection. ThefindOne()
method takes the same parameters asfind(), but returns a document rather than a cursor.
To retrieve one document from thetestDatacollection, issue the following command:
db.testData.findOne()
For more information on querying for documents, see theQuery Documents(page 87) andRead Operations(page 55)
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 thelimit()method on a cursor, as in the
following command:
db.testData.find().limit(3)
MongoDB will return the following result, with differentObjectId(page 165) values:
{"51a7dc7b2cacf40b79990be6"),
{"51a7dc7b2cacf40b79990be7"),
{"51a7dc7b2cacf40b79990be8"),
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(page 51)
SQL to MongoDB Mapping Chart(page 120)
http://docs.mongodb.org/manualapplications/drivers
2.2.2
This tutorial describes how to quickly generate test data as you need to test basic MongoDB operations.
Insert Multiple Documents Using a For Loop
You can add documents to a new or existing collection by using a JavaScriptforloop run from themongoshell.
1. mongoshell, insert new documents into thetestDatacollection using the followingforloop. If
thetestDatacollection does not exist, MongoDB creates the collection implicitly.
for(vari; i; i++) db.testData.insert( { x
2.
db.testData.find()
2.2. First Steps with MongoDB 47

MongoDB Documentation, Release 2.6.4
Themongoshell displays the rst 20 documents in the collection. YourObjectId(page 165) values will be
different:
{"51a7dc7b2cacf40b79990be6"),
{"51a7dc7b2cacf40b79990be7"),
{"51a7dc7b2cacf40b79990be8"),
{"51a7dc7b2cacf40b79990be9"),
{"51a7dc7b2cacf40b79990bea"),
{"51a7dc7b2cacf40b79990beb"),
{"51a7dc7b2cacf40b79990bec"),
{"51a7dc7b2cacf40b79990bed"),
{"51a7dc7b2cacf40b79990bee"),
{"51a7dc7b2cacf40b79990bef"),
{"51a7dc7b2cacf40b79990bf0"),
{"51a7dc7b2cacf40b79990bf1"),
{"51a7dc7b2cacf40b79990bf2"),
{"51a7dc7b2cacf40b79990bf3"),
{"51a7dc7b2cacf40b79990bf4"),
{"51a7dc7b2cacf40b79990bf5"),
{"51a7dc7b2cacf40b79990bf6"),
{"51a7dc7b2cacf40b79990bf7"),
{"51a7dc7b2cacf40b79990bf8"),
{"51a7dc7b2cacf40b79990bf9"),
1. find()returns a cursor. To iterate the cursor and return more documents use theitoperation in the
mongoshell. Themongoshell will exhaust the cursor, and return the following documents:
{"51a7dce92cacf40b79990bfc"),
{"51a7dce92cacf40b79990bfd"),
{"51a7dce92cacf40b79990bfe"),
{"51a7dce92cacf40b79990bff"),
{"51a7dce92cacf40b79990c00"),
Insert Multiple Documents with amongoShell Function
You can create a JavaScript function in your shell session to generate the above data. TheinsertData()JavaScript
function, shown here, creates new data for use in testing or training by either creating a new collection or appending
data to an existing collection:
functioninsertData(dbName, colName, num) {
varcol
for(i; i++) {
col.insert({x:i});
}
print(col.count());
}
TheinsertData()function takes three parameters: a database, a new or existing collection, and the number of
documents to create. The function creates documents with anxeld that is set to an incremented integer, as in the
following example documents:
{"51a4da9b292904caffcff6eb"),
{"51a4da9b292904caffcff6ec"),
{"51a4da9b292904caffcff6ed"),
48 Chapter 2. Install MongoDB

MongoDB Documentation, Release 2.6.4
Store the function in your.mongorc.jsle. Themongoshell loads the function for you every time you start a session.
Example
Specify database name, collection name, and the number of documents to insert as arguments toinsertData().
insertData("test",,)
This operation inserts 400 documents into thetestDatacollection in thetestdatabase. If the collection and
database do not exist, MongoDB creates them implicitly before inserting documents.
See also:
MongoDB CRUD Concepts(page 53) andData Models(page 131).
2.2. First Steps with MongoDB 49

MongoDB Documentation, Release 2.6.4
50 Chapter 2. Install MongoDB

CHAPTER3
MongoDB CRUD Operations
MongoDB provides rich semantics for reading and manipulating data. CRUD stands forcreate,read,update, and
delete. These terms are the foundation for all interactions with the database.
MongoDB CRUD Introduction(page 51)An introduction to the MongoDB data model as well as queries and data
manipulations.
MongoDB CRUD Concepts(page 53)The core documentation of query and data manipulation.
MongoDB CRUD Tutorials(page 84)Examples of basic query and data modication operations.
MongoDB CRUD Reference(page 117)Reference material for the query and data manipulation interfaces.
3.1
MongoDB stores data in the form ofdocuments, which are JSON-like eld 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 areBSONdocuments. BSON is a binary representation ofJSONwith
additional type information. In the documents, the value of a eld can be any of the BSON data types, including other
documents, arrays, and arrays of documents. For more information, seeDocuments(page 158).
Figure 3.1: A MongoDB document.
MongoDB stores all documents incollections. 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.
51

MongoDB Documentation, Release 2.6.4
Figure 3.2: A collection of MongoDB documents.
3.1.1
Query
In MongoDB a query targets a specic collection of documents. Queries specify criteria, or conditions, that identify
the documents that MongoDB returns to the clients. A query may include aprojectionthat species the elds 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 species a query criteria and a sort modier:
SeeRead Operations Overview(page 55) for more information.
Data Modication
Data modication refers to operations that create, update, or delete data. In MongoDB, these operations modify the
data of a singlecollection. 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 theuserscollection.
SeeWrite Operations Overview(page 68) for more information.
3.1.2
Indexes
To enhance the performance of common queries and updates, MongoDB has full support for secondary indexes. These
indexes allow applications to store aviewof a portion of the collection in an efcient data structure. Most indexes store
an ordered representation of all values of a eld or a group of elds. Indexes may alsoenforce uniqueness(page 457),
store objects in ageospatial representation(page 444), and facilitatetext search(page 454).
52 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.3: The stages of a MongoDB query with a query criteria and a sort modier.
Replica Set Read Preference
For replica sets and sharded clusters with replica set components, applications specifyread preferences(page 530). A
read preference determines how the client direct read operations to the set.
Write Concern
Applications can also control the behavior of write operations usingwrite concern(page 72). 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 eld, or
process a collection of documents using a versatile stage-based data processing pipeline or map-reduce operations.
3.2
TheRead Operations(page 55) andWrite Operations(page 67) documents introduce the behavior and operations of
read and write operations for MongoDB deployments.
Read Operations(page 55)Introduces all operations that select and return documents to clients, including the query
specications.
Cursors(page 59)Queries return iterable objects, called cursors, that hold the full result set.
Query Optimization(page 60)Analyze and improve query performance.
3.2. MongoDB CRUD Concepts 53

MongoDB Documentation, Release 2.6.4
Figure 3.4: The stages of a MongoDB insert operation.
54 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Distributed Queries(page 63)Describes howsharded clustersandreplica setsaffect the performance of read
operations.
Write Operations(page 67)Introduces data create and modify operations, their behavior, and performances.
Write Concern(page 72)Describes the kind of guarantee MongoDB provides when reporting on the success
of a write operation.
Distributed Write Operations(page 76)Describes how MongoDB directs write operations onsharded clusters
andreplica setsand the performance characteristics of these operations.
Continue reading fromWrite Operations(page 67) for additional background on the behavior of data modica-
tion operations in MongoDB.
3.2.1
The following documents describe read operations:
Read Operations Overview(page 55)A high level overview of queries and projections in MongoDB, including a
discussion of syntax and behavior.
Cursors(page 59)Queries return iterable objects, called cursors, that hold the full result set.
Query Optimization(page 60)Analyze and improve query performance.
Query Plans(page 61)MongoDB executes queries using optimalplans.
Distributed Queries(page 63)Describes howsharded clustersandreplica setsaffect the performance of read opera-
tions.
Read Operations Overview
Read operations, orqueries, retrieve data stored in the database. In MongoDB, queries selectdocumentsfrom a single
collection.
Queries specify criteria, or conditions, that identify the documents that MongoDB returns to the clients. A query may
include aprojectionthat species the elds 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 adb.collection.find() method. The method accepts both the
query criteria and projections and returns acursor(page 59) 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:
Figure 3.5: The components of a MongoDB nd operation.
3.2. MongoDB CRUD Concepts 55

MongoDB Documentation, Release 2.6.4
The next diagram shows the same query in SQL:
Figure 3.6: The components of a SQL SELECT statement.
Example
db.users.find( { age:::, address:5)
This query selects the documents in theuserscollection that match the conditionageis greater than18. To specify
the greater than condition, query criteria uses the greater than (i.e.$gt)query selection operator. The query returns
at most5matching documents (or more precisely, a cursor to those documents). The matching documents will return
with only the_id,nameandaddresselds. SeeProjections(page 57) for details.
See
SQL to MongoDB Mapping Chart(page 120) for additional examples of MongoDB queries and the corresponding
SQL statements.
Query Behavior
MongoDB queries exhibit the following behavior:
singlecollection.
limits,skips, andsort orders.
sort().
modify existing documents(page 98) (i.e.updates) use the same query syntax as queries to select
documents to update.
aggregation(page 391) pipeline, the$matchpipeline stage provides access to MongoDB queries.
MongoDB provides adb.collection.findOne() method as a special case offind()that returns a single
document.
Query Statements
Consider the following diagram of the query process that species a query criteria and a sort modier:
In the diagram, the query selects documents from theuserscollection. Using aquery selection operator
to dene the conditions for matching documents, the query selects documents that haveagegreater than (i.e.$gt)
18. Then thesort()modier sorts the results byagein ascending order.
For additional examples of queries, seeQuery Documents(page 87).
56 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.7: The stages of a MongoDB query with a query criteria and a sort modier.
Projections
Queries in MongoDB return all elds in all matching documents by default. To limit the amount of data that MongoDB
sends to applications, include aprojectionin the queries. By projecting results with a subset of elds, applications
reduce their network overhead and processing requirements.
Projections, which are thesecondargument to thefind()method, may either specify a list of elds to returnorlist
elds to exclude in the result documents.
Important:Except for excluding the_ideld in inclusive projections, you cannot mix exclusive and inclusive
projections.
Consider the following diagram of the query process that species a query criteria and a projection:
In the diagram, the query selects from theuserscollection. The criteria matches the documents that haveageequal
to18. Then the projection species that only thenameeld should return in the matching documents.
Projection Examples
Exclude One Field From a Result Set
db.records.find( {:::
This query selects documents in therecordscollection that match the condition{ "user_id": { $lt: 42
} }, and uses the projection{ "history": 0 } to exclude thehistoryeld from the documents in the result
set.
Return Two eldsandthe_idField
db.records.find( {:::,:
3.2. MongoDB CRUD Concepts 57

MongoDB Documentation, Release 2.6.4
Figure 3.8: The stages of a MongoDB query with a query criteria and projection. MongoDB only transmits the
projected data to the clients.
This query selects documents in therecordscollection that match the query{ "user_id": { $lt: 42 }
}and uses the projection{ "name": 1, "email": 1 } to return just the_ideld (implicitly included),
nameeld, and theemaileld in the documents in the result set.
Return Two FieldsandExclude_id
db.records.find( {::} }, {:,::
This query selects documents in therecordscollection that match the query{ "user_id": { $lt: 42}
}, and only returns thenameandemailelds in the documents in the result set.
See
Limit Fields to Return from a Query(page 94) for more examples of queries with projection statements.
Projection BehaviorMongoDB projections have the following properties:
_ideld is included in the results. To suppress the_ideld from the result set, specify_id:
0in the projection document.
$elemMatch,$slice,
and$.
aggregation framework(page 391) pipeline, use the$project
pipeline stage.
58 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Cursors
In themongoshell, the primary method for the read operation is thedb.collection.find() method. This
method queries a collection and returns acursorto the returning documents.
To access the documents, you need to iterate the cursor. However, in themongoshell, if the returned cursor is not
assigned to a variable using thevarkeyword, then the cursor is automatically iterated up to 20 times
1
to print up to
the rst 20 documents in the results.
For example, in themongoshell, the following read operation queries theinventorycollection for documents that
havetypeequal to'food'and automatically print up to the rst 20 matching documents:
db.inventory.find( { type:
To manually iterate the cursor to access the documents, seeIterate a Cursor in the mongo Shell(page 95).
Cursor Behaviors
Closure of Inactive CursorsBy 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 thenoTimeoutwire protocol ag
2
in your query; however, you should either close the cursor manually or exhaust the cursor. In themongoshell, you
can set thenoTimeoutag:
varmyCursor
See yourdriverdocumentation for information on setting thenoTimeoutag. For themongoshell, see
cursor.addOption() for a complete list of available cursor ags.
Cursor IsolationBecause 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 onsnapshot mode(page 698).
Cursor BatchesThe MongoDB server returns the query results in batches. Batch size will not exceed themaximum
BSON document size. For most queries, therstbatch 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, seebatchSize()and
limit().
For queries that include a sort operationwithoutan index, the server must load all the documents in memory to perform
the sort and will return all documents in the rst batch.
As you iterate through the cursor and reach the end of the returned batch, if there are more results,cursor.next()
will perform agetmore operationto retrieve the next batch. To see how many documents remain in the batch
as you iterate the cursor, you can use theobjsLeftInBatch()method, as in the following example:
varmyCursor
varmyFirstDocument null;
myCursor.objsLeftInBatch();
1
You can use theDBQuery.shellBatchSize to change the number of iteration from the default value20. SeeExecuting Queries
(page 256) for more information.
2
http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol
3.2. MongoDB CRUD Concepts 59

MongoDB Documentation, Release 2.6.4
Cursor Information
Thedb.serverStatus()method returns a document that includes ametricseld. Themetricseld con-
tains acursoreld with the following information:

DBQuery.Option.noTimeout set to prevent timeout after a period
of inactivity

Consider the following example which calls thedb.serverStatus() method and accesses themetricseld
from the results and then thecursoreld from themetricseld:
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 efciency of read operations by reducing the amount of data that query operations need to process.
This simplies the work associated with fullling queries within MongoDB.
Create an Index to Support Read Operations
If your application queries a collection on a particular eld or elds, then an index on the queried eld or elds can
prevent the query from scanning the whole collection to nd and return the query results. For more information about
indexes, see thecomplete documentation of indexes in MongoDB(page 436).
Example
An application queries theinventorycollection on thetypeeld. The value of thetypeeld is user-driven.
vartypeValuesomeUserInput>;
db.inventory.find( { type:
To improve the performance of this query, add an ascending, or a descending, index to theinventorycollection
on thetypeeld.
3
In themongoshell, you can create indexes using thedb.collection.ensureIndex()
method:
3
For single-eld indexes, the selection between ascending and descending order is immaterial. For compound indexes, the selection is important.
Seeindexing order(page 441) for more details.
60 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
db.inventory.ensureIndex( { type:
This index can prevent the above query ontypefrom scanning the whole collection to return the results.
To analyze the performance of the query with an index, seeAnalyze Query Performance(page 97).
In addition to optimizing read operations, indexes can support sort operations and allow for a more efcient storage
utilization. Seedb.collection.ensureIndex() andIndexing Tutorials(page 464) for more information about
index creation.
Query Selectivity
Some query operations are not selective. These operations cannot use indexes effectively or cannot use indexes at all.
The inequality operators$ninand$neare not very selective, as they often match a large portion of the index. As a
result, in most cases, a$ninor$nequery with an index may perform no better than a$ninor$nequery that must
scan all documents in a collection.
Queries that specify regular expressions, with inline JavaScript regular expressions or$regexoperator expressions,
cannot use an index with one exception. Queries that specify regular expressionwith anchorsat the beginning of a
stringcanuse an index.
Covering a Query
An indexcovers(page 495) a query, acovered query, when:
query(page 87) are part of that index,and

For these queries, MongoDB does not need to inspect documents outside of the index. This is often more efcient
than inspecting entire documents.
Example
Given a collectioninventorywith the following index on thetypeanditemelds:
{: 1, item: 1
This index will cover the following query on thetypeanditemelds, which returns only theitemeld:
db.inventory.find( { type:, item:/^c/
{ item:, _id:
However, the index willnotcover the following query, which returns theitemeldandthe_ideld:
db.inventory.find( { type:, item:/^c/
{ item:
SeeCreate Indexes that Support Covered Queries(page 495) for more information on the behavior and use of covered
queries.
Query Plans
The MongoDB query optimizer processes queries and chooses the most efcient query plan for a query given the
available indexes. The query system then uses this query plan each time the query runs.
3.2. MongoDB CRUD Concepts 61

MongoDB Documentation, Release 2.6.4
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 withIndex Filters(page 63).
You can use theexplain()method to view statistics about the query plan for a given query. This information can
help as you developindexing strategies(page 493).
Query Optimization
To create a new query plan, the query optimizer:
1.
2.
ordered query plans, there is a single common results buffer.
unordered query plans, there is a single common results buffer.
both ordered query plansandunordered 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.
3.
unordered query planhas returned all the matching results;or
ordered query planhas returned all the matching results;or
ordered query planhas 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 specied 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:
db.inventory.find( { type:
Query Plan Revision
As collections change over time, the query optimizer deletes the query plan and re-evaluates after any of the following
events:

reIndexrebuilds the index.

mongodprocess restarts.
62 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Cached Query Plan Interface
New in version 2.6.
MongoDB provideshttp://docs.mongodb.org/manualreference/method/js-plan-cache to
view and modify the cached query plans.
Index Filters
New in version 2.6.
Index lters determine which indexes the optimizer evaluates for aquery shape. A query shape consists of a combi-
nation of query, sort, and projection specications. If an index lter exists for a given query shape, the optimizer only
considers those indexes specied in the lter.
When an index lter exists for the query shape, MongoDB ignores thehint(). To see whether MongoDB applied
an index lter for a query, check theexplain.filterSeteld of theexplain()output.
Index lters 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 lters exist for the duration of the server process and do not persist after shutdown. MongoDB also provides a
command to manually remove lters.
Because index lters overrides the expected behavior of the optimizer as well as thehint()method, use index lters
sparingly.
SeeplanCacheListFilters,planCacheClearFilters , andplanCacheSetFilter.
Distributed Queries
Read Operations to Sharded Clusters
Sharded clustersallow you to partition a data set among a cluster ofmongodinstances in a way that is nearly trans-
parent to the application. For an overview of sharded clusters, see theSharding(page 607) section of this manual.
For a sharded cluster, applications issue operations to one of themongosinstances associated with the cluster.
Read operations on sharded clusters are most efcient when directed to a specic shard. Queries to sharded collections
should include the collection'sshard key(page 620). When a query includes a shard key, themongoscan use cluster
metadata from thecong database(page 616) to route the queries to shards.
If a query does not include the shard key, themongosmust direct the query toallshards in the cluster. Thesescatter
gatherqueries can be inefcient. On larger clusters, scatter gather queries are unfeasible for routine operations.
For more information on read operations in sharded clusters, see theSharded Cluster Query Routing(page 624) and
Shard Keys(page 620) sections.
Read Operations to Replica Sets
Replica setsuseread preferencesto determine where and how to route read operations to members of the replica set.
By default, MongoDB always reads data from a replica set'sprimary. You can modify that behavior by changing the
read preference mode(page 603).
You can congure theread preference mode(page 603) on a per-connection or per-operation basis to allow reads from
secondariesto:
3.2. MongoDB CRUD Concepts 63

MongoDB Documentation, Release 2.6.4
Figure 3.9: Diagram of a sharded cluster.
64 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.10: Read operations to a sharded cluster. Query criteria includes the shard key. The query routermongos
can target the query to the appropriate shard or shards.
3.2. MongoDB CRUD Concepts 65

MongoDB Documentation, Release 2.6.4
Figure 3.11: Read operations to a sharded cluster. Query criteria does not include the shard key. The query router
mongosmust broadcast query to all shards for the collection.
66 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4

failover(page 523) situations.
Figure 3.12: Read operations to a replica set. Default read preference routes the read to the primary. Read preference
ofnearestroutes the read to the nearest member.
Read operations from secondary members of replica sets are not guaranteed to reect 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, seeRead Preference(page 530) andRead
Preference Modes(page 603).
3.2.2
The following documents describe write operations:
Write Operations Overview(page 68)Provides an overview of MongoDB's data insertion and modication opera-
tions, including aspects of the syntax, and behavior.
Write Concern(page 72)Describes the kind of guarantee MongoDB provides when reporting on the success of a
write operation.
Distributed Write Operations(page 76)Describes how MongoDB directs write operations onsharded clustersand
replica setsand the performance characteristics of these operations.
3.2. MongoDB CRUD Concepts 67

MongoDB Documentation, Release 2.6.4
Write Operation Performance(page 77)Introduces the performance constraints and factors for writing data to Mon-
goDB deployments.
Bulk Inserts in MongoDB(page 81)Describe behaviors associated with inserting an array of documents.
Storage(page 82)Introduces the storage allocation strategies available for MongoDB collections.
Write Operations Overview
A write operation is any operation that creates or modies data in the MongoDB instance. In MongoDB, write
operations target a singlecollection. All write operations in MongoDB are atomic on the level of a singledocument.
There are three classes of write operations in MongoDB:insert(page 68),update(page 69), andremove(page 70).
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 asread operations(page 55).
MongoDB allows applications to determine the acceptable level of acknowledgement required of write operations.
SeeWrite Concern(page 72) for more information.
Insert
In MongoDB, thedb.collection.insert() method adds newdocumentsto a collection.
The following diagram highlights the components of a MongoDB insert operation:
Figure 3.13: The components of a MongoDB insert operations.
The following diagram shows the same query in SQL:
Example
The following operation inserts a new documents into theuserscollection. The new document has four eldsname,
age, andstatus, and an_ideld. MongoDB always adds the_ideld to the new document if that eld does not
exist.
db.users.insert(
{
name:,
age:,
68 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.14: The components of a SQL INSERT statement.
status:
}
)
For more information and examples, seedb.collection.insert() .
Insert BehaviorIf you add a new documentwithoutthe_ideld, the client library or themongodinstance adds an
_ideld and populates the eld with a uniqueObjectId.
If you specify the_ideld, the value must be unique within the collection. For operations withwrite concern
(page 72), if you try to create a document with a duplicate_idvalue,mongodreturns a duplicate key exception.
Other Methods to Add DocumentsYou can also add new documents to a collection using methods that have an
upsert(page 70) option. If the option is set totrue, these methods will either modify existing documents or add a
new document when no matching documents exist for the query. For more information, seeUpdate Behavior with the
upsert Option(page 70).
Update
In MongoDB, thedb.collection.update() method modies existingdocumentsin acollection. 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 themultioption to update multiple documents.
The following diagram highlights the components of a MongoDB update operation:
Figure 3.15: The components of a MongoDB update operation.
The following diagram shows the same query in SQL:
Example
3.2. MongoDB CRUD Concepts 69

MongoDB Documentation, Release 2.6.4
Figure 3.16: The components of a SQL UPDATE statement.
db.users.update(
{ age::
{ $set::
{ multi: true}
)
This update operation on theuserscollection sets thestatuseld toAfor the documents that match the criteria
ofagegreater than18.
For more information, seedb.collection.update() andupdate() Examples.
Default Update BehaviorBy default, thedb.collection.update() method updates asingledocument.
However, with themultioption,update()can update all documents in a collection that match a query.
Thedb.collection.update() method either updates specic elds in the existing document or replaces the
document. Seedb.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 elds following write operationsexceptfor the following cases:
_ideld is always the rst eld in the document.
renamingof eld names may result in the reordering of elds in the document.
Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the eld order in a document.
Before version 2.6, MongoDB did not actively preserve the order of the elds in a document.
Update Behavior with theupsertOptionIf theupdate()method includesupsert: true andno 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 theupsert: truemodies the matching document or documents.
By specifyingupsert: true, applications can indicate, in asingleoperation, that if no matching documents are found
for the update, an insert should be performed. Seeupdate()for details on performing anupsert.
Changed in version 2.6: In 2.6, the newBulk()methods and the underlyingupdatecommand allow you to perform
many updates withupsert: true operations in a single call.
Remove
In MongoDB, thedb.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:
70 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.17: The components of a MongoDB remove operation.
The following diagram shows the same query in SQL:
Figure 3.18: The components of a SQL DELETE statement.
Example
db.users.remove(
{ status:
)
This delete operation on theuserscollection removes all documents that match the criteria ofstatusequal toD.
For more information, seedb.collection.remove() method andRemove Documents(page 101).
Remove BehaviorBy default,db.collection.remove() method removes all documents that match its query.
However, the method can accept a ag to limit the delete operation to a single document.
Isolation of Write Operations
The modication of a single document is always atomic, even if the write operation modies multiple sub-documents
withinthat document. For write operations that modify multiple documents, the operation as a whole is not atomic,
and other operations may interleave.
No other operations are atomic. You can, however, attempt to isolate a write operation that affects multiple documents
using theisolation operator.
To isolate a sequence of write operations from other read and write operations, seePerform Two Phase Commits
(page 102).
Additional Methods
Thedb.collection.save() method can either update an existing document or an insert a document if the
document cannot be found by the_ideld. Seedb.collection.save() for more information and examples.
MongoDB also provides methods to perform write operations in bulk. SeeBulk()for more information.
3.2. MongoDB CRUD Concepts 71

MongoDB Documentation, Release 2.6.4
Write Concern
Write concerndescribes 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 aweak
write concern, write operations return quickly. In some failure cases, write operations issued with weak write concerns
may not persist. Withstrongerwrite concerns, clients wait after sending a write operation for MongoDB to conrm
the write operations.
MongoDB provides different levels of write concern to better address the specic 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 forwrite operations(page 737) integrates write concern with the write
operations.
For details on write concern congurations, seeWrite Concern Reference(page 118).
Considerations
Default Write ConcernThemongoshell and the MongoDB drivers useAcknowledged(page 73) as the default
write concern.
SeeAcknowledged(page 73) for more information, including when this write concern became the default.
Read IsolationMongoDB allows clients to read documents inserted or modied before it commits these modica-
tions to disk, regardless of write concern level or journaling conguration. As a result, applications may observe two
classes of behaviors:

write operation before the write operation returns.
mongodterminates before the journal commits, even if a write returns successfully, queries may have
read data that will not exist after themongodrestarts.
Other database systems refer to these isolation semantics asread uncommitted. For all inserts and updates, Mon-
goDB modies 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.
Whenmongodreturns a successfuljournaled write concern, the data is fully committed to disk and will be available
aftermongodrestarts.
For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of
the members of the set. MongoDB regularly commits data to the journal regardless of journaled write concern: use
thecommitIntervalMsto control how often amongodcommits the journal.
TimeoutsClients can set awtimeout(page 119) value as part of areplica acknowledged(page 75) write concern. If
the write concern is not satised in the specied interval, the operation returns an error, even if the write concern will
eventually succeed.
MongoDB does not rollback or undo modications made before thewtimeoutinterval expired.
Write Concern Levels
MongoDB has the following levels of conceptual write concern, listed from weakest to strongest:
72 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
UnacknowledgedWith anunacknowledgedwrite concern, MongoDB does not acknowledge the receipt of write
operations.Unacknowledgedis similar toerrors 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 conguration.
Before the releases outlined inDefault Write Concern Change(page 808), this was the default write concern.
Figure 3.19: Write operation to amongodinstance with write concern ofunacknowledged. The client does not
wait for any acknowledgment.
AcknowledgedWith a receiptacknowledgedwrite concern, themongodconrms the receipt of the write operation.
Acknowledgedwrite concern allows clients to catch network, duplicate key, and other errors.
MongoDB uses theacknowledgedwrite concern by default starting in the driver releases outlined inReleases
(page 808).
Changed in version 2.6: Themongoshell write methods now incorporates thewrite concern(page 72) in the write
methods and provide the default write concern whether run interactively or in a script. SeeWrite Method Acknowl-
edgements(page 743) for details.
JournaledWith ajournaledwrite concern, the MongoDB acknowledges the write operation only after committing
the data to thejournal. 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 ajournaledwrite concern, write operations must wait for the next journal commit. To reduce latency for these op-
erations, MongoDB also increases the frequency that it commits operations to the journal. SeecommitIntervalMs
for more information.
Note:Requiringjournaledwrite concern in a replica set only requires a journal commit of the write operation to the
primaryof the set regardless of the level ofreplica acknowledgedwrite concern.
3.2. MongoDB CRUD Concepts 73

MongoDB Documentation, Release 2.6.4
Figure 3.20: Write operation to amongodinstance with write concern ofacknowledged. The client waits for
acknowledgment of success or exception.
Figure 3.21: Write operation to amongodinstance with write concern ofjournaled. Themongodsends acknowl-
edgment after it commits the write operation to the journal.
74 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Replica AcknowledgedReplica setspresent additional considerations with regards to write concern.. The default
write concern only requires acknowledgement from the primary.
Withreplica acknowledgedwrite concern, you can guarantee that the write operation propagates to additional members
of the replica set. SeeWrite Concern for Replica Sets(page 528) for more information.
Figure 3.22: Write operation to a replica set with write concern level ofw:2or write to the primary and at least one
secondary.
Note:Requiringjournaledwrite concern in a replica set only requires a journal commit of the write operation to the
primaryof the set regardless of the level ofreplica acknowledgedwrite concern.
See also:
Write Concern Reference(page 118)
3.2. MongoDB CRUD Concepts 75

MongoDB Documentation, Release 2.6.4
Distributed Write Operations
Write Operations on Sharded Clusters
For sharded collections in asharded cluster, themongosdirects write operations from applications to the shards that
are responsible for the specicportionof the data set. Themongosuses the cluster metadata from thecong database
(page 616) to route the write operation to the appropriate shards.
Figure 3.23: Diagram of a sharded cluster.
MongoDB partitions data in a sharded collection intorangesbased on the values of theshard 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 asingledocumentmustinclude theshard keyor the_ideld. Updates
that affect multiple documents are more efcient in some situations if they have theshard 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.
76 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.24: Diagram of the shard key value space segmented into smaller ranges or chunks.
For more information, seeSharded Cluster Tutorials(page 634) andBulk Inserts in MongoDB(page 81).
Write Operations on Replica Sets
Inreplica sets, all write operations go to the set'sprimary, which applies the write operation then records the oper-
ations on the primary's operation log oroplog. The oplog is a reproducible sequence of operations to the data set.
Secondarymembers 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 difculty applying the replicating operations from the primary at a sufcient rate: this can cause the secondary's
state to fall behind that of the primary. Secondaries that are signicantly behind the primary present problems for
normal operation of the replica set, particularlyfailover(page 523) in the form ofrollbacks(page 527) as well as
generalread consistency(page 528).
To help avoid this issue, you can customize thewrite concern(page 72) to return conrmation of the write operation
to another member
4
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, seeReplica Acknowledged(page 75),Oplog Size(page 535),
andChange the Size of the Oplog(page 570).
Write Operation Performance
Indexes
After every insert, update, or delete operation, MongoDB must updateeveryindex 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.
5
4
Intermittently issuing a write concern with awvalue of2ormajoritywill slow the throughput of write trafc; however, this practice will
allow the secondaries to remain current with the state of the primary.
Changed in version 2.6: InMaster/Slave(page 538) deployments, MongoDB treatsw: "majority" as equivalent tow: 1. In earlier
versions of MongoDB,w: "majority" produces an error inmaster/slave(page 538) deployments.
5
For inserts and updates to un-indexed elds, the overhead forsparse indexes(page 457) is less than for non-sparse indexes. Also for non-sparse
indexes, updates that do not change the record size have less indexing overhead.
3.2. MongoDB CRUD Concepts 77

MongoDB Documentation, Release 2.6.4
Figure 3.25: Diagram of default routing of reads and writes to the primary.
78 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Figure 3.26: Write operation to a replica set with write concern level ofw:2or write to the primary and at least one
secondary.
3.2. MongoDB CRUD Concepts 79

MongoDB Documentation, Release 2.6.4
In general, the performance gains that indexes provide forread operationsare 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, seeQuery Optimization(page 60). For more information on indexes, seeIndexes(page 431)
andIndexing Strategies(page 493).
Document Growth
If an update operation causes a document to exceed the currently allocatedrecord size, MongoDB relocates the docu-
ment 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$incoperation, 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$pushoperation, change
the size of the document.
In-place-updates are signicantly more efcient than updates that cause document growth. When possible, usedata
models(page 133) that minimize the need for document growth.
SeeStorage(page 82) for more information.
Storage Performance
HardwareThe capability of the storage system creates some important physical limits for the performance of Mon-
goDB'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 congurations.
Solid state drives (SSDs) can outperform spinning hard disks (HDDs) by 100 times or more for random workloads.
See
Production Notes(page 188) for recommendations regarding additional hardware and conguration options.
JournalingMongoDB useswrite ahead loggingto an on-diskjournalto guaranteewrite operation(page 67) dura-
bility and to provide crash resiliency. Before applying a change to the data les, 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:

for a nite number of available write operations. Moving the journal to a separate device may increase the
capacity for write operations.
write concern(page 72) that includesjournaled(page 73),mongodwill decrease the
duration between journal commits, which can increases the overall write load.
commitIntervalMsrun-time option. De-
creasing 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, seeJournaling Mechanics(page 275).
80 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Bulk Inserts in MongoDB
In some situations you may need to insert or ingest a large amount of data into a MongoDB database. Thesebulk
insertshave some special considerations that are different from other write operations.
Use theinsert()Method
Theinsert()method, when passed an array of documents, performs a bulk insert, and inserts each document
atomically. Bulk inserts can signicantly increase performance by amortizingwrite concern(page 72) costs.
New in version 2.2:insert()in themongoshell gained support for bulk inserts in version 2.2.
In thedrivers, you can congure write concern for batches rather than on a per-document level.
Drivers have aContinueOnErroroption in their insert operation, so that the bulk operation will continue to insert
remaining documents in a batch even if an insert fails.
Note:If multiple errors occur during a bulk insert, clients only receive the last error generated.
See also:
Driver documentation for details on performing bulk inserts in your application. Also seeImport and Export
MongoDB Data(page 186).
Bulk Inserts on Sharded Clusters
WhileContinueOnErroris optional on unsharded clusters, all bulk operations to asharded collectionrun with
ContinueOnError, which cannot be disabled.
Large bulk insert operations, including initial data inserts or routine data import, can affectsharded clusterperfor-
mance. For bulk inserts, consider the following strategies:
Pre-Split the CollectionIf the sharded collection is empty, then the collection has only one initialchunk, 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 inSplit Chunks
in a Sharded Cluster(page 666).
Insert to MultiplemongosTo parallelize import processes, send insert operations to more than onemongos
instance. Pre-split empty collections rst as described inSplit Chunks in a Sharded Cluster(page 666).
Avoid Monotonic ThrottlingIf 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 modications to your application:

with increasing sequence of values.

3.2. MongoDB CRUD Concepts 81

MongoDB Documentation, Release 2.6.4
Example
The following example, in C++, swaps the leading and trailing 16-bit word ofBSON ObjectIdsgenerated so that they
are no longer monotonically increasing.
using mongo;
OID() {
OID x::gen();
const *p
swap( (unsigned &) p[0], ( unsigned &) p[10] );
returnx;
}
voidfoo() {
// create an object
BSONObj o_id"<<x"<<name"<jane"
// now we may insert o into a sharded collection
}
See also:
Shard Keys(page 620) for information on choosing a sharded key. Also seeShard Key Internals(page 620) (in
particular,Choosing a Shard Key(page 639)).
Storage
Data Model
MongoDB stores data in the form ofBSONdocuments, which are rich mappings of keys, or eld names, to values.
BSON supports a rich collection of types, and elds in BSON documents may hold arrays of values or embedded
documents. All documents in MongoDB must be less than 16MB, which is theBSON document size.
Every document in MongoDB is stored in arecordwhich contains the document itself and extra space, orpadding,
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, Mon-
goDB 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 acollection, 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 elds and structure.
In MongoDB thedatabaseconstruct is a group of related collections. Each database has a distinct set of data les 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 modications to a MongoDB data set are durably written to disk, MongoDB records all
modications to a journal that it writes to disk more frequently than it writes the data les. The journal allows
MongoDB to successfully recover data from data les after amongodinstance exits without ushing all changes.
SeeJournaling Mechanics(page 275) for more information about the journal in MongoDB.
82 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Record Allocation Strategies
MongoDB supports multiple record allocation strategies that determine howmongodadds 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 efcient
than in-place updates, and can lead to storage fragmentation. As a result, all padding strategies trade additional space
for increased efciency and decreased fragmentation.
Different allocation strategies support different kinds of workloads: thepower of 2 allocations(page 83) are more
efcient for insert/update/delete workloads; whileexact t allocations(page 83) is ideal for collectionswithoutupdate
and delete workloads.
Power of 2 Sized AllocationsChanged in version 2.6: For all new collections,usePowerOf2Sizes
became the default allocation strategy. To change the default allocation strategy, use the
newCollectionsUsePowerOf2Sizes parameter.
mongoduses an allocation strategy calledusePowerOf2Sizeswhere 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:
mongodto reuse existing
allocations, which will reduce fragmentation in some cases.

ments to grow while minimizing or eliminating the chance that themongodwill need to allocate a new record
if the document grows.
TheusePowerOf2Sizesstrategy does noteliminatedocument reallocation as a result of document growth, but it
minimizes its occurrence in many common operations.
Exact Fit AllocationThe exact t allocation strategy allocates record sizes based on the size of the document and
an additionalpadding factor. Each collection has its own padding factor, which defaults to1when you insert the rst
document in a collection. MongoDB dynamically adjusts the padding factor up to2depending 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 reects the size of the padding factor at the time of allocation. See the
paddingFactoreld in the output ofdb.collection.stats() to see the current padding factor for a collec-
tion.
On average, this exact t allocation strategy uses less storage space than theusePowerOf2Sizesstrategy but will
result in higher levels of storage fragmentation if documents grow beyond the size of their initial allocation.
ThecompactandrepairDatabaseoperations remove padding by default, as do themongodumpand
mongorestore.compactdoes allow you to specify a padding for records during compaction.
Capped Collections
Capped collectionsare xed-size collections that support high-throughput operations that store records in insertion
order. Capped collections work like circular buffers: once a collection lls its allocated space, it makes room for new
documents by overwriting the oldest documents in the collection.
SeeCapped Collections(page 196) for more information.
3.2. MongoDB CRUD Concepts 83

MongoDB Documentation, Release 2.6.4
3.3
The following tutorials provide instructions for querying and modifying data. For a higher-level overview of these
operations, seeMongoDB CRUD Operations(page 51).
Insert Documents(page 84)Insert new documents into a collection.
Query Documents(page 87)Find documents in a collection using search criteria.
Limit Fields to Return from a Query(page 94)Limit which elds are returned by a query.
Iterate a Cursor in the mongo Shell(page 95)Access documents returned by afindquery by iterating the cursor,
either manually or using the iterator index.
Analyze Query Performance(page 97)Analyze the efciency of queries and determine how a query uses available
indexes.
Modify Documents(page 98)Modify documents in a collection
Remove Documents(page 101)Remove documents from a collection.
Perform Two Phase Commits(page 102)Use two-phase commits when writing data to multiple documents.
Create Tailable Cursor(page 109)Create tailable cursors for use in capped collections with high numbers of write
operations for which an index would be too expensive.
Isolate Sequence of Operations(page 111)Use the<isolation> isolated operator toisolatea single write
operation that affects multiple documents, preventing other operations from interrupting the sequence of write
operations.
Create an Auto-Incrementing Sequence Field(page 113)Describes how to create an incrementing sequence num-
ber for the_ideld using a Counters Collection or an Optimistic Loop.
Limit Number of Elements in an Array after an Update(page 116)Use$pushwith various modiers to sort and
maintain an array of xed size after update
3.3.1
In MongoDB, thedb.collection.insert() method adds new documents into a collection.
Insert a Document
Step 1: Insert a document into a collection.
Insert a document into a collection namedinventory. The operation will create the collection if the collection does
not currently exist.
db.inventory.insert(
{
item:,
details:
model:,
manufacturer:
},
stock::, qty::, qty:
category:
}
)
84 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
The operation returns aWriteResultobject with the status of the operation. A successful insert of the document
returns the following object:
WriteResult({
ThenInsertedeld species the number of documents inserted. If the operation encounters an error, the
WriteResultobject will contain the error information.
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.
{"53d98f133bb604791249ca99"),,,,,
The returned document shows that MongoDB added an_ideld to the document. If a client inserts a document that
does not contain the_ideld, MongoDB adds the eld with the value set to a generated
6
. The
7
values in your documents will differ from the ones shown.
Insert an Array of Documents
You can pass an array of documents to thedb.collection.insert() method to insert multiple documents.
Step 1: Create an array of documents.
Dene a variablemydocumentsthat holds an array of documents to insert.
varmydocuments
[
{
item:,
details::, manufacturer:
stock::, qty:
category:
},
{
item:,
details::, manufacturer:
stock::, qty::, qty::, qty:
category:
},
{
item:,
details::, manufacturer:
stock::, qty::, qty:
category:
}
];
6
http://docs.mongodb.org/manual/reference/object-id
7
http://docs.mongodb.org/manual/reference/object-id
3.3. MongoDB CRUD Tutorials 85

MongoDB Documentation, Release 2.6.4
Step 2: Insert the documents.
Pass themydocumentsarray to thedb.collection.insert() to perform a bulk insert.
db.inventory.insert( mydocuments );
The method returns aBulkWriteResultobject with the status of the operation. A successful insert of the docu-
ments returns the following object:
BulkWriteResult({
"writeErrors"
"writeConcernErrors"
"nInserted",
"nUpserted",
"nMatched",
"nModified",
"nRemoved",
"upserted"
})
ThenInsertedeld species the number of documents inserted. If the operation encounters an error, the
BulkWriteResultobject will contain information regarding the error.
The inserted documents will each have an_ideld added by MongoDB.
Insert Multiple Documents withBulk
New in version 2.6.
MongoDB provides aBulk()API that you can use to perform multiple write operations in bulk. The following
sequence of operations describes how you would use theBulk()API to insert a group of documents into a MongoDB
collection.
Step 1: Initialize aBulkoperations builder.
Initialize aBulkoperations builder for the collectioninventory.
varbulk
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; seedb.collection.initializeOrderedBulkOp()
for details.
Step 2: Add insert operations to thebulkobject.
Add two insert operations to thebulkobject using theBulk.insert()method.
bulk.insert(
{
item:,
details::, manufacturer:
stock::, qty:
86 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
category:
}
);
bulk.insert(
{
item:,
details::, manufacturer:
stock::, qty::, qty:
category:
}
);
Step 3: Execute the bulk operation.
Call theexecute()method on thebulkobject to execute the operations in its list.
bulk.execute();
The method returns aBulkWriteResultobject with the status of the operation. A successful insert of the docu-
ments returns the following object:
BulkWriteResult({
"writeErrors"
"writeConcernErrors"
"nInserted",
"nUpserted",
"nMatched",
"nModified",
"nRemoved",
"upserted"
})
ThenInsertedeld species the number of documents inserted. If the operation encounters an error, the
BulkWriteResultobject will contain information regarding the error.
Additional Examples and Methods
For more examples, seedb.collection.insert() .
Thedb.collection.update() method, thedb.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.
3.3.2
In MongoDB, thedb.collection.find() method retrieves documents from a collection.
8
The
db.collection.find() method returns acursor(page 59) to the retrieved documents.
This tutorial provides examples of read operations using thedb.collection.find() method in themongo
shell. In these examples, the retrieved documents contain all their elds. To restrict the elds to return in the retrieved
documents, seeLimit Fields to Return from a Query(page 94).
8
Thedb.collection.findOne() method also performs a read operation to return a single document. Internally, the
db.collection.findOne() method is thedb.collection.find() method with a limit of 1.
3.3. MongoDB CRUD Tutorials 87

MongoDB Documentation, Release 2.6.4
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 thefind()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 specied<value>.
The following example retrieves from theinventorycollection all documents where thetypeeld has the value
snacks:
db.inventory.find( { type:
Specify Conditions Using Query Operators
A query document can use thequery operatorsto specify conditions in a MongoDB query.
The following example selects all documents in theinventorycollection where the value of thetypeeld is either
'food'or'snacks':
db.inventory.find( { type::,
Although you can express this query using the$oroperator, use the$inoperator rather than the$oroperator when
performing equality checks on the same eld.
Refer to thehttp://docs.mongodb.org/manualreference/operator document for the complete list
of query operators.
SpecifyANDConditions
A compound query can specify conditions for more than one eld in the collection's documents. Implicitly, a logical
ANDconjunction 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 species an equality match on the eldtypeanda less than ($lt)
comparison match on the eldprice:
db.inventory.find( { type:, price::
This query selects all documents where thetypeeld has the value'food'andthe value of thepriceeld is less
than9.95. Seecomparison operatorsfor other comparison operators.
SpecifyORConditions
Using the$oroperator, you can specify a compound query that joins each clause with a logicalORconjunction so
that the query selects the documents in the collection that match at least one condition.
88 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
In the following example, the query document selects all documents in the collection where the eldqtyhas a value
greater than ($gt)100orthe value of thepriceeld is less than ($lt)9.95:
db.inventory.find(
{
$or:::::
}
)
SpecifyANDas well asORConditions
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
thetypeeld is'food'andeithertheqtyhas a value greater than ($gt)100orthe value of thepriceeld is
less than ($lt)9.95:
db.inventory.find(
{
type:,
$or:::::
}
)
Embedded Documents
When the eld holds an embedded document, a query can either specify an exact match on the embedded document
or specify a match by individual elds in the embedded document using thedot 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 anexactmatch of
the specied<value>, including the eld order.
In the following example, the query matches all documents where the value of the eldproduceris an embedded
document that containsonlythe eldcompanywith the value'ABC123'and the eldaddresswith the value
'123 Street', in the exact order:
db.inventory.find(
{
producer:
{
company:,
address:
}
}
)
Equality Match on Fields within an Embedded Document
Use thedot notationto match by specic elds in an embedded document. Equality matches for specic elds in
an embedded document will select documents in the collection where the embedded document contains the specied
elds with the specied values. The embedded document can contain additional elds.
3.3. MongoDB CRUD Tutorials 89

MongoDB Documentation, Release 2.6.4
In the following example, the query uses thedot notationto match all documents where the value of the eld
produceris an embedded document that contains a eldcompanywith the value'ABC123'and may contain
other elds:
db.inventory.find( {:
Arrays
When the eld holds an array, you can query for an exact array match or for specic values in the array. If the array
holds embedded documents, you can query for specic elds in the embedded documents usingdot notation.
If you specify multiple conditions using the$elemMatchoperator, the array must contain at least one element that
satises all the conditions. SeeSingle Element Satises the Criteria(page 91).
If you specify multiple conditions without using the$elemMatchoperator, 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. SeeCombination of Elements Satises the Criteria(page 91).
Consider aninventorycollection that contains the following documents:
{ _id:, type:, item:, ratings:,,
{ _id:, type:, item:, ratings:,
{ _id:, type:, item:, ratings:,,
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 eld matchexactlythe specied<value>,
including the element order.
The following example queries for all documents where the eldratingsis an array that holds exactly three ele-
ments,5,8, and9, in this order:
db.inventory.find( { ratings:,,
The operation returns the following document:
{,,,,,
Match an Array Element
Equality matches can specify a single element in the array to match. These specications match if the array contains
at leastoneelement with the specied value.
The following example queries for all documents whereratingsis an array that contains5as one of its elements:
db.inventory.find( { ratings:
The operation returns the following documents:
{,,,,,
{,,,,
{,,,,,
90 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Match a Specic 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 thedot notationto match all documents where theratingsarray contains
5as the rst element:
db.inventory.find( {:
The operation returns the following documents:
{,,,,,
{,,,,
Specify Multiple Criteria for Array Elements
Single Element Satises the CriteriaUse$elemMatchoperator to specify multiple criteria on the elements of
an array such that at least one array element satises all the specied criteria.
The following example queries for documents where theratingsarray contains at least one element that is greater
than ($gt)5and less than ($lt)9:
db.inventory.find( { ratings:::, $lt:
The operation returns the following documents, whoseratingsarray contains the element8which meets the crite-
ria:
{,,,,,
{,,,,,
Combination of Elements Satises the CriteriaThe following example queries for documents where the
ratingsarray contains elements that in some combination satisfy the query conditions; e.g., one element can satisfy
the greater than5condition and another element can satisfy the less than9condition, or a single element can satisfy
both:
db.inventory.find( { ratings::, $lt:
The operation returns the following documents:
{,,,,,
{,,,,
{,,,,,
The document with the"ratings" : [ 5, 9 ] matches the query since the element9is greater than5(the
rst condition) and the element5is less than9(the second condition).
Array of Embedded Documents
Consider that theinventorycollection includes the following documents:
{
_id:,
type:,
item:,
qty:,
3.3. MongoDB CRUD Tutorials 91

MongoDB Documentation, Release 2.6.4
price:,
ratings:,,
memos::, by::, by:
}
{
_id:,
type:,
item:,
qty:,
price:,
ratings:,
memos::, by::, by:
}
Match a Field in the Embedded Document Using the Array IndexIf you know the array index of the embedded
document, you can specify the document using the subdocument's position using thedot notation.
The following example selects all documents where thememoscontains an array whose rst element (i.e. index is0)
is a document that contains the eldbywhose value is'shipping':
db.inventory.find( {:
The operation returns the following document:
{
_id:,
type:,
item:,
qty:,
price:,
ratings:,,
memos::, by::, by:
}
Match a Field Without Specifying Array IndexIf you do not know the index position of the document in the array,
concatenate the name of the eld that contains the array, with a dot (.) and the name of the eld in the subdocument.
The following example selects all documents where thememoseld contains an array that contains at least one
embedded document that contains the eldbywith the value'shipping':
db.inventory.find( {:
The operation returns the following documents:
{
_id:,
type:,
item:,
qty:,
price:,
ratings:,,
memos::, by::, by:
}
{
_id:,
type:,
92 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
item:,
qty:,
price:,
ratings:,
memos::, by::, by:
}
Specify Multiple Criteria for Array of Documents
Single Element Satises the CriteriaUse$elemMatchoperator to specify multiple criteria on an array of em-
bedded documents such that at least one embedded document satises all the specied criteria.
The following example queries for documents where thememosarray has at least one embedded document that
contains both the eldmemoequal to'on time'and the eldbyequal to'shipping':
db.inventory.find(
{
memos:
{
$elemMatch:
{
memo:,
by:
}
}
}
)
The operation returns the following document:
{
_id:,
type:,
item:,
qty:,
price:,
ratings:,,
memos::, by::, by:
}
Combination of Elements Satises the CriteriaThe following example queries for documents where thememos
array contains elements that in some combination satisfy the query conditions; e.g. one element satises the eld
memoequal to'on time'condition and another element satises the eldbyequal to'shipping'condition, or
a single element can satisfy both criteria:
db.inventory.find(
{
memos.memo:,
memos.by:
}
)
The query returns the following documents:
{
_id:,
3.3. MongoDB CRUD Tutorials 93

MongoDB Documentation, Release 2.6.4
type:,
item:,
qty:,
price:,
ratings:,,
memos::, by::, by:
}
{
_id:,
type:,
item:,
qty:,
price:,
ratings:,
memos::, by::, by:
}
3.3.3
Theprojectiondocument limits the elds to return for all matching documents. The projection document can specify
the inclusion of elds or the exclusion of elds.
The specications have the following forms:
Syntax Description
<field>: <1 or true> Specify the inclusion of a eld.
<field>: <0 or false> Specify the suppression of the eld.
Important:The_ideld is, by default, included in the result set. To suppress the_ideld from the result set,
specify_id: 0in the projection document.
You cannot combine inclusion and exclusion semantics in a single projection with theexceptionof the_ideld.
This tutorial offers various query examples that limit the elds to return for all matching documents. The examples in
this tutorial use a collectioninventoryand use thedb.collection.find() method in themongoshell. The
db.collection.find() method returns acursor(page 59) to the retrieved documents. For examples on query
selection criteria, seeQuery Documents(page 87).
Return All Fields in Matching Documents
If you specify no projection, thefind()method returns all elds of all documents that match the query.
db.inventory.find( { type:
This operation will return all documents in theinventorycollection where the value of thetypeeld is'food'.
The returned documents contain all its elds.
Return the Specied Fields and the_idField Only
A projection can explicitly include several elds. In the following operation,find()method returns all documents
that match the query. In the result set, only theitemandqtyelds and, by default, the_ideld return in the
matching documents.
94 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
db.inventory.find( { type::, qty:
Return Specied Fields Only
You can remove the_ideld from the results by specifying its exclusion in the projection, as in the following
example:
db.inventory.find( { type::, qty:, _id:0
This operation returns all documents that match the query. In the result set,onlytheitemandqtyelds return in
the matching documents.
Return All But the Excluded Field
To exclude a single eld or group of elds you can use a projection in the following form:
db.inventory.find( { type::0
This operation returns all documents where the value of thetypeeld isfood. In the result set, thetypeeld does
not return in the matching documents.
With the exception of the_ideld you cannot combine inclusion and exclusion statements in projection documents.
Projection for Array Fields
For elds that contain arrays, MongoDB provides the following projection operators:$elemMatch,$slice, and
$.
For example, theinventorycollection contains the following document:
{,,,,,
Then the following operation uses the$sliceprojection operator to return just the rst two elements in theratings
array.
db.inventory.find( { _id:::
$elemMatch,$slice, and$are theonlyway to projectportionsof an array. For instance, youcannotproject a
portion of an array using the array index; e.g.{ "ratings.0": 1 } projection willnotproject the array with
the rst element.
3.3.4 mongoShell
Thedb.collection.find() method returns a cursor. To access the documents, you need to iterate the cursor.
However, in themongoshell, if the returned cursor is not assigned to a variable using thevarkeyword, then the
cursor is automatically iterated up to 20 times to print up to the rst 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 themongoshell, when you assign the cursor returned from thefind()method to a variable using thevar
keyword, the cursor does not automatically iterate.
3.3. MongoDB CRUD Tutorials 95

MongoDB Documentation, Release 2.6.4
You can call the cursor variable in the shell to iterate up to 20 times
9
and print the matching documents, as in the
following example:
varmyCursor:
myCursor
You can also use the cursor methodnext()to access the documents, as in the following example:
varmyCursor:
while(myCursor.hasNext()) {
print(tojson(myCursor.next()));
}
As an alternative print operation, consider theprintjson()helper method to replaceprint(tojson()):
varmyCursor:
while(myCursor.hasNext()) {
printjson(myCursor.next());
}
You can use the cursor methodforEach()to iterate the cursor and access the documents, as in the following
example:
varmyCursor:
myCursor.forEach(printjson);
SeeJavaScript cursor methodsand yourdriverdocumentation for more information on cursor methods.
Iterator Index
In themongoshell, you can use thetoArray()method to iterate the cursor and return the documents in an array,
as in the following:
varmyCursor:
vardocumentArray
varmyDocument3];
ThetoArray()method loads into RAM all documents returned by the cursor; thetoArray()method exhausts
the cursor.
Additionally, somedriversprovide access to the documents by using an index on the cursor (i.e.
cursor[index]). This is a shortcut for rst calling thetoArray()method and then using an index on the
resulting array.
Consider the following example:
varmyCursor:
varmyDocument3];
ThemyCursor[3]is equivalent to the following example:
myCursor.toArray() [3];
9
You can use theDBQuery.shellBatchSize to change the number of iteration from the default value20. SeeExecuting Queries
(page 256) for more information.
96 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
3.3.5
Theexplain()cursor method allows you to inspect the operation of the query system. This method is useful for
analyzing the efciency of queries, and for determining how the query uses the index. Theexplain()method tests
the query operation, andnotthe timing of query performance. Becauseexplain()attempts multiple query plans,
it does not reect an accurate timing of query performance.
Evaluate the Performance of a Query
To use theexplain()method, call the method on a cursor returned byfind().
Example
Evaluate a query on thetypeeld on the collectioninventorythat has an index on thetypeeld.
db.inventory.find( { type:
Consider the results:
{
"cursor",
"isMultiKey" false,
"n",
"nscannedObjects",
"nscanned",
"nscannedObjectsAllPlans",
"nscannedAllPlans",
"scanAndOrder" false,
"indexOnly" false,
"nYields",
"nChunkSkips",
"millis",
"indexBounds"
[,
"food"
] },
"server"
TheBtreeCursorvalue of thecursoreld indicates that the query used an index.
This query returned 5 documents, as indicated by theneld.
To return these 5 documents, the query scanned 5 documents from the index, as indicated by thenscannedeld,
and then read 5 full documents from the collection, as indicated by thenscannedObjectseld.
Without the index, the query would have scanned the whole collection to return the 5 documents.
Seeexplain-resultsmethod for full details on the output.
Compare Performance of Indexes
To manually compare the performance of a query using more than one index, you can use thehint()and
explain()methods in conjunction.
Example
Evaluate a query using different indexes:
3.3. MongoDB CRUD Tutorials 97

MongoDB Documentation, Release 2.6.4
db.inventory.find( { type::
db.inventory.find( { type::, name:
These return the statistics regarding the execution of the query using the respective index.
Note:If you runexplain()without includinghint(), the query optimizer reevaluates the query and runs against
multiple indexes before returning the query statistics.
For more detail on the explain output, seeexplain-results.
3.3.6
MongoDB provides theupdate()method to update the documents of a collection. The method accepts as its
parameters:

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 themultioption.
Update Specic Fields in a Document
To change a eld value, MongoDB provides
10
, such as$setto modify values.
Some update operators, such as$set, will create the eld if the eld does not exist. See the individual
operator
11
reference.
Step 1: Use update operators to change eld values.
For the document withitemequal to"MNO2", use the$setoperator to update thecategoryeld and the
detailseld to the specied values and the$currentDateoperator to update the eldlastModifiedwith
the current date.
db.inventory.update(
{ item:
{
$set:
category:,
details::, manufacturer:
},
$currentDate:: true}
}
)
The update operation returns aWriteResultobject which contains the status of the operation. A successful update
of the document returns the following object:
10
http://docs.mongodb.org/manual/reference/operator/update
11
http://docs.mongodb.org/manual/reference/operator/update
98 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
WriteResult({,,
ThenMatchedeld species the number of existing documents matched for the update, andnModifiedspecies
the number of existing documents modied.
Step 2: Update an embedded eld.
To update a eld within an embedded document, use thedot notation. When using the dot notation, enclose the whole
dotted eld name in quotes.
The following updates themodeleld within the embeddeddetailsdocument.
db.inventory.update(
{ item:
{ $set::
)
The update operation returns aWriteResultobject which contains the status of the operation. A successful update
of the document returns the following object:
WriteResult({,,
Step 3: Update multiple documents.
By default, theupdate()method updates a single document. To update multiple documents, use themultioption
in theupdate()method.
Update thecategoryeld to"apparel"and update thelastModifiedeld to the current date foralldocu-
ments that havecategoryeld equal to"clothing".
db.inventory.update(
{ category:
{
$set::
$currentDate:: true}
},
{ multi: true}
)
The update operation returns aWriteResultobject which contains the status of the operation. A successful update
of the document returns the following object:
WriteResult({,,
Replace the Document
To replace the entire content of a document except for the_ideld, pass an entirely new document as the second
argument toupdate().
The replacement document can have different elds from the original document. In the replacement document, you
can omit the_ideld since the_ideld is immutable. If you do include the_ideld, it must be the same value as
the existing value.
3.3. MongoDB CRUD Tutorials 99

MongoDB Documentation, Release 2.6.4
Step 1: Replace a document.
The following operation replaces the document withitemequal to"BE10". The newly replaced document will only
contain the the_ideld and the elds in the replacement document.
db.inventory.update(
{ item:
{
item:,
stock::, qty::, qty:
category:
}
)
The update operation returns aWriteResultobject which contains the status of the operation. A successful update
of the document returns the following object:
WriteResult({,,
upsertOption
By default, if no document matches the update query, theupdate()method does nothing.
However, by specifyingupsert: true, theupdate()method either updates matching document or documents, or
inserts a new document using the update specication if no matching document exists.
Step 1: Specifyupsert: true for the update replacement operation.
When you specifyupsert: 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_ideld if specied, 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:
{
item:,
details:,
stock:,
category:
},
{ upsert: true}
)
The update operation returns aWriteResultobject which contains the status of the operation, including whether
thedb.collection.update() method modied an existing document or added a new document.
WriteResult({
"nMatched",
"nUpserted",
"nModified",
"_id""53dbd684babeaec6342ed6c7")
})
100 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
ThenMatchedeld shows that the operation matched0documents.
ThenUpsertedof1shows that the update added a document.
ThenModifiedof0species that no existing documents were updated.
The_ideld shows the generated_ideld for the added document.
Step 2: Specify anupsert: true for the update specic elds operation.
When you specify anupsert: true for an update operation that modies specic elds and no matching docu-
ments are found, MongoDB creates a new document using the equality conditions in the update conditions document,
and applies the modication as specied in the update document.
The following update operation either updates specic elds of a matching document or adds a new document if no
matching document exists.
db.inventory.update(
{ item:
{
$set:
details:,
category:
}
},
{ upsert: true}
)
The update operation returns aWriteResultobject which contains the status of the operation, including whether
thedb.collection.update() method modied an existing document or added a new document.
WriteResult({
"nMatched",
"nUpserted",
"nModified",
"_id""53dbd7c8babeaec6342ed6c8")
})
ThenMatchedeld shows that the operation matched0documents.
ThenUpsertedof1shows that the update added a document.
ThenModifiedof0species that no existing documents were updated.
The_ideld shows the generated_ideld for the added document.
Additional Examples and Methods
For more examples, seeUpdate examplesin thedb.collection.update() reference page.
Thedb.collection.findAndModify() and thedb.collection.save() method can also modify exist-
ing documents or insert a new one. See the individual reference pages for the methods for more information and
examples.
3.3.7
In MongoDB, thedb.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
3.3. MongoDB CRUD Tutorials 101

MongoDB Documentation, Release 2.6.4
single document.
This tutorial provides examples of remove operations using thedb.collection.remove() method in themongo
shell.
Remove All Documents
To remove all documents from a collection, pass an empty query document{}to theremove()method. The
remove()method does not remove the indexes.
The following example removes all documents from theinventorycollection:
db.inventory.remove({})
To remove all documents from a collection, it may be more efcient to use thedrop()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 theremove()method with the<query>parameter.
The following example removes all documents from theinventorycollection where thetypeeld equalsfood:
db.inventory.remove( { type
For large deletion operations, it may be more efcient to copy the documents that you want to keep to a new collection
and then usedrop()on the original collection.
Remove a Single Document that Matches a Condition
To remove a single document, call theremove()method with thejustOneparameter set totrueor1.
The following example removes one document from theinventorycollection where thetypeeld equalsfood:
db.inventory.remove( { type
To delete a single document sorted by some specied order, use thendAndModify()method.
3.3.8
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
arollback-like(page 106) functionality.
Background
Operations on a singledocumentare always atomic with MongoDB databases; however, operations that involve multi-
ple 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 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:
102 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4

state (i.e. the nothing, in all or nothing).

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 isrecoverable(page 106). 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-likesemantics. 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 accountAto accountB. In a relational database system,
you can subtract the funds fromAand add the funds toBin 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:
1. accountsto store account information.
2. transactionsto store information on the fund transfer transactions.
Initialize Source and Destination Accounts
Insert into theaccountscollection a document for accountAand a document for accountB.
db.accounts.insert(
[
{ _id:, balance:, pendingTransactions:
{ _id:, balance:, pendingTransactions:
]
)
The operation returns aBulkWriteResult()object with the status of the operation. Upon successful insert, the
BulkWriteResult()hasnInsertedset to2.
Initialize Transfer Record
For each fund transfer to perform, insert into thetransactionscollection a document with the transfer information.
The document contains the following elds:
sourceanddestinationelds, which refer to the_idelds from theaccountscollection,
valueeld, which species the amount of transfer affecting thebalanceof thesourceand
destinationaccounts,
stateeld, which reects the current state of the transfer. Thestateeld can have the value ofinitial,
pending,applied,done,canceling, andcanceled.
3.3. MongoDB CRUD Tutorials 103

MongoDB Documentation, Release 2.6.4
lastModifiedeld, which reects last modication date.
To initialize the transfer of100from accountAto accountB, insert into thetransactionscollection a document
with the transfer information, the transactionstateof"initial", and thelastModifiedeld set to the current
date:
db.transactions.insert(
{ _id:, source:, destination:, value:, state:, lastModified: newDate() }
)
The operation returns aWriteResult()object with the status of the operation. Upon successful insert, the
WriteResult()object hasnInsertedset to1.
Transfer Funds Between Accounts Using Two-Phase Commit
Step 1: Retrieve the transaction to start.From thetransactionscollection, nd a transaction in theinitial
state. Currently thetransactionscollection has only one document, namely the one added in theInitialize
Transfer Record(page 103) step. If the collection contains additional documents, the query will return any transaction
with aninitialstate unless you specify additional query conditions.
vart:
Type the variabletin themongoshell to print the contents of the variable. The operation should print a document
similar to the following except thelastModifiedeld should reect date of your insert operation:
{,,,,,"2014-07-11T20:39:26.345Z") }
Step 2: Update transaction state to pending.Set the transactionstatefrominitialtopendingand use the
$currentDateoperator to set thelastModifiedeld to the current date.
db.transactions.update(
{ _id::
{
$set::
$currentDate:: true}
}
)
The operation returns aWriteResult()object with the status of the operation. Upon successful update, the
nMatchedandnModifieddisplays1.
In the update statement, thestate: "initial" condition ensures that no other process has already updated this
record. IfnMatchedandnModifiedis0, go back to the rst step to get a different transaction and restart the
procedure.
Step 3: Apply the transaction to both accounts.Apply the transactiontto both accounts using theupdate()
methodifthe 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 thebalanceeld and thependingTransactions eld.
Update the source account, subtracting from itsbalancethe transactionvalueand adding to its
pendingTransactions array the transaction_id.
104 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
db.accounts.update(
{ _id:::
{ $inc::t.value }, $push::
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Update the destination account, adding to itsbalancethe transactionvalueand adding to its
pendingTransactions array the transaction_id.
db.accounts.update(
{ _id:::
{ $inc::::
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Step 4: Update transaction state to applied.Use the followingupdate()operation to set the transaction's
statetoappliedand update thelastModifiedeld:
db.transactions.update(
{ _id::
{
$set::
$currentDate:: true}
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Step 5: Update both accounts' list of pending transactions.Remove the applied transaction_idfrom the
pendingTransactions array for both accounts.
Update the source account.
db.accounts.update(
{ _id::
{ $pull::
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Update the destination account.
db.accounts.update(
{ _id::
{ $pull::
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Step 6: Update transaction state to done.Complete the transaction by setting thestateof the transaction to
doneand updating thelastModifiedeld:
db.transactions.update(
{ _id::
{
$set::
3.3. MongoDB CRUD Tutorials 105

MongoDB Documentation, Release 2.6.4
$currentDate:: true}
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
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
unnished 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 thelastModifieddate as an indicator of whether the pending transaction
requires recovery; specically, 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 StateTo recover from failures that occur after step Update transaction state to pend-
ing. (page??) but before Update transaction state to applied. (page??)step, retrieve from thetransactions
collection a pending transaction for recovery:
vardateThreshold newDate();
dateThreshold.setMinutes(dateThreshold.getMinutes());
vart:, lastModified::
And resume from step Apply the transaction to both accounts. (page??)
Transactions in Applied StateTo recover from failures that occur after step Update transaction state to applied.
(page??) but before Update transaction state to done. (page??)step, retrieve from thetransactionscollection
an applied transaction for recovery:
vardateThreshold newDate();
dateThreshold.setMinutes(dateThreshold.getMinutes());
vart:, lastModified::
And resume from Update both accounts' list of pending transactions. (page??)
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.
106 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Transactions in Applied StateAfter the Update transaction state to applied. (page??) step, you shouldnotroll
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 elds.
Transactions in Pending StateAfter the Update transaction state to pending. (page??) step, but before the
Update transaction state to applied. (page??) step, you can rollback the transaction using the following procedure:
Step 1: Update transaction state to canceling.Update the transactionstatefrompendingtocanceling.
db.transactions.update(
{ _id::
{
$set::
$currentDate:: true}
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Step 2: Undo the transaction on both accounts.To undo the transaction on both accounts, reverse the transaction
tif the transaction has been applied. In the update condition, include the conditionpendingTransactions:
t._idin order to update the account only if the pending transaction has been applied.
Update the destination account, subtracting from itsbalancethe transactionvalueand removing the transaction
_idfrom thependingTransactions array.
db.accounts.update(
{ _id::
{
$inc::t.value },
$pull::
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to
1. If the pending transaction has not been previously applied to this account, no document will match the update
condition andnMatchedandnModifiedwill be0.
Update the source account, adding to itsbalancethe transactionvalueand removing the transaction_idfrom
thependingTransactions array.
db.accounts.update(
{ _id::
{
$inc::
$pull::
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to
1. If the pending transaction has not been previously applied to this account, no document will match the update
condition andnMatchedandnModifiedwill be0.
Step 3: Update transaction state to canceled.To nish the rollback, update the transactionstatefrom
cancelingtocancelled.
3.3. MongoDB CRUD Tutorials 107

MongoDB Documentation, Release 2.6.4
db.transactions.update(
{ _id::
{
$set::
$currentDate:: true}
}
)
Upon successful update, the method returns aWriteResult()object withnMatchedandnModifiedset to1.
Multiple Applications
Transactions exist, in part, so that multiple applications can create and run operations concurrently without causing
data inconsistency or conicts. In our procedure, to update or retrieve the transaction document, the update conditions
include a condition on thestateeld to prevent reapplication of the transaction by multiple applications.
For example, applicationsApp1andApp2both grab the same transaction, which is in theinitialstate.App1
applies the whole transaction beforeApp2starts. WhenApp2attempts to perform the Update transaction state to
pending. (page??) step, the update condition, which includes thestate: "initial" criterion, will not match
any document, and thenMatchedandnModifiedwill be0. This should signal toApp2to go back to the rst 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
{
query::, application:: false} },
update:
{
$set::, application:
$currentDate:: true}
},
new:true
}
)
Amend the transaction operations to ensure that only applications that match the identier in theapplicationeld
apply the transaction.
If the applicationApp1fails during transaction execution, you can use therecovery procedures(page 106), but appli-
cations should ensure that they own the transaction before applying the transaction. For example to nd and resume
the pending job, use a query that resembles the following:
vardateThreshold newDate();
dateThreshold.setMinutes(dateThreshold.getMinutes());
db.transactions.find(
{
application:,
state:,
lastModified::
}
)
108 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
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 bal-
ance, pending credits, and pending debits.
For all transactions, ensure that you use a level ofwrite concernappropriate for your deployment.
3.3.9
Overview
By default, MongoDB will automatically close a cursor when the client has exhausted all results in the cursor. How-
ever, forcapped collections(page 196) you may use aTailable Cursorthat remains open after the client exhausts
the results in the initial cursor. Tailable cursors are conceptually equivalent to thetailUnix 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,
MongoDBreplication(page 503) uses tailable cursors to tail the primary'soplog.
Note:If your query is on an indexed eld, do not use tailable cursors, but instead, use a regular cursor. Keep track of
the last value of the indexed eld returned by the query. To retrieve the newly added documents, query the collection
again using the last value of the indexed eld in the query criteria, as in the following example:
db.<collection>.find( { indexedField::lastvalue>
Consider the following behaviors related to tailable cursors:
natural order.

exhausting the cursor, subsequent retrievals of the newly added documents are inexpensive.
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 those docu-
ment.
Adeadcursor has an id of0.
See yourdriver documentation for the driver-specic method to specify the tailable cursor. For more infor-
mation on the details of specifying a tailable cursor, see
12
documentation.
C++ Example
Thetailfunction uses a tailable cursor to output the results from a query to a capped collection:

cursor->more()statement is also inside a loop.
12
http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol
3.3. MongoDB CRUD Tutorials 109

MongoDB Documentation, Release 2.6.4
#include "client/
using 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.
*/
voidtail(DBClientBase& const *ns) {
BSONElement lastValue
Query query$natural"<
while(
auto_ptr<DBClientCursor>
conn.query(ns, query,,,,
QueryOption_CursorTailable
while(
if(c->more() ) {
if( c->isDead() ) {
break;
}
continue;
}
BSONObj o->next();
lastValue"insertDate"];
cout<<
}
queryinsertDate"<<$natural"<
}
}
Thetailfunction performs the following actions:
lastValuevariable, which tracks the last accessed value. The function will use thelastValue
if the cursor becomesinvalidandtailneeds to restart the query. Usehint()to ensure that the query uses
the$naturalorder.
while(1)loop,
Query the capped collection and return a tailable cursor that blocks for several seconds waiting for new
documents
auto_ptr<DBClientCursor>
conn.query(ns, query,,,,
QueryOption_CursorTailable
*Specify the capped collection usingnsas an argument to the function.
*Set theQueryOption_CursorTailable option to create a tailable cursor.
110 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
*Set theQueryOption_AwaitData option so that the returned cursor blocks for a few seconds to
wait for data.
In an innerwhile (1)loop, read the documents from the cursor:
*If the cursor has no more documents and is not invalid, loop the innerwhileloop to recheck for
more documents.
*If the cursor has no more documents and is dead, break the innerwhileloop.
*If the cursor has documents:
·
· lastValuevalue,
· while (1)loop to recheck for more documents.
If the logic breaks out of the innerwhile (1)loop and the cursor is invalid:
*Use thelastValuevalue to create a new query condition that matches documents added after the
lastValue. Explicitly ensure$naturalorder with thehint()method:
queryinsertDate"<<$natural"<
*Loop through the outerwhile (1)loop to re-query with the new query condition and repeat.
See also:
Detailed blog post on tailable cursor
13
3.3.10
Overview
Write operations are atomic on the level of a single document: no single write operation can atomically affect more
than one document or more than one collection.
When a single write operation modies multiple documents, the operation as a whole is not atomic, and other opera-
tions may interleave. The modication of a single document, or record, is always atomic, even if the write operation
modies multiple sub-documentswithinthe single record.
No other operations are atomic; however, you canisolatea single write operation that affects multiple documents
using theisolation operator.
This document describes one method of updating documentsonlyif the local copy of the document reects the current
state of the document in the database. In addition the following methods provide a way to manage isolated sequences
of operations:
findAndModify()provides an isolated update and return operation.
Perform Two Phase Commits(page 102)
unique index(page 457), to ensure that a key doesn't exist when you insert it.
13
http://shtylman.com/post/the-tail-of-mongodb
3.3. MongoDB CRUD Tutorials 111

MongoDB Documentation, Release 2.6.4
Update if Current
In this pattern, you will:

only ifthe elds have not changed in the collection since the query.
Consider the following example in JavaScript which attempts to update theqtyeld of a document in theproducts
collection:
Changed in version 2.6: Thedb.collection.update() method now returns aWriteResult()object that
contains the status of the operation. Previous versions required an extradb.getLastErrorObj() method call.
varmyCollection
varmyDocument:
if(myDocument) {
varoldQty
if(myDocument.qty) {
myDocument.qty*=;
}else ( myDocument.qty
myDocument.qty*=;
}else{
myDocument.qty*=;
}
varresults
{
_id:
qty:
},
{
$set::
}
);
if( results.hasWriteError() ) {
print("unexpected error updating document: "
}else ( results.nMatched
print("No update: no matching document for { _id: ")
}
}
Your application may require some modications of this pattern, such as:
update()operation, to generalize the operation and guarantee
that the original document was not modied, rather than ensuring that as single eld was not changed.

Use this version variable in the query expression. You must be able to ensure thatallclients that connect to your
database obey this constraint.
$setin the update expression to modify only your elds and prevent overriding other elds.
Create an Auto-Incrementing Sequence Field(page 113).
112 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
3.3.11
Synopsis
MongoDB reserves the_ideld in the top level of all documents as a primary key._idmust be unique, and always
has an index with aunique constraint(page 457). However, except for the unique constraint you can use any value for
the_ideld in your collections. This tutorial describes two methods for creating an incrementing sequence number
for the_ideld using the following:
Use Counters Collection(page 113)
Optimistic Loop(page 115)
Considerations
Generally in MongoDB, you would not use an auto-increment pattern for the_ideld, or any eld, because it does
not scale for databases with large numbers of documents. Typically the default valueObjectIdis more ideal for the
_id.
Procedures
Use Counters Collection
Counter Collection ImplementationUse a separatecounterscollection to track thelastnumber sequence used.
The_ideld contains the sequence name and theseqeld contains the last value of the sequence.
1. counterscollection, the initial value for theuserid:
db.counters.insert(
{
_id:,
seq:
}
)
2. getNextSequence function that accepts anameof the sequence. The function uses the
findAndModify()method to atomically increment theseqvalue and return this new value:
functiongetNextSequence(name) {
varret
{
query::
update:::
new:true
}
);
returnret.seq;
}
3. getNextSequence()function duringinsert().
db.users.insert(
{
_id:"userid"),
name:
3.3. MongoDB CRUD Tutorials 113

MongoDB Documentation, Release 2.6.4
}
)
db.users.insert(
{
_id:"userid"),
name:
}
)
You can verify the results withfind():
db.users.find()
The_idelds contain incrementing sequence values:
{
_id,
name
}
{
_id,
name
}
findAndModifyBehaviorWhenfindAndModify()includes theupsert: true optionandthe query
eld(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
nd phase before any of methods perform the modify phase, these methods could insert the same document.
In thecounterscollection example, the query eld is the_ideld, which always has a unique index. Consider
that thefindAndModify()includes theupsert: true option, as in the following modied example:
functiongetNextSequence(name) {
varret
{
query::
update:::
new:true,
upsert: true
}
);
returnret.seq;
}
If multiple clients were to invoke thegetNextSequence() method with the samenameparameter, then the
methods would observe one of the following behaviors:
findAndModify()would successfully insert a new document.
findAndModify()methods would update the newly inserted document.
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.
114 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Optimistic Loop
In this pattern, anOptimistic Loopcalculates the incremented_idvalue and attempts to insert a document with the
calculated_idvalue. If the insert is successful, the loop ends. Otherwise, the loop will iterate through possible_id
values until the insert is successful.
1. insertDocumentthat performs the insert if not present loop. The function wraps
theinsert()method and takes adocand atargetCollectionarguments.
Changed in version 2.6: Thedb.collection.insert() method now returns awriteresults-insertobject
that contains the status of the operation. Previous versions required an extradb.getLastErrorObj()
method call.
functioninsertDocument(doc, targetCollection) {
while(1) {
varcursor::11);
varseq;
doc._id
varresults
if( results.hasWriteError() ) {
if( results.writeError.code /*dup key*/)
continue;
else
print(
}
break;
}
}
Thewhile (1)loop performs the following actions:
targetCollectionfor the document with the maximum_idvalue.
_idby:
adding1to the returned_idvalue if the returned cursor points to a document.
otherwise: it sets the next sequence value to1if the returned cursor points to no document.
docto insert, set its_ideld to the calculated sequence valueseq.
docinto thetargetCollection.

ters some other error or if the operation succeeds, break out of the loop.
2. insertDocument()function to perform an insert:
varmyCollection
insertDocument(
{
name:
},
myCollection
3.3. MongoDB CRUD Tutorials 115

MongoDB Documentation, Release 2.6.4
);
insertDocument(
{
name:
},
myCollection
)
You can verify the results withfind():
db.users2.find()
The_idelds contain incrementing sequence values:
{
_id:,
name:
}
{
_id,
"name"
}
Thewhileloop may iterate many times in collections with larger insert volumes.
3.3.12
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$pushoperator with the$each,$sort, and$slicemodiers to sort and maintain an array
of xed size.
Important:The array elements must be documents in order to use the$sortmodier.
Pattern
Consider the following document in the collectionstudents:
{
_id:,
scores:
{ attempt:, score:
{ attempt::8
]
}
The following update uses the$pushoperator with:
$eachmodier to append to the array 2 new elements,
116 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
$sortmodier to order the elements by ascending (1) score, and
$slicemodier to keep the last3elements of the ordered array.
db.students.update(
{ _id:
{ $push::
{ attempt:, score:
{ attempt:, score:
],
$sort::
$slice:3
}
}
}
)
Note:When using the$sortmodier on the array element, access the eld in the subdocument element directly
instead of using thedot notationon the array eld.
After the operation, the document contains only the top 3 scores in thescoresarray:
{
"_id",
"scores"
{,
{,
{,
]
}
See also:
$pushoperator,
$eachmodier,
$sortmodier, and
$slicemodier.
3.4
3.4.1
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 specic 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 specication.
cursor.toArray()Returns an array that contains all documents returned by the cursor.
3.4. MongoDB CRUD Reference 117

MongoDB Documentation, Release 2.6.4
3.4.2
Name Description
db.collection.count() Wrapscountto 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 specied eld.
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 aninsert()andupdate()to insert new
documents.
db.collection.update() Modies a document in a collection.
3.4.3
Write Concern Reference(page 118)Conguration options associated with the guarantee MongoDB provides when
reporting on the success of a write operation.
SQL to MongoDB Mapping Chart(page 120)An overview of common database operations showing both the Mon-
goDB operations and SQL statements.
The bios Example Collection(page 125)Sample data for experimenting with MongoDB.insert(),update()
andfind()pages use the data for some of their examples.
Write Concern Reference
Write concern(page 72) describes the guarantee that MongoDB provides when reporting on the success of a write
operation.
Changed in version 2.6: A new protocol forwrite operations(page 737) integrates write concerns with the write oper-
ations and eliminates the need to call thegetLastErrorcommand. Previous versions required agetLastError
command immediately after a write operation to specify the write concern.
Read Isolation Behavior
MongoDB allows clients to read documents inserted or modied before it commits these modications to disk, regard-
less of write concern level or journaling conguration. As a result, applications may observe two classes of behaviors:

write operation before the write operation returns.
mongodterminates before the journal commits, even if a write returns successfully, queries may have
read data that will not exist after themongodrestarts.
Other database systems refer to these isolation semantics asread uncommitted. For all inserts and updates, Mon-
goDB modies 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.
Whenmongodreturns a successfuljournaled write concern, the data is fully committed to disk and will be available
aftermongodrestarts.
For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of
the members of the set. MongoDB regularly commits data to the journal regardless of journaled write concern: use
thecommitIntervalMsto control how often amongodcommits the journal.
118 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
Available Write Concern
Write concern can include thew(page 119) option to specify the required number of acknowledgments before return-
ing, thej(page 119) option to require writes to the journal before returning, andwtimeout(page 119) option to specify
a time limit to prevent write operations from blocking indenitely.
In sharded clusters,mongosinstances will pass the write concern on to the shard.
wOptionThewoption provides the ability to disable write concern entirelyas well asspecify the write concern for
replica sets.
MongoDB usesw: 1as the default write concern.w: 1provides basic receipt acknowledgment.
Thewoption accepts the following values:
Value Description
1 Provides acknowledgment of write operations on a standalonemongodor theprimaryin 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 thatmongod
acknowledge the write operation.
<Number
greater than
1>
Guarantees that write operations have propagated successfully to the specied number of replica
set members including the primary.
For example,w: 2indicates acknowledgements from the primary and at least one secondary.
If you setwto 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 indenitely.
"majority" Conrms that write operations have propagated to the majority of congured replica set: a
majority of the set's congured 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: InMaster/Slave(page 538) deployments, MongoDB treatsw:
"majority"as equivalent tow: 1. In earlier versions of MongoDB,w: "majority"
produces an error inmaster/slave(page 538) deployments.
<tag set> By specifying atag set(page 576), you can have ne-grained control over which replica set
members must acknowledge a write operation to satisfy the required level of write concern.
jOptionThejoption conrms that themongodinstance has written the data to the on-disk journal. This ensures
that data is not lost if themongodinstance shuts down unexpectedly. Set totrueto enable.
Changed in version 2.6: Specifying a write concern that includesj: trueto amongodormongosrunning with
--nojournaloption now errors. Previous versions would ignore thej: true.
Note:Requiringjournaledwrite concern in a replica set only requires a journal commit of the write operation to the
primaryof the set regardless of the level ofreplica acknowledgedwrite concern.
wtimeoutThis option species a time limit, in milliseconds, for the write concern.wtimeoutis only applicable
forwvalues greater than1.
3.4. MongoDB CRUD Reference 119

MongoDB Documentation, Release 2.6.4
wtimeoutcauses write operations to return with an error after the specied limit, even if the required write concern
will eventually succeed. When these write operations return, MongoDBdoes notundo successful data modications
performed before the write concern exceeded thewtimeouttime limit.
If you do not specify thewtimeoutoption and the level of write concern is unachievable, the write operation will
block indenitely. Specifying awtimeoutvalue of0is equivalent to a write concern without thewtimeoutoption.
See also:
Write Concern Introduction(page 72) andWrite Concern for Replica Sets(page 75).
SQL to MongoDB Mapping Chart
In addition to the charts that follow, you might want to consider theFrequently Asked Questions(page 687) 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 documentorBSONdocument
column eld
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_ideld.
aggregation (e.g. group by) aggregation pipeline
See theSQL to Aggregation Mapping Chart
(page 426).
Executables
The following table presents some database executables and the corresponding MongoDB executables. This table is
notmeant to be exhaustive.
MongoDB MySQL Oracle Informix DB2
Database Servermongod mysqldoracle IDS DB2 Server
Database Clientmongo mysql sqlplusDB-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:
users.
usersthat contain documents of the following prototype:
120 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
{
_id:"509a8fb2f3f4948bd2f983a0"),
user_id:,
age:,
status:
}
Create and AlterThe following table presents the various SQL statements related to table-level actions and the
corresponding MongoDB statements.
3.4. MongoDB CRUD Reference 121

MongoDB Documentation, Release 2.6.4
SQL Schema Statements MongoDB Schema Statements
CREATE users (
id MEDIUMINTNOT
AUTO_INCREMENT,
user_id(30),
age,
status(1),
PRIMARY (id)
)
Implicitly created on rstinsert()operation. The
primary key_idis automatically added if_ideld is
not specied.
db.users.insert( {
user_id:,
age:,
status:
} )
However, you can also explicitly create a collection:
db.createCollection("users")
ALTER users
ADDjoin_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 elds to existing documents using the$setop-
erator.
db.users.update(
{ },
{ $set:: newDate() } },
{ multi: true}
)
ALTER users
DROP 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 elds from documents using the$unset
operator.
db.users.update(
{ },
{ $unset::
{ multi: true}
)
CREATE idx_user_id_asc
ONusers(user_id)
db.users.ensureIndex( { user_id:
CREATE
idx_user_id_asc_age_desc
ONusers(user_id, age DESC)
db.users.ensureIndex( { user_id:, age:1
DROP users db.users.drop()
For more information, see db.collection.insert() , db.createCollection() ,
db.collection.update() ,$set,$unset,db.collection.ensureIndex() ,indexes(page 436),
db.collection.drop() , andData Modeling Concepts(page 133).
InsertThe following table presents the various SQL statements related to inserting records into tables and the cor-
responding MongoDB statements.
122 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
SQL INSERT Statements MongoDB insert() Statements
INSERT users(user_id,
age,
status)
VALUES("bcd001",
45,
"A")
db.users.insert(
{ user_id:, age:, status:
)
For more information, seedb.collection.insert() .
SelectThe following table presents the various SQL statements related to reading records from tables and the corre-
sponding MongoDB statements.
3.4. MongoDB CRUD Reference 123

MongoDB Documentation, Release 2.6.4
SQL SELECT Statements MongoDB nd() Statements
SELECT*
FROMusers
db.users.find()
SELECTid,
user_id,
status
FROMusers
db.users.find(
{ },
{ user_id:, status:
)
SELECTuser_id, status
FROMusers
db.users.find(
{ },
{ user_id:, status:, _id:
)
SELECT*
FROMusers
WHEREstatus
db.users.find(
{ status:
)
SELECTuser_id, status
FROMusers
WHEREstatus
db.users.find(
{ status:
{ user_id:, status:, _id:
)
SELECT*
FROMusers
WHEREstatus=
db.users.find(
{ status::
)
SELECT*
FROMusers
WHEREstatus
ANDage
db.users.find(
{ status:,
age:
)
SELECT*
FROMusers
WHEREstatus
ORage
db.users.find(
{ $or::
{ age:
)
SELECT*
FROMusers
WHEREage
db.users.find(
{ age::
)
SELECT*
FROMusers
WHEREage
db.users.find(
{ age::
)
SELECT*
FROMusers
WHEREage
AND age=
db.users.find(
{ age::, $lte:
)
SELECT*
FROMusers
WHEREuser_idlike"%bc%"
db.users.find( { user_id:
SELECT*
FROMusers
WHEREuser_idlike"bc%"
db.users.find( { user_id:
SELECT*
FROMusers
WHEREstatus
ORDER user_idASC
db.users.find( { status::
SELECT*
FROMusers
WHEREstatus
ORDER user_idDESC
db.users.find( { status::1
SELECT (*)
FROMusers
db.users.count()
or
db.users.find().count()
SELECT (user_id)
FROMusers
db.users.count( { user_id:: true} } )
or
db.users.find( { user_id:: true} } ).count()
SELECT (*)
FROMusers
WHEREage
db.users.count( { age::
or
db.users.find( { age::
SELECT (status)
FROMusers
db.users.distinct(
SELECT*
FROMusers
LIMIT1
db.users.findOne()
or
db.users.find().limit(1)
SELECT*
FROMusers
LIMIT5
SKIP
db.users.find().limit(5).skip(10)
EXPLAIN *
FROMusers
WHEREstatus
db.users.find( { status:
124 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
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(), andcount().
Update RecordsThe 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
UPDATEusers
SETstatus
WHEREage
db.users.update(
{ age::
{ $set::
{ multi: true}
)
UPDATEusers
SETage
WHEREstatus
db.users.update(
{ status:
{ $inc::
{ multi: true}
)
For more information, seedb.collection.update() ,$set,$inc, and$gt.
Delete RecordsThe 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 users
WHEREstatus
db.users.remove( { status:
DELETE users db.users.remove({})
For more information, seedb.collection.remove() .
ThebiosExample Collection
Thebioscollection provides example data for experimenting with MongoDB. Many of this guide's examples on
insert,updateandreadoperations create or query data from thebioscollection.
The following documents comprise thebioscollection. In the examples, the data might be different, as the examples
themselves make changes to the data.
{
"_id",
"name"
"first",
"last"
},
"birth""1924-12-03T05:00:00Z"),
"death""2007-03-17T04:00:00Z"),
"contribs"
"Fortran",
3.4. MongoDB CRUD Reference 125

MongoDB Documentation, Release 2.6.4
"ALGOL",
"Backus-Naur Form",
"FP"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id""51df07b094c6acd67e492f41"),
"name"
"first",
"last"
},
"birth""1927-09-04T04:00:00Z"),
"death""2011-12-24T05:00:00Z"),
"contribs"
"Lisp",
"Artificial Intelligence",
"ALGOL"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
126 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
}
{
"_id",
"name"
"first",
"last"
},
"title",
"birth""1906-12-09T05:00:00Z"),
"death""1992-01-01T05:00:00Z"),
"contribs"
"UNIVAC",
"compiler",
"FLOW-MATIC",
"COBOL"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id",
"name"
"first",
"last"
},
"birth""1926-08-27T04:00:00Z"),
"death""2002-08-10T04:00:00Z"),
"contribs"
"OOP",
"Simula"
],
"awards"
{
"award",
"year",
"by"
3.4. MongoDB CRUD Reference 127

MongoDB Documentation, Release 2.6.4
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id",
"name"
"first",
"last"
},
"birth""1931-10-12T04:00:00Z"),
"death""2002-06-29T04:00:00Z"),
"contribs"
"OOP",
"Simula"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id",
"name"
"first",
"last"
},
"birth""1956-01-31T05:00:00Z"),
"contribs"
"Python"
],
"awards"
{
"award",
128 Chapter 3. MongoDB CRUD Operations

MongoDB Documentation, Release 2.6.4
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id""51e062189c6ae665454e301d"),
"name"
"first",
"last"
},
"birth""1941-09-09T04:00:00Z"),
"death""2011-10-12T04:00:00Z"),
"contribs"
"UNIX",
"C"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id",
"name"
"first",
"aka",
"last"
},
"birth""1965-04-14T04:00:00Z"),
"contribs"
"Ruby"
],
"awards"
{
"award",
"year",
"by"
3.4. MongoDB CRUD Reference 129

MongoDB Documentation, Release 2.6.4
}
]
}
{
"_id",
"name"
"first",
"last"
},
"birth""1955-05-19T04:00:00Z"),
"contribs"
"Java"
],
"awards"
{
"award",
"year",
"by"
},
{
"award",
"year",
"by"
}
]
}
{
"_id",
"name"
"first",
"last"
},
"contribs"
"Scala"
]
}
130 Chapter 3. MongoDB CRUD Operations

CHAPTER4
Data Models
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. This exibility gives you
data-modeling choices to match your application and its performance requirements.
Read theData Modeling Introduction(page 131) document for a high level introduction to data modeling, and proceed
to the documents in theData Modeling Concepts(page 133) section for additional documentation of the data model
design process. TheData Model Examples and Patterns(page 140) documents provide examples of different data
models. In addition, the
1
provide overviews of application design and include example
data models with MongoDB.
Data Modeling Introduction(page 131)An introduction to data modeling in MongoDB.
Data Modeling Concepts(page 133)The core documentation detailing the decisions you must make when determin-
ing a data model, and discussing considerations that should be taken into account.
Data Model Examples and Patterns(page 140)Examples of possible data models that you can use to structure your
MongoDB documents.
Data Model Reference(page 158)Reference material for data modeling for developers of MongoDB applications.
4.1
Data in MongoDB has aexible schema. Unlike SQL databases, where you must determine and declare a table's
schema before inserting data, MongoDB'scollectionsdo not enforcedocumentstructure. This exibility facilitates
the mapping of documents to an entity or an object. Each document can match the data elds 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.
4.1.1
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:referencesandembedded documents.
1
http://docs.mongodb.org/ecosystem/use-cases
131

MongoDB Documentation, Release 2.6.4
References
References store the relationships between data by including links orreferencesfrom one document to another. Appli-
cations can resolve thesereferences(page 161) to access the related data. Broadly, these arenormalizeddata models.
Figure 4.1: Data model using references to link documents. Both thecontactdocument and theaccessdocument
contain a reference to theuserdocument.
SeeNormalized Data Models(page 135) 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. Mon-
goDB documents make it possible to embed document structures as sub-documents in a eld or array within a docu-
ment. Thesedenormalizeddata models allow applications to retrieve and manipulate related data in a single database
operation.
SeeEmbedded Data Models(page 134) for the strengths and weaknesses of embedding sub-documents.
4.1.2
In MongoDB, write operations are atomic at thedocumentlevel, 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.
132 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Figure 4.2: Data model with embedded elds that contain all related information.
However, schemas that facilitate atomic writes may limit ways that applications can use the data or may limit ways to
modify applications. TheAtomicity Considerations(page 136) documentation describes the challenge of designing a
schema that balances exibility and atomicity.
4.1.3
Some updates, such as pushing elements to an array or adding new elds, increase adocument'ssize. If the document
size exceeds the allocated space for that document, MongoDB relocates the document on disk. The growth consider-
ation can affect the decision to normalize or denormalize data. SeeDocument Growth Considerations(page 136) for
more about planning for and managing document growth in MongoDB.
4.1.4
When designing a data model, consider how applications will use your database. For instance, if your application only
uses recently inserted documents, consider usingCapped Collections(page 196). Or if your application needs are
mainly read operations to a collection, adding indexes to support common queries can improve performance.
SeeOperational Factors and Data Models(page 136) for more information on these and other operational considera-
tions that affect data model designs.
4.2
When constructing a data model for your MongoDB collection, there are various options you can choose from, each
of which has its strengths and weaknesses. The following sections guide you through key design decisions and detail
various considerations for choosing the best data model for your application needs.
4.2. Data Modeling Concepts 133

MongoDB Documentation, Release 2.6.4
For a general introduction to data modeling in MongoDB, see theData Modeling Introduction(page 131). For example
data models, seeData Modeling Examples and Patterns(page 140).
Data Model Design(page 134)Presents the different strategies that you can choose from when determining your data
model, their strengths and their weaknesses.
Operational Factors and Data Models(page 136)Details features you should keep in mind when designing your
data model, such as lifecycle management, indexing, horizontal scalability, and document growth.
GridFS(page 138)GridFS is a specication for storing documents that exceeds theBSON-document size limit of
16MB.
4.2.1
Effective data models support your application needs. The key consideration for the structure of your documents is
the decision toembed(page 134) or touse references(page 135).
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:
Figure 4.3: Data model with embedded elds that contain all related information.
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:
Model One-to-One Relationships with Embedded Doc-
uments(page 140).
134 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4

always appear with or are viewed in the context of the one or parent documents. SeeModel One-to-Many
Relationships with Embedded Documents(page 141).
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. Doc-
ument growth can impact write performance and lead to data fragmentation. SeeDocument Growth(page 136) for
details. Furthermore, documents in MongoDB must be smaller than themaximum BSON document size . For
bulk binary data, considerGridFS(page 138).
To interact with embedded documents, usedot notationto reach into embedded documents. Seequery for data
in arrays(page 90) andquery data in sub-documents(page 89) for more examples on accessing data in arrays and
embedded documents.
Normalized Data Models
Normalized data models describe relationships usingreferences(page 161) between documents.
Figure 4.4: Data model using references to link documents. Both thecontactdocument and theaccessdocument
contain a reference to theuserdocument.
In general, use normalized data models:

tages to outweigh the implications of the duplication.

4.2. Data Modeling Concepts 135

MongoDB Documentation, Release 2.6.4

References provides more exibility 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.
SeeModel One-to-Many Relationships with Document References(page 143) for an example of referencing. For
examples of various tree models using references, seeModel Tree Structures(page 144).
4.2.2
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 efcient queries, increase the throughput
of insert and update operations, or distribute activity to a sharded cluster more effectively.
These factors areoperationalor 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'sread operations
(page 55) andwrite operations(page 67) 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 elds 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 thanin place updatesand can lead to
fragmented storage. Although MongoDB automaticallyadds padding to document allocations(page 83) 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
apre-allocationstrategy to explicitly avoid document growth. Refer to the
2
for an
example of thepre-allocationapproach to handling document growth.
SeeStorage(page 82) for more information on MongoDB's storage model and record allocation strategies.
Atomicity
In MongoDB, operations are atomic at thedocumentlevel. Nosinglewrite 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.
3
Ensure that your application stores all elds 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 mod-
els 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.
SeeModel Data for Atomic Operations(page 154) for an example data model that provides atomic updates for a single
document.
2
http://docs.mongodb.org/ecosystem/use-cases/pre-aggregated-reports
3
Document-level atomic operations include all operations within a single MongoDB document record: operations that affect multiple sub-
documents within that single record are still atomic.
136 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Sharding
MongoDB usesshardingto provide horizontal scaling. These clusters support deployments with large data sets and
high-throughput operations. Sharding allows users topartitionacollectionwithin a database to distribute the collec-
tion's documents across a number ofmongodinstances orshards.
To distribute data and application trafc in a sharded collection, MongoDB uses theshard key(page 620). Selecting
the propershard key(page 620) has signicant implications for performance, and can enable or prevent query isolation
and increased write capacity. It is important to consider carefully the eld or elds to use as the shard key.
SeeSharding Introduction(page 607) andShard Keys(page 620) for more information.
Indexes
Use indexes to improve performance for common queries. Build indexes on elds that appear often in queries and for
all operations that return sorted results. MongoDB automatically creates a unique index on the_ideld.
As you create indexes, consider the following behaviors of indexes:

to-read ratio, indexes are expensive since each insert must also update any indexes.

read operations.

for capacity planning, especially for concerns over working set size.
SeeIndexing Strategies(page 493) for more information on indexes as well asAnalyze Query Performance(page 97).
Additionally, the MongoDBdatabase proler(page 210) may help identify inefcient queries.
Large Number of Collections
In certain situations, you might choose to store related information in several collections rather than in a single collec-
tion.
Consider a sample collectionlogsthat stores log documents for various environment and applications. Thelogs
collection contains documents of the following form:
{ log:, ts::
{ log:, ts::
If the total number of documents is low, you may group documents into collection by type. For logs, consider main-
taining distinct log collections, such aslogs_devandlogs_debug. Thelogs_devcollection would contain
only the documents related to the dev environment.
Generally, having a large number of collections has no signicant 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:

_id, requires at least 8KB of data space.
database, a single namespace le (i.e.<database>.ns) stores all meta-data for that database, and
each index and collection has its own entry in the namespace le. MongoDB placeslimits on the size
of namespace files.
4.2. Data Modeling Concepts 137

MongoDB Documentation, Release 2.6.4
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 themongoshell:
db.system.namespaces.count()
The limit on the number of namespaces depend on the<database>.nssize. The namespace le defaults to
16 MB.
To change the size of thenewnamespace le, start the server with the option--nssize <new size MB> .
For existing databases, after starting up the server with--nssize, run thedb.repairDatabase() com-
mand from themongoshell. For impacts and considerations on runningdb.repairDatabase(), see
repairDatabase.
Data Lifecycle Management
Data modeling decisions should take data lifecycle management into consideration.
TheTime to Live or TTL feature(page 198) 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, considerCapped Collections(page 196).
Capped collections providerst-in-rst-out(FIFO) management of inserted documents and efciently support opera-
tions that insert and read documents based on insertion order.
4.2.3
GridFSis a specication for storing and retrieving les that exceed theBSON-documentsize limitof 16MB.
Instead of storing a le in a single document, GridFS divides a le into parts, or chunks,
4
and stores each of those
chunks as a separate document. By default GridFS limits chunk size to 255k. GridFS uses two collections to store
les. One collection stores the le chunks, and the other stores le metadata.
When you query a GridFS store for a le, the driver or client will reassemble the chunks as needed. You can perform
range queries on les stored through GridFS. You also can access information from arbitrary sections of les, which
allows you to skip into the middle of a video or audio le.
GridFS is useful not only for storing les that exceed 16MB but also for storing any les for which you want access
without having to load the entire le into memory. For more information on the indications of GridFS, seeWhen
should I use GridFS?(page 693).
Changed in version 2.4.10: The default chunk size changed from 256k to 255k.
Implement GridFS
To store and retrieve les usingGridFS, use either of the following:
driversdocumentation for information on using GridFS with your driver.
mongofiles command-line tool in the mongo shell. See
http://docs.mongodb.org/manualreference/program/mongofiles .
4
The use of the termchunksin the context of GridFS is not related to the use of the termchunksin the context of sharding.
138 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
GridFS Collections
GridFSstores les in two collections:
chunksstores the binary chunks. For details, seeThe chunks Collection(page 164).
filesstores the le's metadata. For details, seeThe les Collection(page 165).
GridFS places the collections in a common bucket by prexing each with the bucket name. By default, GridFS uses
two collections with names prexed byfsbucket:
fs.files
fs.chunks
You can choose a different bucket name thanfs, and create multiple buckets in a single database.
Each document in thechunkscollection represents a distinct chunk of a le as represented in the GridFS store. Each
chunk is identied by its uniqueObjectIdstored in its_ideld.
For descriptions of all elds in thechunksandfilescollections, seeGridFS Reference(page 164).
GridFS Index
GridFSuses aunique,compoundindex on thechunkscollection for thefiles_idandnelds. Thefiles_id
eld contains the_idof the chunk's parent document. Theneld contains the sequence number of the chunk.
GridFS numbers all chunks, starting with 0. For descriptions of the documents and elds in thechunkscollection,
seeGridFS Reference(page 164).
The GridFS index allows efcient retrieval of chunks using thefiles_idandnvalues, as shown in the following
example:
cursor::1});
See the relevantdriverdocumentation for the specic behavior of your GridFS application. If your driver does not
create this index, issue the following operation using themongoshell:
db.fs.chunks.ensureIndex( { files_id:, n:: true} );
Example Interface
The following is an example of the GridFS interface in Java. The example is for demonstration purposes only. For
API specics, see the relevantdriverdocumentation.
By default, the interface must support the default GridFS bucket, namedfs, as in the following:
// returns default GridFS bucket (i.e. "fs" collection)
GridFS myFS newGridFS(myDatabase);
// saves the file to "fs" GridFS bucket
myFS.createFile( newFile("/tmp/largething.mpg"));
Optionally, interfaces may support other additional GridFS buckets as in the following example:
// returns GridFS bucket named "contracts"
GridFS myContracts newGridFS(myDatabase,);
// retrieve GridFS object "smithco"
GridFSDBFile file.findOne("smithco");
4.2. Data Modeling Concepts 139

MongoDB Documentation, Release 2.6.4
// saves the GridFS file to the file system
file.writeTo( newFile("/tmp/smithco.pdf"));
4.3
The following documents provide overviews of various data modeling patterns and common schema design consider-
ations:
Model Relationships Between Documents(page 140)Examples for modeling relationships between documents.
Model One-to-One Relationships with Embedded Documents(page 140)Presents a data model that usesem-
bedded documents(page 134) to describe one-to-one relationships between connected data.
Model One-to-Many Relationships with Embedded Documents(page 141)Presents a data model that uses
embedded documents(page 134) to describe one-to-many relationships between connected data.
Model One-to-Many Relationships with Document References(page 143)Presents a data model that uses
references(page 135) to describe one-to-many relationships between documents.
Model Tree Structures(page 144)Examples for modeling tree structures.
Model Tree Structures with Parent References(page 146)Presents a data model that organizes documents in
a tree-like structure by storingreferences(page 135) to parent nodes in child nodes.
Model Tree Structures with Child References(page 148)Presents a data model that organizes documents in a
tree-like structure by storingreferences(page 135) to child nodes in parent nodes.
SeeModel Tree Structures(page 144) for additional examples of data models for tree structures.
Model Specic Application Contexts(page 154)Examples for models for specic application contexts.
Model Data for Atomic Operations(page 154)Illustrates how embedding elds related to an atomic update
within the same document ensures that the elds are in sync.
Model Data to Support Keyword Search(page 155)Describes one method for supporting keyword search by
storing keywords in an array in the same document as the text eld. Combined with a multi-key index, this
pattern can support application's keyword search operations.
4.3.1
Model One-to-One Relationships with Embedded Documents(page 140)Presents a data model that usesembedded
documents(page 134) to describe one-to-one relationships between connected data.
Model One-to-Many Relationships with Embedded Documents(page 141)Presents a data model that usesembed-
ded documents(page 134) to describe one-to-many relationships between connected data.
Model One-to-Many Relationships with Document References(page 143)Presents a data model that usesrefer-
ences(page 135) to describe one-to-many relationships between documents.
Model One-to-One Relationships with Embedded Documents
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
for a full high level overview of data modeling in MongoDB.
140 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
This document describes a data model that usesembedded(page 134) 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
betweenpatronandaddressdata, theaddressbelongs to thepatron.
In the normalized data model, theaddressdocument contains a reference to thepatrondocument.
{
_id:,
name:
}
{
patron_id:,
street:,
city:,
state:,
zip:
}
If theaddressdata is frequently retrieved with thenameinformation, then with referencing, your application needs
to issue multiple queries to resolve the reference. The better data model would be to embed theaddressdata in the
patrondata, as in the following document:
{
_id:,
name:,
address:
street:,
city:,
state:,
zip:
}
}
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 aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
for a full high level overview of data modeling in MongoDB.
This document describes a data model that usesembedded(page 134) documents to describe relationships between
connected data.
4.3. Data Model Examples and Patterns 141

MongoDB Documentation, Release 2.6.4
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 betweenpatronandaddressdata, thepatronhas multipleaddressentities.
In the normalized data model, theaddressdocuments contain a reference to thepatrondocument.
{
_id:,
name:
}
{
patron_id:,
street:,
city:,
state:,
zip:
}
{
patron_id:,
street:,
city:,
state:,
zip:
}
If your application frequently retrieves theaddressdata with thenameinformation, then your application needs
to issue multiple queries to resolve the references. A more optimal schema would be to embed theaddressdata
entities in thepatrondata, as in the following document:
{
_id:,
name:,
addresses:
{
street:,
city:,
state:,
zip:
},
{
street:,
city:,
state:,
zip:
}
]
}
With the embedded data model, your application can retrieve the complete patron information with one query.
142 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Model One-to-Many Relationships with Document References
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
for a full high level overview of data modeling in MongoDB.
This document describes a data model that usesreferences(page 135) 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 torepetitionof the publisher data, as the
following documents show:
{
title:,
author:,
published_date:"2010-09-24"),
pages:,
language:,
publisher:
name:,
founded:,
location:
}
}
{
title:,
author:,
published_date:"2011-05-06"),
pages:,
language:,
publisher:
name:,
founded:,
location:
}
}
To avoid repetition of the publisher data, usereferencesand 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:,
founded:,
location:,
4.3. Data Model Examples and Patterns 143

MongoDB Documentation, Release 2.6.4
books:12346789,, ...]
}
{
_id:,
title:,
author:,
published_date:"2010-09-24"),
pages:,
language:
}
{
_id:,
title:,
author:,
published_date:"2011-05-06"),
pages:,
language:
}
To avoid mutable, growing arrays, store the publisher reference inside the book document:
{
_id:,
name:,
founded:,
location:
}
{
_id:,
title:,
author:,
published_date:"2010-09-24"),
pages:,
language:,
publisher_id:
}
{
_id:,
title:,
author:,
published_date:"2011-05-06"),
pages:,
language:,
publisher_id:
}
4.3.2
MongoDB allows various ways to use tree data structures to model large hierarchical or nested data relationships.
Model Tree Structures with Parent References(page 146)Presents a data model that organizes documents in a tree-
like structure by storingreferences(page 135) to parent nodes in child nodes.
144 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Figure 4.5: Tree data model for a sample hierarchy of categories.
4.3. Data Model Examples and Patterns 145

MongoDB Documentation, Release 2.6.4
Model Tree Structures with Child References(page 148)Presents a data model that organizes documents in a tree-
like structure by storingreferences(page 135) to child nodes in parent nodes.
Model Tree Structures with an Array of Ancestors(page 149)Presents a data model that organizes documents in a
tree-like structure by storingreferences(page 135) to parent nodes and an array that stores all ancestors.
Model Tree Structures with Materialized Paths(page 151)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_idof the nodes ancestors or path as a string.
Model Tree Structures with Nested Sets(page 153)Presents a data model that organizes documents in a tree-like
structure using theNested Setspattern. This optimizes discovering subtrees at the expense of tree mutability.
Model Tree Structures with Parent References
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
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 storingreferences
(page 135) to parent nodes in children nodes.
Pattern
TheParent Referencespattern 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 usingParent References, storing the reference to the parent category in the
eldparent:
db.categories.insert( { _id:, parent:
db.categories.insert( { _id:, parent:
db.categories.insert( { _id:, parent:
db.categories.insert( { _id:, parent:
db.categories.insert( { _id:, parent:
db.categories.insert( { _id:, parent: null} )

db.categories.findOne( { _id:
parentto enable fast search by the parent node:
db.categories.ensureIndex( { parent:
parenteld to nd its immediate children nodes:
db.categories.find( { parent:
TheParent Linkspattern provides a simple solution to tree storage but requires multiple queries to retrieve subtrees.
146 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Figure 4.6: Tree data model for a sample hierarchy of categories.
4.3. Data Model Examples and Patterns 147

MongoDB Documentation, Release 2.6.4
Model Tree Structures with Child References
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
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 storingreferences
(page 135) in the parent-nodes to children nodes.
Pattern
TheChild Referencespattern 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:
Figure 4.7: Tree data model for a sample hierarchy of categories.
The following example models the tree usingChild References, storing the reference to the node's children in the eld
children:
db.categories.insert( { _id:, children:
db.categories.insert( { _id:, children:
db.categories.insert( { _id:, children:,
148 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
db.categories.insert( { _id:, children:
db.categories.insert( { _id:, children:,
db.categories.insert( { _id:, children:

db.categories.findOne( { _id:
childrento enable fast search by the child nodes:
db.categories.ensureIndex( { children:
childreneld to nd its parent node as well as its siblings:
db.categories.find( { children:
TheChild Referencespattern 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 aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
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 usingreferences
(page 135) to parent nodes and an array that stores all ancestors.
Pattern
TheArray of Ancestorspattern 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 usingArray of Ancestors. In addition to theancestorseld, these docu-
ments also store the reference to the immediate parent category in theparenteld:
db.categories.insert( { _id:, ancestors:,,:
db.categories.insert( { _id:, ancestors:,,:
db.categories.insert( { _id:, ancestors:,:
db.categories.insert( { _id:, ancestors:,:
db.categories.insert( { _id:, ancestors::
db.categories.insert( { _id:, ancestors:: null} )

db.categories.findOne( { _id:
ancestorsto enable fast search by the ancestors nodes:
db.categories.ensureIndex( { ancestors:
ancestorsto nd all its descendants:
4.3. Data Model Examples and Patterns 149

MongoDB Documentation, Release 2.6.4
Figure 4.8: Tree data model for a sample hierarchy of categories.
150 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
db.categories.find( { ancestors:
TheArray of Ancestorspattern provides a fast and efcient solution to nd the descendants and the ancestors of a node
by creating an index on the elements of the ancestors eld. This makesArray of Ancestorsa good choice for working
with subtrees.
TheArray of Ancestorspattern is slightly slower than theMaterialized Paths(page 151) pattern but is more straight-
forward to use.
Model Tree Structures with Materialized Paths
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
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
TheMaterialized Pathspattern 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 theMaterialized Pathspattern requires additional steps of
working with strings and regular expressions, the pattern also provides more exibility in working with the path, such
as nding nodes by partial paths.
Consider the following hierarchy of categories:
The following example models the tree usingMaterialized Paths, storing the path in the eldpath; the path string
uses the comma,as a delimiter:
db.categories.insert( { _id:, path: null} )
db.categories.insert( { _id:, path:
db.categories.insert( { _id:, path:
db.categories.insert( { _id:, path:
db.categories.insert( { _id:, path:
db.categories.insert( { _id:, path:
path:
db.categories.find().sort( { path:
patheld to nd the descendants ofProgramming:
db.categories.find( { path:
Bookswhere theBooksis also at the topmost level of the hierarchy:
db.categories.find( { path:
pathuse the following invocation:
db.categories.ensureIndex( { path:
This index may improve performance depending on the query:
4.3. Data Model Examples and Patterns 151

MongoDB Documentation, Release 2.6.4
Figure 4.9: Tree data model for a sample hierarchy of categories.
152 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
For queries of theBookssub-tree (e.g.http://docs.mongodb.org/manual^,Books,/ ) an
index on thepatheld improves the query performance signicantly.
For queries of theProgrammingsub-tree (e.g.http://docs.mongodb.org/manual,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 indexmayprovide some performance improvementifthe index is signicantly smaller
than the entire collection.
Model Tree Structures with Nested Sets
Overview
Data in MongoDB has aexible schema.Collectionsdo not enforcedocumentstructure. Decisions that affect how
you model data can affect application performance and database capacity. SeeData Modeling Concepts(page 133)
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
TheNested Setspattern identies each node in the tree as stops in a round-trip traversal of the tree. The application
visits each node in the tree twice; rst during the initial trip, and second during the return trip. TheNested Setspattern
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 thelefteld, and its return stop in therighteld.
Consider the following hierarchy of categories:
Figure 4.10: Example of a hierarchical data. The numbers identify the stops at nodes during a roundtrip traversal of a
tree.
4.3. Data Model Examples and Patterns 153

MongoDB Documentation, Release 2.6.4
The following example models the tree usingNested Sets:
db.categories.insert( { _id:, parent:, left:, right:
db.categories.insert( { _id:, parent:, left:, right:
db.categories.insert( { _id:, parent:, left:, right:
db.categories.insert( { _id:, parent:, left:, right:
db.categories.insert( { _id:, parent:, left:, right:
db.categories.insert( { _id:, parent:, left:, right:
You can query to retrieve the descendants of a node:
vardatabaseCategory:
db.categories.find( { left::::
TheNested Setspattern provides a fast and efcient solution for nding subtrees but is inefcient for modifying the
tree structure. As such, this pattern is best for static trees that do not change.
4.3.3
Model Data for Atomic Operations(page 154)Illustrates how embedding elds related to an atomic update within
the same document ensures that the elds are in sync.
Model Data to Support Keyword Search(page 155)Describes one method for supporting keyword search by storing
keywords in an array in the same document as the text eld. Combined with a multi-key index, this pattern can
support application's keyword search operations.
Model Monetary Data(page 156)Describes two methods to model monetary data in MongoDB.
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 elds that must be updated to-
gether, embedding the elds within the same document ensures that the elds 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
availableeld and thecheckouteld within the same document ensures that you can update the two elds
atomically.
{
_id:,
title:,
author:,
published_date:"2010-09-24"),
pages:,
language:,
publisher_id:,
available:,
checkout::, date:"2012-10-15") } ]
}
Then to update with new checkout information, you can use thedb.collection.update() method to atomically
update both theavailableeld and thecheckouteld:
154 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
db.books.update (
{ _id:, available::
{
$inc::1
$push:::, date: newDate() } }
}
)
The operation returns aWriteResult()object that contains information on the status of the operation:
WriteResult({,,
ThenMatchedeld shows that1document matched the update condition, andnModifiedshows that the operation
updated1document.
If no document matched the update condition, thennMatchedandnModifiedwould be0and would indicate that
you could not check out the book.
Model Data to Support Keyword Search
Note:Keyword search isnotthe same as text search or full text search, and does not provide stemming or other
text-processing features. See theLimitations of Keyword Indexes(page 156) section for more information.
In 2.4, MongoDB provides a text search feature. SeeText Indexes(page 454) for more information.
If your application needs to perform queries on the content of a eld that holds text you can perform exact matches
on the text or use$regexto 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 eld. Combined with amulti-key
index(page 442), this pattern can support application's keyword search operations.
Pattern
To add structures to your document to support keyword-based queries, create an array eld in your documents and add
the keywords as strings in the array. You can then create amulti-key index(page 442) 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 theMoby-Dickvolume you might have the following document:
{ title
author
published
ISBN
topics
"novel"
}
You then create a multi-key index on thetopicsarray:
4.3. Data Model Examples and Patterns 155

MongoDB Documentation, Release 2.6.4
db.volumes.ensureIndex( { topics:
The multi-key index creates separate index entries for each keyword in thetopicsarray. For example the index
contains one entry forwhalingand another forallegory.
You then query based on the keywords. For example:
db.volumes.findOne( { topics:
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 specic data models andmulti-key indexes(page 442); however, these
keyword indexes are not sufcient 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 applica-
tion 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 key-
word indexes are always current and can operate in real-time. However, asynchronous bulk indexes may be
more efcient for some kinds of content and workloads.
Model Monetary Data
Overview
MongoDB stores numeric data as either IEEE 754 standard 64-bit oating point numbers or as 32-bit or 64-bit signed
integers. Applications that handle monetary data often require capturing fractional units of currency. However, arith-
metic on oating 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 oating point numbers.
Note:Arithmetic mentioned on this page refers to server-side arithmetic performed bymongodormongos, and not
to client-side arithmetic.
This document describes two ways to model monetary data in MongoDB:
Exact Precision(page 157) which multiplies the monetary value by a power of 10.
Arbitrary Precision(page 157) which uses two elds for the value: one eld to store the exact monetary value
as a non-numeric and another eld to store a oating 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:
156 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Exact Precision(page 157).
$inc,$mul, andaggregation framework
arithmetic, useExact Precision(page 157).
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:
Arbitrary Precision(page 157).
Arbitrary Precision
(page 157).
Exact Precision
To model monetary data using the exact precision model:
1.
precision down to the tenth of one cent for monetary values inUSDcurrency.
2.
precision needed becomes the least signicant digit of the integer. For example, if the required maximum
precision is the tenth of one cent, multiply the monetary value by 1000.
3.
For example, the following scales9.99 USDby 1000 to preserve precision up to one tenth of a cent.
{
The model assumes that for a given currency value:

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, seeUse Cases for Exact Precision Model(page 156).
Arbitrary Precision
To model monetary data using the arbitrary precision model, store the value in two elds:
1. BinDataor astring.
2.
The following example uses the arbitrary precision model to store9.99 USDfor the price and0.25 USDfor the
fee:
{
price:, approx: 9.9900000000000002, currency:,
fee:, approx: 0.2499999999999999, currency:
}
4.3. Data Model Examples and Patterns 157

MongoDB Documentation, Release 2.6.4
With some care, applications can perform range and sort queries on the eld with the numeric approximation. How-
ever, the use of the approximation eld 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 lter out the returned documents
based on the exact monetary value.
For use cases of this model, seeUse Cases for Arbitrary Precision Model(page 157).
4.4
Documents(page 158)MongoDB stores all data in documents, which are JSON-style data structures composed of
eld-and-value pairs.
Database References(page 161)Discusses manual references and DBRefs, which MongoDB can use to represent
relationships between documents.
GridFS Reference(page 164)Convention for storing large les in a MongoDB Database.
ObjectId(page 165)A 12-byte BSON type that MongoDB uses as the default value for its documents'_ideld if
the_ideld is not specied.
BSON Types(page 167)Outlines the uniqueBSONtypes used by MongoDB. See
5
for the complete
BSON specication.
4.4.1
MongoDB stores all data in documents, which are JSON-style data structures composed of eld-and-value pairs:
{:,:,:
Most user-accessible data structures in MongoDB are documents, including:

Query selectors(page 55), which dene what records to select for read, update, and delete operations.
Update denitions(page 67), which dene what elds to modify during an update.
Index specications(page 436), which dene what elds to index.
serverStatusand the
replica set conguration document(page 594).
Document Format
MongoDB stores documents on disk in theBSONserialization format. BSON is a binary representation ofJSON
documents, though it contains more data types than JSON. For the BSON spec, see
6
. See alsoBSON
Types(page 167).
ThemongoJavaScript shell and theMongoDB language drivers translate between BSON and the language-
specic document representation.
5
http://bsonspec.org/
6
http://bsonspec.org/
158 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
Document Structure
MongoDB documents are composed of eld-and-value pairs and have the following structure:
{
field1:
field2:
field3:
...
fieldN:
}
The value of a eld can be any of the BSONdata types(page 167), including other documents, arrays, and arrays of
documents. The following document contains values of varying types:
varmydoc
_id:"5099803df3f4948bd2f98391"),
name::, last:
birth: newDate(Jun 23, 1912),
death: newDate(Jun 07, 1954),
contribs:,,
views1250000)
}
The above elds have the following data types:
_idholds anObjectId.
nameholds asubdocumentthat contains the eldsfirstandlast.
birthanddeathhold values of theDatetype.
contribsholds anarray of strings.
viewsholds a value of theNumberLongtype.
Field Names
Field names are strings.
Documents(page 158) have the following restrictions on eld names:
_idis 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.
cannotstart with the dollar sign ($) character.
cannotcontain the dot (.) character.
cannotcontain thenullcharacter.
BSON documents may have more than one eld with the same name. MostMongoDB interfaces, however,
represent MongoDB with a structure (e.g. a hash table) that does not support duplicate eld names. If you need to
manipulate documents that have more than one eld with the same name, see thedriver documentation for
your driver.
Some documents created by internal MongoDB processes may have duplicate elds, butnoMongoDB process will
everadd duplicate elds to an existing user document.
4.4. Data Model Reference 159

MongoDB Documentation, Release 2.6.4
Field Value Limit
Forindexed collections(page 431), the values for the indexed elds have aMaximum Index Key Length limit.
SeeMaximum 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. Seemongofilesand the documentation for yourdriverfor more information about GridFS.
Document Field Order
MongoDB preserves the order of the document elds following write operationsexceptfor the following cases:
_ideld is always the rst eld in the document.
renamingof eld names may result in the reordering of elds in the document.
Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the eld order in a document.
Before version 2.6, MongoDB did not actively preserve the order of the elds in a document.
The_idField
The_ideld has the following behavior and constraints:
_ideld during the creation of a collection.
_ideld is always the rst eld in the documents. If the server receives a document that does not have the
_ideld rst, then the server will move the eld to the beginning.
_ideld may contain values of anyBSON data type(page 167), other than an array.
Warning:To ensure functioning replication, do not store values that are of the BSON regular expression
type in the_ideld.
The following are common options for storing values for_id:
ObjectId(page 165).

Create an Auto-Incrementing Sequence Field(page 113).

and in the_idindex, store the UUID as a value of the BSONBinDatatype.
Index keys that are of theBinDatatype are more efciently stored in the index if:
the binary subtype value is in the range of 0-7 or 128-135, and
160 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
the length of the byte array is: 0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, or 32.

ment UUID serialization and deserialization logic differently, which may not be fully compatible with other
drivers. See your
7
for information concerning UUID interoperability.
Note:Most MongoDB driver clients will include the_ideld and generate anObjectIdbefore sending the insert
operation to MongoDB; however, if the client sends a document without an_ideld, themongodwill add the_id
eld and generate theObjectId.
Dot Notation
MongoDB uses thedot notationto access the elements of an array and to access the elds of a subdocument.
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>
To access a eld of a subdocument withdot-notation, concatenate the subdocument name with the dot (.) and the
eld name, and enclose in quotes:
<subdocument>.<field>
See also:
Embedded Documents(page 89) for dot notation examples with subdocuments.
Arrays(page 90) for dot notation examples with arrays.
4.4.2
MongoDB does not support joins. In MongoDB some data isdenormalized, or stored with related data indocumentsto
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:
1.Manual references(page 162) where you save the_ideld 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
sufcient for most use cases.
2.DBRefs(page 162) are references from one document to another using the value of the rst document's_id
eld, 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
drivershave helper methods that form the query for the DBRef automatically. The drivers
8
do notautomat-
icallyresolve 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.
7
http://api.mongodb.org/
8
Some community supported drivers may have alternate behavior and may resolve a DBRef into a document automatically.
4.4. Data Model Reference 161

MongoDB Documentation, Release 2.6.4
Manual References
Background
Using manual references is the practice of including onedocument's_ideld in another document. The application
can then issue a second query to resolve the referenced elds as needed.
Process
Consider the following operation to insert two documents, using the_ideld of the rst document as a reference in
the second document:
original_id
db.places.insert({
"_id":
"name":,
"url":
})
db.people.insert({
"name":,
"places_id":
"url":
})
Then, when a query returns the document from thepeoplecollection you can, if needed, make a second query for
the document referenced by theplaces_ideld in theplacescollection.
Use
For nearly every case where you want to store a relationship between two documents, usemanual references
(page 162). 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
usingDBRefs(page 162).
DBRefs
Background
DBRefs are a convention for representing adocument, rather than a specic reference type. They include the name of
the collection, and in some cases the database name, in addition to the value from the_ideld.
Format
DBRefs have the following elds:
$ref
The$refeld holds the name of the collection where the referenced document resides.
162 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
$id
The$ideld contains the value of the_ideld in the referenced document.
$db
Optional.
Contains the name of the database where the referenced document resides.
Only some drivers support$dbreferences.
Example
DBRef documents resemble the following document:
{value>,value>,value>
Consider a document from a collection that stored a DBRef in acreatoreld:
{
"_id""5126bbf64aed4daf9e2ab771"),
// .. application fields
"creator"
"$ref",
"$id""5126bc054aed4daf9e2ab772"),
"$db"
}
}
The DBRef in this example points to a document in thecreatorscollection of theusersdatabase that has
ObjectId("5126bc054aed4daf9e2ab772") in its_ideld.
Note:The order of elds in the DBRef matters, and you must use the above sequence when using a DBRef.
Support
C++The C++ driver contains no support for DBRefs. You can transverse references manually.
C#The C# driver provides access to DBRef objects with the
9
and supplies the
Method
10
for accessing these objects.
JavaThe
11
class provides supports for DBRefs from Java.
JavaScriptThemongoshell'sJavaScriptinterface provides a DBRef.
PerlThe Perl driver contains no support for DBRefs. You can transverse references manually or use the
goDBx::AutoDeref
12
CPAN module.
PHPThe PHP driver supports DBRefs, including the optional$dbreference, through
13
.
PythonThe Python driver provides the
14
, and the
15
for interacting with DBRefs.
9
http://api.mongodb.org/csharp/current/html/46c356d3-ed06-a6f8-42fa-e0909ab64ce2.htm
10
http://api.mongodb.org/csharp/current/html/1b0b8f48-ba98-1367-0a7d-6e01c8df436f.htm
11
http://api.mongodb.org/java/current/com/mongodb/DBRef.html
12
http://search.cpan.org/dist/MongoDBx-AutoDeref/
13
http://www.php.net/manual/en/class.mongodbref.php/
14
http://api.mongodb.org/python/current/api/bson/dbref.html
15
http://api.mongodb.org//python/current/api/pymongo/database.html#pymongo.database.Database.dereference
4.4. Data Model Reference 163

MongoDB Documentation, Release 2.6.4
RubyThe Ruby Driver supports DBRefs using the
16
and the
17
.
Use
In most cases you should use themanual reference(page 162) method for connecting two or more related documents.
However, if you need to reference documents from multiple collections, consider using DBRefs.
4.4.3
GridFSstores les in two collections:
chunksstores the binary chunks. For details, seeThe chunks Collection(page 164).
filesstores the le's metadata. For details, seeThe les Collection(page 165).
GridFS places the collections in a common bucket by prexing each with the bucket name. By default, GridFS uses
two collections with names prexed byfsbucket:
fs.files
fs.chunks
You can choose a different bucket name thanfs, and create multiple buckets in a single database.
See also:
GridFS(page 138) for more information about GridFS.
ThechunksCollection
Each document in thechunkscollection represents a distinct chunk of a le as represented in theGridFSstore. The
following is a prototype document from thechunkscollection.:
{
"_id"ObjectId>,
"files_id"ObjectId>,
"n"num>,
"data"binary>
}
A document from thechunkscollection contains the following elds:
chunks._id
The uniqueObjectIdof the chunk.
chunks.files_id
The_idof the parent document, as specied in thefilescollection.
chunks.n
The sequence number of the chunk. GridFS numbers all chunks, starting with 0.
chunks.data
The chunk's payload as aBSONbinary type.
Thechunkscollection uses acompound indexonfiles_idandn, as described inGridFS Index(page 139).
16
http://api.mongodb.org//ruby/current/BSON/DBRef.html
17
http://api.mongodb.org//ruby/current/Mongo/DB.html#dereference-instance_method
164 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
ThefilesCollection
Each document in thefilescollection represents a le in theGridFSstore. Consider the following prototype of a
document in thefilescollection:
{
"_id"ObjectId>,
"length"num>,
"chunkSize"num>,
"uploadDate"timestamp>,
"md5"hash>,
"filename"string>,
"contentType"string>,
"aliases"string array>,
"metadata"dataObject>,
}
Documents in thefilescollection contain some or all of the following elds. Applications may create additional
arbitrary elds:
files._id
The unique ID for this document. The_idis of the data type you chose for the original document. The default
type for MongoDB documents isBSON 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 specied 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 rst stored by GridFS. This value has theDatetype.
files.md5
An MD5 hash returned by thefilemd5command. This value has theStringtype.
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.
4.4.4
Overview
ObjectIdis a 12-byteBSONtype, constructed using:

4.4. Data Model Reference 165

MongoDB Documentation, Release 2.6.4

In MongoDB, documents stored in a collection require a unique_ideld that acts as aprimary key. Because ObjectIds
are small, most likely unique, and fast to generate, MongoDB uses ObjectIds as the default value for the_ideld if
the_ideld is not specied. MongoDB clients should add an_ideld with a unique ObjectId. However, if a client
does not add an_ideld,mongodwill add an_ideld that holds an ObjectId.
Using ObjectIds for the_ideld provides the following additional benets:
mongoshell, you can access the creation time of theObjectId, using thegetTimestamp()method.
_ideld that storesObjectIdvalues is roughly equivalent to sorting by creation time.
Important:The relationship between the order ofObjectIdvalues 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;ObjectIdvalues do not represent a strict insertion order. Clock skew between clients can also
result in non-strict ordering even for values, because client drivers generateObjectIdvalues,notthemongod
process.
Also consider theDocuments(page 158) section for related information on MongoDB's document orientation.
ObjectId()
Themongoshell provides theObjectId()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 versionstoString()returns the hexadecimal string representation,
which as of version 2.2 can be retrieved by thestrproperty.
valueOf()
Returns the representation of the object as a hexadecimal string. The returned string is thestrattribute.
Changed in version 2.2: In previous versions,valueOf()returns the object.
Examples
Consider the following usesObjectId()class in themongoshell:
Generate a new ObjectId
To generate a new ObjectId, use theObjectId()constructor with no argument:
166 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
x
In this example, the value ofxwould be:
ObjectId("507f1f77bcf86cd799439011")
To generate a new ObjectId using theObjectId()constructor with a unique hexadecimal string:
y"507f191e810c19729de860ea")
In this example, the value ofywould be:
ObjectId("507f191e810c19729de860ea")
ObjectId()object, use thegetTimestamp()method as follows:
Convert an ObjectId into a Timestamp
To return the timestamp of anObjectId()object, use thegetTimestamp()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 thestrattribute of anObjectId()object, as follows:
ObjectId("507f191e810c19729de860ea").str
This operation will return the following hexadecimal string:
507f191e810c19729de860ea
To return the hexadecimal string representation of anObjectId(), use thevalueOf()method as follows:
ObjectId("507f191e810c19729de860ea").valueOf()
This operation returns the following output:
507f191e810c19729de860ea
To return the string representation of anObjectId()object, use thetoString()method as follows:
ObjectId("507f191e810c19729de860ea").toString()
This operation will return the following output:
507f191e810c19729de860ea
4.4.5
BSONis a binary serialization format used to store documents and make remote procedure calls in MongoDB. The
BSON specication is located at
18
.
18
http://bsonspec.org/
4.4. Data Model Reference 167

MongoDB Documentation, Release 2.6.4
BSON supports the following data types as values in documents. Each data type has a corresponding number that can
be used with the$typeoperator to query documents by BSON type.
Type Number
Double 1
String 2
Object 3
Array 4
Binary data 5
Undened 6
Object id 7
Boolean 8
Date 9
Null 10
Regular Expression11
JavaScript 13
Symbol 14
JavaScript (with scope)15
32-bit integer 16
Timestamp 17
64-bit integer 18
Min key 255
Max key 127
To determine a eld's type, seeCheck Types in the mongo Shell(page 252).
If you convert BSON to JSON, seehttp://docs.mongodb.org/manualreference/mongodb-extended-json .
Comparison/Sort Order
When comparing values of differentBSONtypes, MongoDB uses the following comparison order, from lowest to
highest:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion
before comparison.
The comparison treats a non-existent eld as it would an empty BSON Object. As such, a sort on theaeld in
documents{ }and{ a: null }would treat the documents as equivalent in sort order.
168 Chapter 4. Data Models

MongoDB Documentation, Release 2.6.4
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 eld whose
value is a single-element array (e.g.[ 1 ]) with non-array elds (e.g.2), the comparison is between1and2. A
comparison of an empty array (e.g.[ ]) treats the empty array as less thannullor a missing eld.
MongoDB sortsBinDatain the following order:
1.
2.
3.
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 rst
four bytes are a timestamp that reect the ObjectId's creation. Refer to theObjectId(page 165) 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.
19
In addition, MongoDB$regexqueries support UTF-8 in the regex string.
Timestamps
BSON has a special timestamp type forinternalMongoDB use and isnotassociated with the regularDate(page 170)
type. Timestamp values are a 64 bit value where:
time_tvalue (seconds since the Unix epoch)
ordinalfor operations within a given second.
Within a singlemongodinstance, timestamp values are always unique.
In replication, theoploghas atseld. The values in this eld reect the operation time, which uses a BSON
timestamp value.
Note:The BSON Timestamp type is forinternalMongoDB use. For most cases, in application development, you
will want to use the BSON date type. SeeDate(page 170) for more information.
If you create a BSON Timestamp using the empty constructor (e.g.new Timestamp()), MongoDB will only
generate a timestampifyou use the constructor in the rst eld of the document.
20
Otherwise, MongoDB will
generate an empty timestamp value (i.e.Timestamp(0, 0).)
Changed in version 2.1:mongoshell displays the Timestamp value with the wrapper:
Timestamp(<time_t>,ordinal>)
Prior to version 2.1, themongoshell display the Timestamp value as a document:
19
Given strings using UTF-8 character sets, usingsort()on strings will be reasonably correct. However, because internallysort()uses the
C++strcmpapi, the sort order may handle some characters incorrectly.
20
If the rst eld in the document is_id, then you can generate a timestamp in thesecondeld of a document.
4.4. Data Model Reference 169

MongoDB Documentation, Release 2.6.4
{ ttime_t>, iordinal>
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
21
refers to the BSON Date type as theUTC datetime.
Changed in version 2.0: BSON Date type is signed.
22
Negative values represent dates before 1970.
Example
Construct a Date using thenew Date()constructor in themongoshell:
varmydate1 newDate()
Example
Construct a Date using theISODate()constructor in themongoshell:
varmydate2
Example
Return theDatevalue as string:
mydate1.toString()
Example
Return the month portion of the Date value; months are zero-indexed, so that January is month0:
mydate1.getMonth()
21
http://bsonspec.org/#/specication
22
Prior to version 2.0,Datevalues were incorrectly interpreted asunsignedintegers, which affected sorts, range queries, and indexes onDate
elds. Because indexes are not recreated when upgrading, please re-index if you created an index onDatevalues with an earlier version, and dates
before 1970 are relevant to your application.
170 Chapter 4. Data Models

CHAPTER5
Administration
The administration documentation addresses the ongoing operation and maintenance of MongoDB instances and de-
ployments. This documentation includes both high level overviews of these concerns as well as tutorials that cover
specic procedures and processes for operating MongoDB.
Administration Concepts(page 171)Core conceptual documentation of operational practices for managing Mon-
goDB deployments and systems.
MongoDB Backup Methods(page 172)Describes approaches and considerations for backing up a MongoDB
database.
Monitoring for MongoDB(page 175)An overview of monitoring tools, diagnostic strategies, and approaches
to monitoring replica sets and sharded clusters.
Production Notes(page 188)A collection of notes that describe best practices and considerations for the oper-
ations of MongoDB instances and deployments.
Continue reading fromAdministration Concepts(page 171) for additional documentation of MongoDB admin-
istration.
Administration Tutorials(page 205)Tutorials that describe common administrative procedures and practices for op-
erations for MongoDB instances and deployments.
Conguration, Maintenance, and Analysis(page 205)Describes routine management operations, including
conguration and performance analysis.
Backup and Recovery(page 229)Outlines procedures for data backup and restoration withmongodinstances
and deployments.
Continue reading fromAdministration Tutorials(page 205) for more tutorials of common MongoDB mainte-
nance operations.
Administration Reference(page 266)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. SeeReplica
Set Tutorials(page 543) andSharded Cluster Tutorials(page 634) for additional tutorials and information.
5.1
The core administration documents address strategies and practices used in the operation of MongoDB systems and
deployments.
171

MongoDB Documentation, Release 2.6.4
Operational Strategies(page 172)Higher level documentation of key concepts for the operation and maintenance of
MongoDB deployments, including backup, maintenance, and conguration.
MongoDB Backup Methods(page 172)Describes approaches and considerations for backing up a MongoDB
database.
Monitoring for MongoDB(page 175)An overview of monitoring tools, diagnostic strategies, and approaches
to monitoring replica sets and sharded clusters.
Run-time Database Conguration(page 182)Outlines common MongoDB congurations and examples of
best-practice congurations for common use cases.
Data Management(page 194)Core documentation that addresses issues in data management, organization, mainte-
nance, and lifestyle management.
Data Center Awareness(page 194)Presents the MongoDB features that allow application developers and
database administrators to congure their deployments to be more data center aware or allow operational
and location-based separation.
Expire Data from Collections by Setting TTL(page 198)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(page 196)Capped collections provide a special type of size-constrained collections that
preserve insertion order and can support high volume inserts.
Optimization Strategies for MongoDB(page 200)Techniques for optimizing application performance with Mon-
goDB.
5.1.1
These documents address higher level strategies for common administrative tasks and requirements with respect to
MongoDB deployments.
MongoDB Backup Methods(page 172)Describes approaches and considerations for backing up a MongoDB
database.
Monitoring for MongoDB(page 175)An overview of monitoring tools, diagnostic strategies, and approaches to
monitoring replica sets and sharded clusters.
Run-time Database Conguration(page 182)Outlines common MongoDB congurations and examples of best-
practice congurations for common use cases.
Import and Export MongoDB Data(page 186)Provides an overview ofmongoimportandmongoexport, the
tools MongoDB includes for importing and exporting data.
Production Notes(page 188)A collection of notes that describe best practices and considerations for the operations
of MongoDB instances and deployments.
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(page 173)
Backup with mongodump(page 173)
MongoDB Management Service (MMS) Cloud Backup(page 174)
MongoDB Management Service (MMS) On Prem Backup Software(page 174)
172 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Backup by Copying Underlying Data Files
You can create a backup by copying MongoDB's underlying data les.
If the volume where MongoDB stores data les 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 specic 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 runningmongodprocess, you must have journaling enabled and the journal must reside
on the same logical volume as the other MongoDB data les. 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 cong server at approximately the same moment in time.
If your storage system does not support snapshots, you can copy the les directly usingcp,rsync, or a similar tool.
Since copying multiple les is not an atomic operation, you must stop all writes to themongodbefore copying the
les. Otherwise, you will copy the les in an invalid state.
Backups produced by copying the underlying data do not support point in time recovery for replica sets and are
difcult 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 theBackup and Restore with Filesystem Snapshots(page 229) andBackup a Sharded Cluster
with Filesystem Snapshots(page 239) for complete instructions on using LVM to create snapshots. Also see
and Restore Processes for MongoDB on Amazon EC2
1
.
Backup withmongodump
Themongodumptool reads data from a MongoDB database and creates high delity BSON les. The
mongorestoretool can populate a MongoDB database with the data from these BSON les. These tools are
simple and efcient for backing up small MongoDB deployments, but are not ideal for capturing backups of larger
systems.
mongodumpandmongorestorecan operate against a runningmongodprocess, and can manipulate the underly-
ing data les directly. By default,mongodumpdoes not capture the contents of thelocal database(page 598).
mongodumponly captures the documents in the database. The resulting backup is space efcient, but
mongorestoreormongodmust rebuild the indexes after restoring data.
When connected to a MongoDB instance,mongodumpcan adversely affectmongodperformance. If your data is
larger than system memory, the queries will push the working set out of memory.
To mitigate the impact ofmongodumpon the performance of the replica set, usemongodumpto capture back-
ups from asecondary(page 508) member of a replica set. Alternatively, you can shut down a secondary and use
mongodumpwith the data les directly. If you shut down a secondary to capture data withmongodumpensure that
the operation can complete before its oplog becomes too stale to continue replicating.
For replica sets,mongodumpalso supports a point in time feature with the--oplogoption. Applications may
continue modifying data whilemongodumpcaptures the output. To restore a point in time backup created with
--oplog, usemongorestorewith the--oplogReplayoption.
If applications modify data whilemongodumpis creating a backup,mongodumpwill compete for resources with
those applications.
1
http://docs.mongodb.org/ecosystem/tutorial/backup-and-restore-mongodb-on-amazon-ec2
5.1. Administration Concepts 173

MongoDB Documentation, Release 2.6.4
SeeBack Up and Restore with MongoDB Tools(page 234),Backup a Small Sharded Cluster with mongodump
(page 238), andBackup a Sharded Cluster with Database Dumps(page 241) for more information.
MongoDB Management Service (MMS) Cloud Backup
The
2
supports backup and restore for MongoDB deployments.
MMS continually backs up MongoDB replica sets and sharded systems by reading the oplog data from your MongoDB
cluster.
MMS Backup offers point in time recovery of MongoDB replica sets and a consistent snapshot of sharded systems.
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.
For sharded systems, MMS does not provide restores for arbitrary moments in time. MMS does provide periodic con-
sistent snapshots of the entire sharded cluster. Sharded cluster snapshots are difcult to achieve with other MongoDB
backup methods.
To restore a MongoDB cluster from an MMS Backup snapshot, you download a compressed archive of your MongoDB
data les and distribute those les before restarting themongodprocesses.
To get started with MMS Backup
3
, and consider the complete documentation of MMS see the
Manual
4
.
MongoDB Management Service (MMS) On Prem Backup Software
MongoDB Subscribers can install and run the same core software that powersMongoDB Management Service (MMS)
Cloud Backup(page 174) 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
5
page and the
6
.
Further Reading
Backup and Restore with Filesystem Snapshots(page 229)An outline of procedures for creating MongoDB data set
backups using system-level le snapshot tool, such asLVMor native storage appliance tools.
Restore a Replica Set from MongoDB Backups(page 232)Describes procedure for restoring a replica set from an
archived backup such as amongodumpor
7
le.
Back Up and Restore with MongoDB Tools(page 234)The procedure for writing the contents of a database to a
BSON (i.e. binary) dump le for backing up MongoDB databases.
Backup and Restore Sharded Clusters(page 238)Detailed procedures and considerations for backing up sharded
clusters and single shards.
Recover Data after an Unexpected Shutdown(page 246)Recover data from MongoDB data les that were not prop-
erly closed or have an invalid state.
2
https://mms.10gen.com/?pk_campaign=MongoDB-Org&pk_kwd=Backup-Docs
3
http://mms.mongodb.com
4
https://mms.mongodb.com/help/
5
https://www.mongodb.com/products/subscriptions
6
https://mms.mongodb.com/help-hosted/current/
7
https://mms.mongodb.com/?pk_campaign=mongodb-docs-admin-tutorials
174 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Monitoring for MongoDB
Monitoring is a critical component of all database administration. A rm 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 Mon-
goDB. It also introduces diagnostic strategies and suggestions for monitoring replica sets and sharded clusters.
Note:MongoDB Management Service (MMS)
8
is a hosted monitoring service which collects and aggregates data
to provide insight into the performance and operation of MongoDB deployments. See the
9
for
more information.
Monitoring Strategies
There are three methods for collecting data about the state of a running MongoDB instance:

database commandsreturn statistics regarding the current database state with greater delity.

10
collects data from running MongoDB deployments and provides visualiza-
tion and alerts based on that data. MMS is a free service provided by MongoDB.
Each strategy can help answer different questions and is useful in different contexts. These methods are complemen-
tary.
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.
UtilitiesThe 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.
mongostatmongostatcaptures 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.
Usemongostatto understand the distribution of operation types and to inform capacity planning. See the
mongostat manualfor details.
mongotopmongotoptracks and reports the current read and write activity of a MongoDB instance, and reports
these statistics on a per collection basis.
Usemongotopto check if your database activity and use match your expectations. See themongotop manual
for details.
8
https://mms.mongodb.com/?pk_campaign=mongodb-org&pk_kwd=monitoring
9
http://mms.mongodb.com/help/
10
https://mms.mongodb.com/?pk_campaign=mongodb-org&pk_kwd=monitoring
5.1. Administration Concepts 175

MongoDB Documentation, Release 2.6.4
REST InterfaceMongoDB provides a simple REST interface that can be useful for conguring monitoring and
alert scripts, and for other administrative tasks.
To enable, conguremongodto useREST, either by startingmongodwith the--restoption, or by setting the
net.http.RESTInterfaceEnabled setting totruein aconfiguration file.
For more information on using the REST Interface see, the
11
documentation.
HTTP ConsoleMongoDB provides a web interface that exposes diagnostic and monitoring information in a simple
web page. The web interface is accessible atlocalhost:<port>, where the<port>number is1000more than
themongodport .
For example, if a locally runningmongodis using the default port27017, access the HTTP console at
http://localhost:28017 .
CommandsMongoDB includes a number of commands that report on the state of the database.
These data may provide a ner 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. Thedb.currentOpmethod is another useful tool for identifying the database instance's
in-progress operations.
serverStatus TheserverStatuscommand, ordb.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.
serverStatusoutputs 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
12
.
Nevertheless, all administrators should be familiar with the data provided byserverStatus.
dbStatsThedbStatscommand, ordb.stats()from the shell, returns a document that addresses storage use
and data volumes. ThedbStatsreect 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 specic database. This output also allows you to compare
use between databases and to determine the averagedocumentsize in a database.
collStatsThecollStatsprovides statistics that resembledbStatson 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 infor-
mation about its indexes.
replSetGetStatus ThereplSetGetStatus command (rs.status()from the shell) returns an
overview of your replica set's status. ThereplSetGetStatusdocument details the state and conguration of
the replica set and statistics about its members.
Use this data to ensure that replication is properly congured, and to check the connections between the current host
and the other members of the replica set.
Third Party ToolsA number of third party monitoring tools have support for MongoDB, either directly, or through
their own plugins.
11
http://docs.mongodb.org/ecosystem/tools/http-interfaces
12
http://mms.mongodb.com
176 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Self Hosted Monitoring ToolsThese are monitoring tools that you must install, congure and maintain on your
own servers. Most are open source.
ToolPlugin Description
Gan-
glia
26
mongodb-ganglia
27
Python script to report operations per second, memory usage, btree statistics,
master/slave status and current connections.
Gan-
glia
gmond_python_modules
28
Parses output from theserverStatusandreplSetGetStatus
commands.
Mo-
top
29
None Realtime monitoring tool for MongoDB servers. Shows current operations
ordered by durations every second.
mtop
30
None A top like tool.
Munin
31
mongo-munin
32
Retrieves server statistics.
Muninmongomon
33
Retrieves collection statistics (sizes, index sizes, and each (congured) collection
count for one DB).
Muninmunin-plugins
Ubuntu PPA
34
Some additional munin plugins not in the main distribution.
Na-
gios
35
nagios-plugin-
mongodb
36
A simple Nagios check script, written in Python.
Zab-
bix
37
mikoomi-
mongodb
38
Monitors availability, resource utilization, health, performance and other
important metrics.
Also consider
39
, an index and query analyzing tool for MongoDB that compares MongoDB log les and indexes
to make indexing recommendations.
As part of
40
, you can run
41
, which offers the features of MMS in a package that
runs within your infrastructure.
Hosted (SaaS) Monitoring ToolsThese are monitoring tools provided as a hosted service, usually through a paid
subscription.
13
http://sourceforge.net/apps/trac/ganglia/wiki
14
https://github.com/quiiver/mongodb-ganglia
15
https://github.com/ganglia/gmond_python_modules
16
https://github.com/tart/motop
17
https://github.com/beaufour/mtop
18
http://munin-monitoring.org/
19
https://github.com/erh/mongo-munin
20
https://github.com/pcdummy/mongomon
21
https://launchpad.net/ chris-lea/+archive/munin-plugins
22
http://www.nagios.org/
23
https://github.com/mzupan/nagios-plugin-mongodb
24
http://www.zabbix.com/
25
https://code.google.com/p/mikoomi/wiki/03
26
http://sourceforge.net/apps/trac/ganglia/wiki
27
https://github.com/quiiver/mongodb-ganglia
28
https://github.com/ganglia/gmond_python_modules
29
https://github.com/tart/motop
30
https://github.com/beaufour/mtop
31
http://munin-monitoring.org/
32
https://github.com/erh/mongo-munin
33
https://github.com/pcdummy/mongomon
34
https://launchpad.net/ chris-lea/+archive/munin-plugins
35
http://www.nagios.org/
36
https://github.com/mzupan/nagios-plugin-mongodb
37
http://www.zabbix.com/
38
https://code.google.com/p/mikoomi/wiki/03
39
https://github.com/mongolab/dex
40
http://www.mongodb.com/products/mongodb-enterprise
41
http://mms.mongodb.com
5.1. Administration Concepts 177

MongoDB Documentation, Release 2.6.4
Name Notes
MongoDB Management
Service
50
MMS is a cloud-based suite of services for managing MongoDB deployments. MMS
provides monitoring and backup functionality.
Scout
51
Several plugins, including
52
,
53
, and
MongoDB Replica Set Monitoring
54
.
Server Density
55
Dashboard for MongoDB
56
, MongoDB specic alerts, replication failover timeline
and iPhone, iPad and Android mobile apps.
Application
Performance
Management
57
IBM has an Application Performance Management SaaS offering that includes
monitor for MongoDB and other applications and middleware.
Process Logging
During normal operation,mongodandmongosinstances report a live account of all server activity and operations to
either standard output or a log le. 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.
path. Enables logging to a le, rather than the standard output. You must specify the full path to the log le
when adjusting this setting.
logAppend. Adds information to a log le instead of overwriting the le.
Note:You can specify these conguration operations as the command line arguments tomongodormongos
For example:
mongod -v --logpath /var/log/mongodb/server1.log --logappend
Starts amongod instance inverbose mode, appending data to the log le at
/var/log/mongodb/server1.log/ .
The followingdatabase commandsalso affect logging:
getLog. Displays recent messages from themongodprocess log.
logRotate. Rotates the log les formongodprocesses only. SeeRotate Log Files(page 214).
42
https://mms.mongodb.com/?pk_campaign=mongodb-org&pk_kwd=monitoring
43
http://scoutapp.com
44
https://scoutapp.com/plugin_urls/391-mongodb-monitoring
45
http://scoutapp.com/plugin_urls/291-mongodb-slow-queries
46
http://scoutapp.com/plugin_urls/2251-mongodb-replica-set-monitoring
47
http://www.serverdensity.com
48
http://www.serverdensity.com/mongodb-monitoring/
49
http://ibmserviceengage.com
50
https://mms.mongodb.com/?pk_campaign=mongodb-org&pk_kwd=monitoring
51
http://scoutapp.com
52
https://scoutapp.com/plugin_urls/391-mongodb-monitoring
53
http://scoutapp.com/plugin_urls/291-mongodb-slow-queries
54
http://scoutapp.com/plugin_urls/2251-mongodb-replica-set-monitoring
55
http://www.serverdensity.com
56
http://www.serverdensity.com/mongodb-monitoring/
57
http://ibmserviceengage.com
178 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
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 trafc 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.
LocksMongoDB 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 theglobalLocksection
of theserverStatusoutput. IfglobalLock.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.
IfglobalLock.totalTime is high relative touptime, the database has existed in a lock state for a signicant
amount of time. IfglobalLock.ratiois 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 insufcient RAM resulting inpage faults
(page 179) and disk reads.
Memory UsageMongoDB uses memory mapped les to store data. Given a data set of sufcient 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 les make it difcult to determine if the amount of RAM is
sufcient for the data set.
Thememory usage statusesmetrics of theserverStatusoutput can provide insight into MongoDB's memory use.
Check the resident memory use (i.e.mem.resident): if this exceeds the amount of system memoryandthere is a
signicant 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 accesspage faultsto read data from virtual memory and negatively
affect performance.
Page FaultsPage faults can occur as MongoDB reads from or writes data to parts of its data les 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 theextra_info.page_faults value in theserverStatusoutput.
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
5.1. Administration Concepts 179

MongoDB Documentation, Release 2.6.4
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 asharded clusteror addingshardsto your deployment to distribute load
amongmongodinstances.
SeeWhat are page faults?(page 715) for more information.
Number of ConnectionsIn 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 elds in theserverStatusdocument can provide insight:
globalLock.activeClients contains a counter of the total number of clients with active operations in
progress or queued.
connectionsis a container for the following two elds:
currentthe total number of current clients that connect to the database instance.
availablethe 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 yourreplica setand distribute read operations tosecondarymembers. For write heavy
applications, deployshardingand add one or moreshardsto asharded clusterto distribute load amongmongod
instances.
Spikes in the number of connections can also be the result of application or driver errors. All of the ofcially supported
MongoDB drivers implement connection pooling, which allows clients to use and reuse connections more efciently.
Extremely high numbers of connections, particularly without corresponding workload is often indicative of a driver or
other conguration error.
Unless constrained by system-wide limits MongoDB has no limit on incoming connections. You can modify system
limits using theulimitcommand, or by editing your system's/etc/sysctlle. SeeUNIX ulimit Settings
(page 266) for more information.
Database ProlingMongoDB's Proler is a database proling system that can help identify inefcient queries
and operations.
The following proling levels are available:
LevelSetting
0 Off. No proling
1 On. Only includesslowoperations
2 On. Includesalloperations
Enable the proler by setting theprofilevalue using the following command in themongoshell:
db.setProfilingLevel(1)
TheslowOpThresholdMs setting denes what constitutes a slow operation. To set the threshold above
which the proler considers operations slow (and thus, included in the level1proling data), you can congure
slowOpThresholdMsat runtime as an argument to thedb.setProfilingLevel() operation.
See
The documentation ofdb.setProfilingLevel() for more information about this command.
By default,mongodrecords all slow queries to itslog, as dened byslowOpThresholdMs.
180 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Note:Because the database proler can negatively impact performance, only enable proling for strategic intervals
and as minimally as possible on production systems.
You may enable proling on a per-mongodbasis. This setting will not propagate across areplica setorsharded
cluster.
You can view the output of the proler in thesystem.profilecollection of your database by issuing theshow
profilecommand in themongoshell, or with the following operation:
db.system.profile.find( { millis
This returns all operations that lasted longer than 100 milliseconds. Ensure that the value specied here (100, in this
example) is above theslowOpThresholdMsthreshold.
See also:
Optimization Strategies for MongoDB(page 200) 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 theprimaryto asecondary. Some small delay period may be acceptable, but two signicant problems emerge as
replication lag grows:

using replication to ensure data persistence, exceptionally long delays may impact the integrity of your data set.
oplog) then MongoDB will have to perform
an initial sync on the secondary, copying all data from theprimaryand rebuilding all indexes. This is uncommon
under normal circumstances, but if you congure the oplog to be smaller than the default, the issue can arise.
Note:The size of the oplog is only congurable during the rst run using the--oplogSizeargument to the
mongodcommand, or preferably, theoplogSizeMBsetting in the MongoDB conguration le. If you do not
specify this on the command line before running with the--replSetoption,mongodwill 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 theChange the Size of the Oplog(page 570)
For causes of replication lag, seeReplication Lag(page 589).
Replication issues are most often the result of network connectivity issues between members, or the result of aprimary
that does not have the resources to support application and replication trafc. To check the status of a replica, use the
replSetGetStatusor the following helper in the shell:
rs.status()
Thehttp://docs.mongodb.org/manualreference/command/replSetGetStatus document pro-
vides a more in-depth overview view of this output. In general, watch the value ofoptimeDate, and pay particular
attention to the time difference between theprimaryand thesecondarymembers.
5.1. Administration Concepts 181

MongoDB Documentation, Release 2.6.4
Sharding and Monitoring
In most cases, the components ofsharded clustersbenet 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 theSharding Concepts(page 613) documentation for more information.
Cong ServersThecong databasemaintains a map identifying which documents are on which shards. The cluster
updates this map aschunksmove between shards. When a conguration server becomes inaccessible, certain sharding
operations become unavailable, such as moving chunks and startingmongosinstances. However, clusters remain
accessible from already-runningmongosinstances.
Because inaccessible conguration servers can seriously impact the availability of a sharded cluster, you should mon-
itor your conguration servers to ensure that the cluster remains well balanced and thatmongosinstances can restart.
MMS Monitoring
58
monitors cong servers and can create notications if a cong server becomes inaccessible.
Balancing and Chunk DistributionThe most effectivesharded clusterdeployments evenly balancechunksamong
the shards. To facilitate this, MongoDB has a backgroundbalancerprocess that distributes data to ensure that chunks
are always optimally distributed among theshards.
Issue thedb.printShardingStatus() orsh.status()command to themongosby way of themongo
shell. This returns an overview of the entire cluster including the database name, and a list of the chunks.
Stale LocksIn 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 amongosinstance using themongoshell. Issue the following
command sequence to switch to theconfigdatabase 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
selectedmongos, takes a special balancer lock that prevents other balancing activity from transpiring. Use the
following command, also to theconfigdatabase, to check the status of the balancer lock.
db.locks.find( { _id
If this lock exists, make sure that the balancer process is actively using this lock.
Run-time Database Conguration
Thecommand lineandconfiguration file interfaces provide MongoDB administrators with a large num-
ber of options and settings for controlling the operation of the database system. This document provides an overview
of common congurations and examples of best-practice congurations for common use cases.
While both interfaces provide access to the same collection of options and settings, this document primarily uses the
conguration le interface. If you run MongoDB using a control script or installed from a package for your operating
system, you likely already have a conguration le located at/etc/mongodb.conf. Conrm this by checking the
contents of the/etc/init.d/mongod or/etc/rc.d/mongodscript to ensure that thecontrol scriptsstart the
mongodwith the appropriate conguration le (see below.)
58
http://mms.mongodb.com
182 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
To start a MongoDB instance using this conguration 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 le on your system to control the conguration of your database
instance.
Congure the Database
Consider the following basic conguration:
fork
bind_ip
port
quiet
dbpath
logpath
logappend
journal
For most standalone servers, this is a sufcient base conguration. It makes several assumptions, but consider the
following explanation:
forkistrue, which enables adaemonmode formongod, which detaches (i.e. forks) the MongoDB from
the current session and allows you to run the database as a conventional server.
bindIpis127.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
ltering (i.e. rewall).
New in version 2.6:mongodinstalled from ofcial.deb(page 12) and.rpm(page 6) packages have the
bind_ipconguration set to127.0.0.1by default.
portis27017, which is the default MongoDB port for database instances. MongoDB can bind to any port.
You can also lter access based on port using network ltering tools.
Note:UNIX-like systems require superuser privileges to attach processes to ports lower than 1024.
quietistrue. This disables all but the most critical entries in output/log le. In normal operation this is
the preferable operation to avoid log noise. In diagnostic or testing situations, set this value tofalse. Use
setParameterto modify this setting during run time.
dbPathis/srv/mongodb, which species where MongoDB will store its data les./srv/mongodband
/var/lib/mongodbare popular locations. The user account thatmongodruns under will need read and
write access to this directory.
systemLog.pathis/var/log/mongodb/mongod.log which is wheremongodwill write its output.
If you do not set this value,mongodwrites all output to standard output (e.g.stdout.)
logAppendistrue, which ensures thatmongoddoes not overwrite an existing log le following the server
start operation.
storage.journal.enabled istrue, which enablesjournaling. Journaling ensures single instance write-
durability. 64-bit builds ofmongodenable journaling by default. Thus, this setting may be redundant.
Given the default conguration, some of these values may be redundant. However, in many situations explicitly stating
the conguration increases overall system intelligibility.
5.1. Administration Concepts 183

MongoDB Documentation, Release 2.6.4
Security Considerations
The following collection of conguration options are useful for limiting access to amongodinstance. Consider the
following:
bind_ip
auth
Consider the following explanation for these conguration 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; and192.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.
enabled tofalsedisables 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.
authorization istrueenables the authentication system within MongoDB. If enabled you will need to
log in by connecting over thelocalhostinterface for the rst time to create user credentials.
See also:
Security Concepts(page 281)
Replication and Sharding Conguration
Replication CongurationReplica setconguration is straightforward, and only requires that thereplSetName
have a value that is consistent among all members of the set. Consider the following:
replSet
Use descriptive names for sets. Once congured use themongoshell to add hosts to the replica set.
See also:
Replica set reconguration.
To enable authentication for thereplica set, add the following option:
keyFile
New in version 1.8: for replica sets, and 1.9.1 for sharded replica sets.
SettingkeyFileenables authentication and species a key le for the replica set member use to when authenticating
to each other. The content of the key le is arbitrary, but must be the same on all members of thereplica setand
mongosinstances that connect to the set. The keyle must be less than one kilobyte in size and may only contain
characters in the base64 set and the le must not have group or world permissions on UNIX systems.
See also:
TheReplica set Recongurationsection for information regarding the process for changing replica set during opera-
tion.
Additionally, consider theReplica Set Securitysection for information on conguring authentication with replica sets.
Finally, see theReplication(page 503) document for more information on replication in MongoDB and replica set
conguration in general.
184 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Sharding CongurationSharding requires a number ofmongodinstances with different congurations. The con-
g servers store the cluster's metadata, while the cluster distributes data among one or more shard servers.
Note:Cong serversare notreplica sets.
To set up one or three cong server instances asnormal(page 183)mongodinstances, and then add the following
conguration option:
configsvr
bind_ip
port
This creates a cong server running on the private IP address10.8.0.12on port27001. Make sure that there are
no port conicts, and that your cong server is accessible from all of yourmongosandmongodinstances.
To set up shards, congure two or moremongodinstance using yourbase conguration(page 183), with the
shardsvrvalue for theclusterRolesetting:
shardsvr
Finally, to establish the cluster, congure at least onemongosprocess with the following settings:
configdb
chunkSize
You can specify multipleconfigDBinstances by specifying hostnames and ports in the form of a comma separated
list. In general, avoid modifying thechunkSizefrom the default value of 64,
59
andshouldensure this setting is
consistent among allmongosinstances.
See also:
TheSharding(page 607) section of the manual for more information on sharding and cluster conguration.
Run Multiple Database Instances on the Same System
In many cases running multiple instances ofmongodon a single system is not recommended. On some types of
deployments
60
and for testing purposes you may need to run more than onemongodon a single system.
In these cases, use abase conguration(page 183) for each instance, but consider the following conguration values:
dbpath
pidfilepath
ThedbPathvalue controls the location of themongodinstance's data directory. Ensure that each database has a
distinct and well labeled data directory. ThepidFilePathcontrols wheremongodprocess places it'sprocess id
le. As this tracks the specicmongodle, it is crucial that le be unique and well labeled to make it easy to start
and stop these processes.
Create additionalcontrol scriptsand/or adjust your existing MongoDB conguration and control script as needed to
control these processes.
59
Chunksize 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.
60
Single-tenant systems withSSDor other high performance disks may provide acceptable performance levels for multiplemongodinstances.
Additionally, you may nd that multiple databases with small working sets may function acceptably on a single system.
5.1. Administration Concepts 185

MongoDB Documentation, Release 2.6.4
Diagnostic Congurations
The following conguration options control variousmongodbehaviors for diagnostic purposes. The following set-
tings have default values that tuned for general production purposes:
slowms
profile
verbose
objcheck
Use thebase conguration(page 183) and add these options if you are experiencing some unknown issue or perfor-
mance problem as needed:
slowOpThresholdMscongures the threshold for to consider a query slow, for the purpose of the logging
system and thedatabase proler. The default value is 100 milliseconds. Set a lower value if the database
proler does not return useful results, or a higher value to only log the longest running queries. SeeOptimization
Strategies for MongoDB(page 200) for more information on optimizing operations in MongoDB.
modesets thedatabase prolerlevel. The proler is not active by default because of the possible impact on the
proler itself on performance. Unless this setting has a value, queries are not proled.
verbositycontrols the amount of logging output thatmongodwrite to the log. Only use this option if you
are experiencing an issue that is not reected in the normal logging level.
wireObjectCheckforcesmongodto 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 clientdriverto interact with the database itself. For disaster recovery protection and
routine database backup operation, use fulldatabase instance backups(page 172).
Warning:Because these tools primarily operate by interacting with a runningmongodinstance, they can impact
the performance of your running database.
Not only do these processes create trafc 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(page 172) or
61
for more information on backing up MongoDB
instances. Additionally, consider the following references for the MongoDB import/export tools:
http://docs.mongodb.org/manualreference/program/mongoimport
http://docs.mongodb.org/manualreference/program/mongoexport
http://docs.mongodb.org/manualreference/program/mongorestore
http://docs.mongodb.org/manualreference/program/mongodump
61
https://mms.mongodb.com/help/backup
186 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Data Import, Export, and Backup Operations
For resilient and non-disruptive backups, use a le system or block-level disk snapshot function, such as the meth-
ods described in theMongoDB Backup Methods(page 172) 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 modied section of data for extra
insurance, or for ease of access.
Warning: mongoimportandmongoexportdo not reliably preserve all richBSONdata
types becauseJSONcan only represent a subset of the types supported by BSON. As a re-
sult, data exported or imported with these tools may lose some measure of delity. See
http://docs.mongodb.org/manualreference/mongodb-extended-json for more infor-
mation.
No matter how you decide to import or export your data, consider the following guidelines:

port/backup reect.

type delity) and consistency if updates continue during the backup process.

Human Intelligible Import/Export Formats
This section describes a process to import/export a collection to a le in aJSONorCSVformat.
The examples in this section use the MongoDB toolshttp://docs.mongodb.org/manualreference/program/mongoimport
andhttp://docs.mongodb.org/manualreference/program/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 thecopydb,
clone, orcloneCollectioncommands, which may be more suited to this task. Themongoshell provides
thedb.copyDatabase()method.
Collection Export withmongoexport
Warning: mongoimportandmongoexportdo not reliably preserve all richBSONdata
types becauseJSONcan only represent a subset of the types supported by BSON. As a re-
sult, data exported or imported with these tools may lose some measure of delity. See
http://docs.mongodb.org/manualreference/mongodb-extended-json for more infor-
mation.
With themongoexportutility you can create a backup le. 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 namedcollectioninto the lecollection.json. Without
the output specication (i.e. --out collection.json ),mongoexportwrites output to standard output (i.e.
stdout). You can further narrow the results by supplying a query lter using the --query and limit results to a
single database using the --db option. For instance:
5.1. Administration Concepts 187

MongoDB Documentation, Release 2.6.4
mongoexport --db sales --collection contacts --query
This command returns all documents in thesalesdatabase'scontactscollection, with a eld namedfieldwith
a value of1. 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,mongoexportreturns oneJSON documentper MongoDB document. Specify the --jsonArray
argument to return the export as a singleJSONarray. Use the --csv le to return the result in CSV (comma
separated values) format.
If yourmongodinstance is not running, you can use the --dbpath option to specify the location to your Mon-
goDB instance's database les. See the following example:
mongoexport --db sales --collection contacts --dbpath /srv/MongoDB/
This reads the data les directly. This locks the data directory to prevent conicting writes. Themongodprocess must
notbe running or attached to these data les when you runmongoexportin this conguration.
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 anymongoexportcommand you may, as above specify username and password credentials as above.
Collection Import withmongoimport
Warning: mongoimportandmongoexportdo not reliably preserve all richBSONdata
types becauseJSONcan only represent a subset of the types supported by BSON. As a re-
sult, data exported or imported with these tools may lose some measure of delity. See
http://docs.mongodb.org/manualreference/mongodb-extended-json for more infor-
mation.
To restore a backup taken withmongoexport. Most of the arguments tomongoexportalso exist for
mongoimport. Consider the following command:
mongoimport --collection collection --file collection.json
This imports the contents of the lecollection.jsoninto the collection namedcollection. If you do not
specify a le with the --file option,mongoimportaccepts input over standard input (e.g. stdin.)
If you specify the --upsert option, all ofmongoimportoperations will attempt to update existing documents
in the database and insert other documents. This option will cause some performance impact depending on your
conguration.
You can specify the database option--dbto 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
les. Consider using the --journal option to ensure thatmongoimportrecords its operations in the jour-
nal. Themongodprocess mustnotbe running or attached to these data les when you runmongoimportin this
conguration.
Use the --ignoreBlanks option to ignore blank elds. ForCSVandTSVimports, this option provides the
desired functionality in most cases: it avoids inserting blank elds in MongoDB documents.
Production Notes
This page details system congurations that affect MongoDB, especially in production.
Note:MongoDB Management Service (MMS)
62
is a hosted monitoring service which collects and aggregates diag-
188 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
nostic data to provide insight into the performance and operation of MongoDB deployments. See the
63
and the
64
for more information.
Packages
MongoDBBe sure you have the latest stable release. All releases are available on the
65
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 the32-bit limitations page
(page 690) for more information.
32-bit builds exist to support use on development machines.
Operating SystemsMongoDB 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
66
(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 theConcurrency(page 702) page for more
information.
Journaling
MongoDB useswrite ahead loggingto an on-diskjournalto guarantee that MongoDB is able to quickly recover the
write operations(page 67) following a crash or other serious failure.
In order to ensure thatmongodwill be able to recover its data les and keep the data les in a valid state following a
crash, leave journaling enabled. SeeJournaling(page 275) for more information.
Networking
Use Trusted Networking EnvironmentsAlways run MongoDB in atrusted environment, with network rules that
prevent access fromallunknown machines, systems, and networks. As with any sensitive system dependent on
network access, your MongoDB deployment should only be accessible to specic systems that require access, such as
application servers, monitoring services, and other MongoDB components.
Note:By default,authorizationis not enabled andmongodassumes a trusted environment. You can enable
security/auth(page 281) mode if you need it.
62
http://mms.mongodb.com
63
http://mms.mongodb.com/
64
http://mms.mongodb.com/help/
65
http://www.mongodb.org/downloads
66
http://www.gnu.org/software/libc/
5.1. Administration Concepts 189

MongoDB Documentation, Release 2.6.4
See documents in theSecurity Section(page 279) for additional information, specically:
Conguration Options(page 288)
Firewalls(page 289)
Network Security Tutorials(page 297)
For Windows users, consider the
67
when deploying MongoDB
on Windows.
Connection PoolsTo avoid overloading the connection resources of a singlemongodormongosinstance, ensure
that clients maintain reasonable connection pool sizes.
TheconnPoolStatsdatabase command returns information regarding the number of open connections to the
current database formongosinstances andmongodinstances in sharded clusters.
Hardware Considerations
MongoDB is designed specically with commodity hardware in mind and has few hardware requirements or limita-
tions. 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 LimitationsThe hardware for the most effective MongoDB deployments have the
following properties:
Allocate Sufcient RAM and CPUAs 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
signicant 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 ofmongod.
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 Filesystems(page 191) for
more information about storage and MongoDB.
67
http://technet.microsoft.com/en-us/library/dd349797.aspx
190 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
MongoDB and NUMA Hardware
Important:The discussion of NUMA in this section only applies to Linux systems withmultiplephysical processors,
and therefore doesnot affectdeployments wheremongodinstances run on other UNIX-like systems, on Windows, or
on a Linux system with only one physical processor.
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 or high system process usage.
When running MongoDB on NUMA hardware, you should disable NUMA for MongoDB and instead set an interleave
memory policy.
Note:MongoDB version 2.0 and greater checks these settings on start up when deployed on a Linux-based system,
and prints a warning if the system is NUMA-based.
To disable NUMA for MongoDB and set an interleave memory policy, use thenumactlcommand and startmongod
in the following manner:
numactl --interleave=all /usr/bin/local/mongod
Then, disablezone reclaimin theprocsettings using the following command:
echo
To fully disable NUMA, you must perform both operations. For more information, see the
/proc/sys/vm/*
68
.
See
69
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.
Disk and Storage Systems
SwapAssign swap space for your systems. Allocating swap space can avoid issues with memory contention and
can prevent the OOM Killer on Linux systems from killingmongod.
The methodmongoduses to map memory les to memory ensures that the operating system will never store Mon-
goDB data in swap space.
RAIDMost MongoDB deployments should use disks backed by RAID-10.
RAID-5 and RAID-6 do not typically provide sufcient 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 FilesystemsThe Network File System protocol (NFS) is not recommended for use with MongoDB as some
versions perform poorly.
Performance problems arise when both the data les and the journal les are hosted on NFS. You may experience
better performance if you place the journal on local oriscsivolumes. If you must use NFS, add the following NFS
options to your/etc/fstable:bg,nolock, andnoatime.
68
http://www.kernel.org/doc/Documentation/sysctl/vm.txt
69
http://jcole.us/blog/archives/2010/09/28/mysql-swap-insanity-and-the-numa-architecture/
5.1. Administration Concepts 191

MongoDB Documentation, Release 2.6.4
Separate Components onto Different Storage DevicesFor improved performance, consider separating your
database's data, journal, and logs onto different storage devices, based on your application's access and write pat-
tern.
Note:This will affect your ability to create snapshot-style backups of your data, since the les will be on different
devices and volumes.
Scheduling for Virtual DevicesLocal block devices attached to virtual machine instances via the hypervisor should
use anoopscheduler for best performance. Thenoopscheduler allows the operating system to defer I/O scheduling to
the underlying hypervisor.
Architecture
Write ConcernWrite concerndescribes 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 aweakwrite concern, write operations return quickly. In some failure cases, write operations issued with
weak write concerns may not persist. Withstrongerwrite concerns, clients wait after sending a write operation for
MongoDB to conrm the write operations.
MongoDB provides different levels of write concern to better address the specic 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 theWrite Concern(page 72) document for more information about choosing an appropriate write concern level
for your deployment.
Replica SetsSee theReplica Set Architectures(page 516) document for an overview of architectural considerations
for replica set deployments.
Sharded ClustersSee theSharded Cluster Production Architecture(page 618) document for an overview of rec-
ommended 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
mongodinstances run other UNIX-like systems or on Windows.
Kernel and File SystemsWhen running MongoDB in production on Linux, it is recommended that you use Linux
kernel version 2.6.36 or later.
MongoDB preallocates its database les before using them and often creates large les. As such, you should use the
Ext4 and XFS le systems:
2.6.23of the Linux Kernel.
2.6.25of the Linux Kernel.

192 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Linux Distribution FilesystemKernel Version
CentOS 5.5 ext4, xfs2.6.18-194.el5
CentOS 5.6 ext4, xfs2.6.18-238.el5
CentOS 5.8 ext4, xfs2.6.18-308.8.2.el5
CentOS 6.1 ext4, xfs2.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, xfs2.6.32-38-server
Amazon Linux AMI release 2012.03ext4 3.2.12-3.2.4.amzn1.x86_64
Important:MongoDB requires a lesystem that supportsfsync()on directories. For example, HGFS and Virtual
Box's shared folders donotsupport this operation.
Recommended Conguration
atimefor the storage volume containing thedatabase les.
-n, and the user process limit (ulimit),-u, above 20,000, according to the sug-
gestions in theulimit(page 266) 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.
transparent huge pages as MongoDB performs better with normal (4096 bytes) virtual mem-
ory pages.
MongoDB on NUMA Hardware(page 191).

access use patterns, set low readahead values. A readahead of 32 (16kb) often works well.
For a standard block device, you can runsudo blockdev --report to get the readahead settings and
sudo blockdev --setra <value> <device> to change the readahead settings. Refer to your spe-
cic operating system manual for more information.

sharded clusters.
MongoDB on Virtual EnvironmentsThe section describes considerations when running MongoDB in some of the
more common virtual environments.
For all platforms, considerScheduling for Virtual Devices(page 192).
EC2MongoDB is compatible with EC2 and requires no conguration changes specic 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
70
.
VMWareMongoDB 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, rst stopmongod, then clone the VM, and nally, restartmongod.
70
http://www.mongodb.com/blog/post/provisioned-iops-aws-marketplace-signicantly-boosts-mongodb-performance-ease-use
5.1. Administration Concepts 193

MongoDB Documentation, Release 2.6.4
OpenVZSome 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
iostatOn Linux, use theiostatcommand 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
trafc in MB/s, at one second intervals:
iostat -xmt 1
Key elds fromiostat:
%util: this is the most useful eld 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 reect more random IO operations.
bwm-ngbwm-ng
71
is a command-line tool for monitoring network use. If you suspect a network-based bottleneck,
you may usebwm-ngto begin your diagnostic process.
Backups
To make backups of your MongoDB database, please refer toMongoDB Backup Methods Overview(page 172).
5.1.2
These document introduce data management practices and strategies for MongoDB deployments, including strategies
for managing multi-data center deployments, managing larger le stores, and data lifecycle tools.
Data Center Awareness(page 194)Presents the MongoDB features that allow application developers and database
administrators to congure their deployments to be more data center aware or allow operational and location-
based separation.
Capped Collections(page 196)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(page 198)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
MongoDB provides a number of features that allow application developers and database administrators to customize
the behavior of asharded clusterorreplica setdeployment so that MongoDB may bemoredata center aware, or
allow operational and location-based separation.
71
http://www.gropp.org/?id=projects&sub=bwm-ng
194 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
MongoDB also supports segregation based on functional parameters, to ensure that certainmongodinstances are
only used for reporting workloads or that certain high-frequency portions of a sharded collection only exist on specic
shards.
The following documents,found either in this section or other sections of this manual, provide information on cus-
tomizing a deployment for operation- and location-based separation:
Operational Segregation in MongoDB Deployments(page 195)MongoDB lets you specify that certain application
operations use certainmongodinstances.
Tag Aware Sharding(page 671)Tags associate specic ranges ofshard keyvalues with specic shards for use in
managing deployment patterns.
Manage Shard Tags(page 672)Use tags to associate specic ranges of shard key values with specic shards.
Operational Segregation in MongoDB Deployments
Operational OverviewMongoDB 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 themongodinstances. 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 certainmongodinstances are only used for reporting workloads or that certain high-frequency portions of a
sharded collection only exist on specic shards.
Specically, with MongoDB, you can:

shard keybalance onto and reside on specicshards.

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(page 530), which controls how drivers help applications target read operations to members
of a replica set.
Write Concerns(page 72), which controls how MongoDB ensures that write operations propagate to members
of a replica set.
Replica Set Tags(page 576), which control how applications create and interact with custom groupings of replica
set members to create custom application-specic read preferences and write concerns.
Tag Aware Sharding(page 671), which allows MongoDB administrators to dene an application-specic bal-
ancing policy, to control how documents belonging to specic 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 ofreplication(page 503), andsharding(page 607).
5.1. Administration Concepts 195

MongoDB Documentation, Release 2.6.4
Further Reading
Write Concern(page 72) andRead Preference(page 530) documents, which address capabilities related to
data center awareness.
Deploy a Geographically Redundant Replica Set(page 550).
Capped Collections
Capped collectionsare xed-size collections that support high-throughput operations that insert, retrieve, and delete
documents based on insertion order. Capped collections work in a way similar to circular buffers: once a collection
lls its allocated space, it makes room for new documents by overwriting the oldest documents in the collection.
SeecreateCollection() orcreatefor more information on creating capped collections.
Capped collections have the following behaviors:

return documents in insertion order. Without this indexing overhead, they can support higher insertion through-
put.
natural order) and do so
by prohibiting updates that increase document size. Capped collections only allow updates that t the original
document size, which ensures a document does not change its location on disk.

explicit remove operations.
For example, theoplog.rscollection that stores a log of the operations in areplica setuses a capped collection.
Consider the following potential use cases for capped collections:

an index is close to the speed of writing log information directly to a le system. Furthermore, the built-in
rst-in-rst-outproperty maintains the order of events, while managing storage use.

either need to ensure that this collectionalwaysremains in the working set (i.e. in RAM)oraccept some write
penalty for the required index or indexes.
Recommendations and Restrictions

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.

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 afailing update: objects in a capped
ns cannot growerror message.
To prevent this error, create your secondary from a snapshot of one of the other up-to-date members of the
replica set. Followour tutorial on lesystem snapshots(page 229) to seed your new secondary.
Seeding the secondary with a lesystem snapshot is the only way to guarantee the primary and secondary binary
les are compatible. MMS Backup snapshots are insufcient in this situation since you need more than the
content of the secondary to match the primary.
196 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4

`emptycapped' command. To remove the collection entirely, use thedrop()method.

_ideld and an index on the_ideld by default. Capped
collections created before 2.2 do not have an index on the_ideld by default. If you are using capped
collections with replication prior to 2.2, you should explicitly create an index on the_ideld.
Warning:If you have a capped collection in areplica setoutside of thelocaldatabase, before 2.2,
you should create a unique index on_id. Ensure uniqueness using theunique: true option to
theensureIndex()method or by using anObjectIdfor the_ideld. Alternately, you can use the
autoIndexIdoption tocreatewhen creating the capped collection, as in theQuery a Capped Collec-
tion(page 197) procedure.

(somewhat) analogous to tail on a log le.
$outcannot write results to a capped collection.
Procedures
Create a Capped CollectionYou must create capped collections explicitly using thecreateCollection()
method, which is a helper in themongoshell for thecreatecommand. 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(, { capped: true, size:
Additionally, you may also specify a maximum number of documents for the collection using themaxeld as in the
following document:
db.createCollection("log", { capped true, size, max
Important:Thesizeargument isalwaysrequired, even when you specifymaxnumber of documents. MongoDB
will remove older documents if a collection reaches the maximum size limit before it reaches the maximum document
count.
See
createCollection() andcreate.
Query a Capped CollectionIf you perform afind()on a capped collection with no ordering specied, MongoDB
guarantees that the ordering of results is the same as the insertion order.
To retrieve documents in reverse insertion order, issuefind()along with thesort()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 CappedUse theisCapped()method to determine if a collection is capped, as follows:
db.collection.isCapped()
5.1. Administration Concepts 197

MongoDB Documentation, Release 2.6.4
Convert a Collection to CappedYou can convert a non-capped collection to a capped collection with the
convertToCappedcommand:
db.runCommand({"convertToCapped":, size:});
Thesizeparameter species 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_idunless you specied
autoIndexIdto thecreate, after 2.2 this became the default.
Automatically Remove Data After a Specied Period of TimeFor additional exibility when expiring data, con-
sider MongoDB'sTTLindexes, as described inExpire Data from Collections by Setting TTL(page 198). These indexes
allow you to expire and remove data from normal collections using a special type, based on the value of a date-typed
eld and a TTL value for the index.
TTL Collections(page 198) are not compatible with capped collections.
Tailable CursorYou can use atailable cursorwith capped collections. Similar to the Unixtail -fcommand,
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.
SeeCreate Tailable Cursor(page 109) 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 themongodautomatically remove data after a specied number
of seconds or at a specic 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 index type supports the implementation of TTL collections. TTL relies on a background thread inmongod
that reads the date-typed values in the index and removes expireddocumentsfrom the collection.
Considerations
_ideld does not support TTL indexes.

BSON typeor an array of dateBSON types.

when thelowest(i.e. earliest) date matches the expiration threshold.

capped collection.
198 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
ensureIndex()to change the value ofexpireAfterSeconds. Instead use the
collModdatabase command in conjunction with theindexcollection ag.
background(page 460), 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 nishes building.
When the TTL thread is active, you will seedelete(page 67) operations in the output ofdb.currentOp()or in the
data collected by thedatabase proler(page 210).
When using TTL indexes onreplica sets, the TTL background threadonlydeletes documents onprimarymembers.
However, the TTL background threaddoesrun on secondaries.Secondarymembers replicate deletion operations from
the primary.
The TTL index does not guarantee that expired data will be deleted immediately. 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 runsevery 60 seconds. As a result, documents may remain in a
collectionafterthey expire butbeforethe background task runs or completes.
The duration of the removal operation depends on the workload of yourmongodinstance. Therefore, expired data
may exist for some timebeyondthe 60 second period between runs of the background task.
All collections with an index using theexpireAfterSeconds option haveusePowerOf2Sizesenabled. Users
cannot modify this setting. As a result of enablingusePowerOf2Sizes, 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.
Procedures
To enable TTL for a collection, use theensureIndex()method to create a TTL index, as shown in the examples
below.
With the exception of the background thread, a TTL index supports queries in the same way normal indexes do. You
can use TTL indexes to expire documents in one of two ways, either:

time of the documents. Alternately,

Expire Documents after a Certain Number of SecondsTo expire data after a certain number of seconds, create
a TTL index on a eld that holds values of BSON date type or an array of BSON date-typed objectsandspecify a
positive non-zero value in theexpireAfterSeconds eld. A document will expire when the number of seconds
in theexpireAfterSeconds eld has passed since the time specied in its indexed eld.
72
For example, the following operation creates an index on thelog_eventscollection'screatedAteld and spec-
ies theexpireAfterSeconds value of3600to set the expiration time to be one hour after the time specied by
createdAt.
db.log_events.ensureIndex( {::
When adding documents to thelog_eventscollection, set thecreatedAteld to the current time:
72
If the eld 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 specied inexpireAfterSeconds.
5.1. Administration Concepts 199

MongoDB Documentation, Release 2.6.4
db.log_events.insert( {
"createdAt": newDate(),
"logEvent":,
"logMessage":
} )
MongoDB will automatically delete documents from thelog_eventscollection when the document'screatedAt
value
1
is older than the number of seconds specied inexpireAfterSeconds.
See also:
$currentDateoperator
Expire Documents at a Certain Clock TimeTo expire documents at a certain clock time, begin by creating a
TTL index on a eld that holds values of BSON date type or an array of BSON date-typed objectsandspecify an
expireAfterSeconds value of0. For each document in the collection, set the indexed date eld to a value
corresponding to the time the document should expire. If the indexed date eld contains a date in the past, MongoDB
considers the document expired.
For example, the following operation creates an index on thelog_eventscollection'sexpireAteld and species
theexpireAfterSeconds value of0:
db.log_events.ensureIndex( {::
For each document, set the value ofexpireAtto correspond to the time the document should expire. For instance,
the followinginsert()operation adds a document that should expire atJuly 22, 2013 14:00:00 .
db.log_events.insert( {
"expireAt": newDate(July 22, 2013 14:00:00),
"logEvent":,
"logMessage":
} )
MongoDB will automatically delete documents from thelog_eventscollection when the documents'expireAt
value is older than the number of seconds specied inexpireAfterSeconds, i.e.0seconds older in this case. As
such, the data expires at the speciedexpireAtvalue.
5.1.3
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 conguration.
This section describes techniques for optimizing application performance with MongoDB.
Evaluate Performance of Current Operations(page 201)MongoDB provides introspection tools that describe the
query execution process, to allow users to test queries and build more efcient queries.
Use Capped Collections for Fast Writes and Reads(page 201)Outlines a use case forCapped Collections
(page 196) to optimize certain data ingestion work ows.
Optimize Query Performance(page 202)Introduces the use ofprojections(page 57) to reduce the amount of data
MongoDB must set to clients.
Design Notes(page 203)A collection of notes related to the architecture, design, and administration of MongoDB-
based applications.
200 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Evaluate Performance of Current Operations
The following sections describe techniques for evaluating operational performance.
Use the Database Proler to Evaluate Operations Against the Database
MongoDB provides a database proler that shows performance characteristics of each operation against the database.
Use the proler 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, seeDatabase Proling(page 180).
Usedb.currentOp()to EvaluatemongodOperations
Thedb.currentOp()method reports on current operations running on amongodinstance.
Use$explainto Evaluate Query Performance
Theexplain()method returns statistics on a query, and reports the index MongoDB selected to fulll the query, as
well as information about the internal operation of the query.
Example
To useexplain()on a query for documents matching the expression{ a: 1 }, in the collection named
records, use an operation that resembles the following in themongoshell:
db.records.find( { a:
Use Capped Collections for Fast Writes and Reads
Use Capped Collections for Fast Writes
Capped Collections(page 196) are circular, xed-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 les 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$naturaloperator. On a
capped collection, this also returns the documents in the order in which they were written.
Natural orderdoes not use indexes but can be fast for operations when you want to select the rst or last items on disk.
See also:
sort()andlimit().
5.1. Administration Concepts 201

MongoDB Documentation, Release 2.6.4
Optimize Query Performance
Create Indexes to Support Queries
For commonly issued queries, createindexes(page 431). If a query searches multiple elds, create acompound index
(page 440). 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 apostscollection containing blog posts, and if you regularly issue a query that sorts on the
author_nameeld, then you can optimize the query by creating an index on theauthor_nameeld:
db.posts.ensureIndex( { author_name
Indexes also improve efciency on queries that routinely sort on a given eld.
Example
If you regularly issue a query that sorts on thetimestampeld, then you can optimize the query by creating an
index on thetimestampeld:
Creating this index:
db.posts.ensureIndex( { timestamp
Optimizes this query:
db.posts.find().sort( { timestamp1
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 theaggregation pipeline(page 393).
Index keys that are of theBinDatatype are more efciently stored in the index if:

Limit the Number of Query Results to Reduce Network Demand
MongoDBcursorsreturn 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 thelimit()method.
This is typically used in conjunction with sort operations. For example, if you need only 10 results from your query to
thepostscollection, you would issue the following command:
db.posts.find().sort( { timestamp110)
For more information on limiting results, seelimit()
Use Projections to Return Only Necessary Data
When you need only a subset of elds from documents, you can achieve better performance by returning only the
elds you need:
202 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
For example, if in your query to thepostscollection, you need only thetimestamp,title,author, and
abstractelds, you would issue the following command:
db.posts.find( {}, { timestamp abstract:} ).sort( { timestamp1
For more information on using projections, seeLimit Fields to Return from a Query(page 94).
Use$hintto Select a Particular Index
In most cases thequery optimizer(page 61) selects the optimal index for a specic operation; however, you can force
MongoDB to use a specic index using thehint()method. Usehint()to support performance testing, or on
some queries where you must select a eld or eld included in several indexes.
Use the Increment Operator to Perform Operations Server-Side
Use MongoDB's$incoperator to increment or decrement values in documents. The operator increments the value
of the eld on the server side, as an alternative to selecting a document, making simple modications in the client
and then writing the entire document to the server. The$incoperator can also help avoid race conditions, which
would result when two application instances queried for a document, manually incremented a eld, and saved the
entire document back at the same time.
Design Notes
This page details features of MongoDB that may be important to bear in mind when designing your applications.
Schema Considerations
Dynamic SchemaData in MongoDB has adynamic schema.Collectionsdo not enforcedocumentstructure. This
facilitates iterative development and polymorphism. Nevertheless, collections often hold documents with highly ho-
mogeneous structures. SeeData Modeling Concepts(page 133) for more information.
Some operational considerations include:

_idindex, all indexes must be created explicitly;

set.
Avoid importing unmodied 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 sub-documents and nested arrays.
Case Sensitive StringsMongoDB strings are case sensitive. So a search for"joe"will not nd"Joe".
Consider:

http://docs.mongodb.org/manuali , and/or
$toLoweror$toUpperin theaggregation framework(page 391).
5.1. Administration Concepts 203

MongoDB Documentation, Release 2.6.4
Type Sensitive FieldsMongoDB data is stored in the
73
format, a binary encoded serialization of JSON-like
documents. BSON encodes additional type information. See
74
for more information.
Consider the following document which has a eldxwith thestringvalue"123":
{ x
Then the following query which looks for anumbervalue123willnotreturn that document:
db.mycollection.find( { x
General Considerations
By Default, Updates Affect one DocumentTo update multiple documents that meet your query criteria, set the
update multioption totrueor1. See:Update Multiple Documents(page 70).
Prior to MongoDB 2.2, you would specify theupsertandmultioptions in theupdatemethod as positional
boolean options. See: theupdatemethod reference documentation.
BSON Document Size LimitTheBSON Document Size limit is currently set at 16MB per document. If you
require larger documents, useGridFS(page 138).
No Fully Generalized TransactionsMongoDB does not havefully generalized transactions(page 111). 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 modication pattern covers most common uses of transactions in other systems.
Replica Set Considerations
Use an Odd Number of Replica Set MembersReplica sets(page 503) perform consensus elections. To ensure
that elections will proceed successfully, either use an odd number of members, typically three, or else use anarbiter
to ensure an odd number of votes.
Keep Replica Set Members Up-to-DateMongoDB replica sets supportautomatic failover(page 523). It is impor-
tant for your secondaries to be up-to-date. There are various strategies for assessing consistency:
1. Monitoring for MongoDB(page 175) for a detailed discus-
sion of MongoDB's monitoring options.
2.
3. manualfail over, you can congure your secondaries aspriority 0(page 512).
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(page 527).
73
http://docs.mongodb.org/meta-driver/latest/legacy/bson/
74
http://bsonspec.org/#/specication
204 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Sharding Considerations

existing collection, MongoDB imposes a maximum size on those col-
lections 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.
Enforce Unique Keys for
Sharded Collections(page 674).
pre-splitting(page 634) a sharded collection before a massive bulk import.
5.2
The administration tutorials provide specic step-by-step instructions for performing common MongoDB setup, main-
tenance, and conguration operations.
Conguration, Maintenance, and Analysis(page 205)Describes routine management operations, including cong-
uration and performance analysis.
Manage mongod Processes(page 207)Start, congure, and manage runningmongodprocess.
Rotate Log Files(page 214)Archive the current log les and start new ones.
Continue reading fromConguration, Maintenance, and Analysis(page 205) for additional tutorials of funda-
mental MongoDB maintenance procedures.
Backup and Recovery(page 229)Outlines procedures for data backup and restoration withmongodinstances and
deployments.
Backup and Restore with Filesystem Snapshots(page 229)An outline of procedures for creating MongoDB
data set backups using system-level le snapshot tool, such asLVMor native storage appliance tools.
Backup and Restore Sharded Clusters(page 238)Detailed procedures and considerations for backing up
sharded clusters and single shards.
Recover Data after an Unexpected Shutdown(page 246)Recover data from MongoDB data les that were not
properly closed or have an invalid state.
Continue reading fromBackup and Recovery(page 229) for additional tutorials of MongoDB backup and re-
covery procedures.
MongoDB Scripting(page 248)An introduction to the scripting capabilities of themongoshell and the scripting
capabilities embedded in MongoDB instances.
MongoDB Tutorials(page 225)A complete list of tutorials in the MongoDB Manual that address MongoDB opera-
tion and use.
5.2.1
The following tutorials describe routine management operations, including conguration and performance analysis:
Use Database Commands(page 206)The process for running database commands that provide basic database oper-
ations.
5.2. Administration Tutorials 205

MongoDB Documentation, Release 2.6.4
Manage mongod Processes(page 207)Start, congure, and manage runningmongodprocess.
Terminate Running Operations(page 209)Stop in progress MongoDB client operations usingdb.killOp()and
maxTimeMS().
Analyze Performance of Database Operations(page 210)Collect data that introspects the performance of query and
update operations on amongodinstance.
Rotate Log Files(page 214)Archive the current log les and start new ones.
Manage Journaling(page 215)Describes the procedures for conguring and managing MongoDB's journaling sys-
tem which allows MongoDB to provide crash resiliency and durability.
Store a JavaScript Function on the Server(page 217)Describes how to store JavaScript functions on a MongoDB
server.
Upgrade to the Latest Revision of MongoDB(page 218)Introduces the basic process for upgrading a MongoDB de-
ployment between different minor release versions.
Monitor MongoDB With SNMP on Linux(page 221)The SNMP extension, available in MongoDB Enterprise, al-
lows MongoDB to report data into SNMP traps.
Monitor MongoDB Windows with SNMP(page 223)The SNMP extension, available in the Windows build of Mon-
goDB Enterprise, allows MongoDB to report data into SNMP traps.
Troubleshoot SNMP(page 224)Outlines common errors and diagnostic processes useful for deploying MongoDB
Enterprise with SNMP support.
MongoDB Tutorials(page 225)A complete list of tutorials in the MongoDB Manual that address MongoDB opera-
tion and use.
Use Database Commands
The MongoDB command interface provides access to allnon CRUDdatabase operations. Fetching server stats,
initializing a replica set, and running a map-reduce job are all accomplished with commands.
Seehttp://docs.mongodb.org/manualreference/command for list of all commands sorted by function,
andhttp://docs.mongodb.org/manualreference/command for a list of all commands sorted alphabet-
ically.
Database Command Form
You specify a command rst by constructing a standardBSONdocument whose rst key is the name of the command.
For example, specify theisMastercommand using the followingBSONdocument:
{ isMaster:
Issue Commands
Themongoshell provides a helper method for running commands calleddb.runCommand(). The following
operation inmongoruns the above command:
db.runCommand( { isMaster:
Manydriversprovide an equivalent for thedb.runCommand()method. Internally, running commands with
db.runCommand()is equivalent to a special query against the$cmdcollection.
206 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Many common commands have their own shell helpers or wrappers in themongoshell and drivers, such as the
db.isMaster()method in themongoJavaScript shell.
You can use themaxTimeMSoption to specify a time limit for the execution of a command, seeTerminate a Command
(page 210) for more information on operation termination.
adminDatabase Commands
You must run some commands on theadmin database. Normally, these operations resemble the followings:
use admin
db.runCommand( {buildInfo:} )
However, there's also a command helper that automatically runs the command in the context of theadmindatabase:
db._adminCommand( {buildInfo:} )
Command Responses
All commands return, at minimum, a document with anokeld indicating whether the command has succeeded:
{:
Failed commands return theokeld with a value of0.
ManagemongodProcesses
MongoDB runs as a standard program. You can start MongoDB from a command line
by issuing themongodcommand and specifying options. For a list of options, see
http://docs.mongodb.org/manualreference/program/mongod . MongoDB can also run as a
Windows service. For details, seeCongure a Windows Service for MongoDB(page 21). To install MongoDB, see
Install MongoDB(page 5).
The following examples assume the directory containing themongodprocess is in your system paths. Themongod
process is the primary database process that runs on an individual server.mongosprovides a coherent MongoDB
interface equivalent to amongodfrom the perspective of a client. Themongobinary provides the administrative
shell.
This document page discusses themongodprocess; however, some portions of this document may be applicable to
mongosinstances.
See also:
Run-time Database Conguration(page 182),http://docs.mongodb.org/manualreference/program/mongod ,
http://docs.mongodb.org/manualreference/program/mongos , and
http://docs.mongodb.org/manualreference/configuration-options .
StartmongodProcesses
By default, MongoDB stores data in the/data/dbdirectory. On Windows, MongoDB stores data inC:\data\db.
On all platforms, MongoDB listens for connections from clients on port27017.
To start MongoDB using all defaults, issue the following command at the system shell:
5.2. Administration Tutorials 207

MongoDB Documentation, Release 2.6.4
mongod
Specify a Data DirectoryIf you wantmongodto store data les at a pathother than/data/dbyou can specify
adbPath. ThedbPathmust exist before you startmongod. If it does not exist, create the directory and the
permissions so thatmongodcan read and write data to this path. For more information on permissions, see the
security operations documentation.
To specify adbPathformongodto use as a data directory, use the--dbpathoption. The following invocation
will start amongodinstance and store data in the/srv/mongodbpath
mongod --dbpath /srv/mongodb/
Specify a TCP PortOnly a single process can listen for connections on a network interface at a time. If you run
multiplemongodprocesses 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 tomongod, use the--portoption on the command line. The following command startsmongod
listening on port12345:
mongod --port 12345
Use the default port number when possible, to avoid confusion.
Startmongodas a DaemonTo run amongodprocess as a daemon (i.e.fork),andwrite its output to a log le,
use the--forkand--logpathoptions. You must create the log directory; however,mongodwill create the log
le if it does not exist.
The following command startsmongodas a daemon and records log output to/var/log/mongodb.log.
mongod --fork --logpath /var/log/mongodb.log
Additional Conguration OptionsFor an overview of common congurations and common conguration deploy-
ments. congurations for common use cases, seeRun-time Database Conguration(page 182).
StopmongodProcesses
In a clean shutdown amongodcompletes all pending operations, ushes all data to data les, and closes all data les.
Other shutdowns areuncleanand can compromise the validity the data les.
To ensure a clean shutdown, always shutdownmongodinstances using one of the following methods:
UseshutdownServer() Shut down themongodfrom themongoshell using thedb.shutdownServer()
method as follows:
use admin
db.shutdownServer()
Calling the same method from a control script accomplishes the same result.
For systems withauthorizationenabled, users may only issuedb.shutdownServer() when authenticated
to theadmindatabase or via the localhost interface on systems without authentication enabled.
208 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Use--shutdownFrom the Linux command line, shut down themongodusing the--shutdownoption in the
following command:
mongod --shutdown
UseCTRL-CWhen running themongodinstance in interactive mode (i.e. without--fork), issueControl-C
to perform a clean shutdown.
UsekillFrom the Linux command line, shut down a specicmongodinstance using the following command:
kill <mongod process ID>
Warning:Never usekill -9(i.e.SIGKILL) to terminate a mongod instance.
Stop a Replica Set
ProcedureIf themongodis theprimaryin areplica set, the shutdown process for thesemongodinstances has the
following steps:
1. secondariesare.
2. mongodwill return a message that it will not shut down.
You can pass theshutdowncommand atimeoutSecsargument to wait for a secondary to catch up.
3.
to catch up.
4.
Force Replica Set ShutdownIf there is no up-to-date secondary and you want the primary to shut down, issue the
shutdowncommand with theforceargument, as in the followingmongoshell operation:
db.adminCommand({shutdown, force true})
To keep checking the secondaries for a specied number of seconds if none are immediately up-to-date, issue
shutdownwith thetimeoutSecsargument. MongoDB will keep checking the secondaries for the specied
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 issuesshutdownwithtimeoutSecsset to5:
db.adminCommand({shutdown, timeoutSecs})
Alternately you can use thetimeoutSecsargument with thedb.shutdownServer() method:
db.shutdownServer({timeoutSecs})
Terminate Running Operations
Overview
MongoDB provides two facilitates to terminate running operations:maxTimeMS()anddb.killOp(). Use these
operations as needed to control the behavior of operations in a MongoDB deployment.
5.2. Administration Tutorials 209

MongoDB Documentation, Release 2.6.4
Available Procedures
maxTimeMSNew in version 2.6.
ThemaxTimeMS()method sets a time limit for an operation. When the operation reaches the specied time limit,
MongoDB interrupts the operation at the nextinterrupt point.
Terminate a QueryFrom themongoshell, use the following method to set a time limit of 30 milliseconds for this
query:
db.location.find( {::,
"$options":30)
Terminate a CommandConsider a potentially long running operation usingdistinctto return each dis-
tinct``collection`` eld that has acitykey:
db.runCommand( { distinct:,
key:
You can add themaxTimeMSeld to the command document to set a time limit of 30 milliseconds for the operation:
db.runCommand( { distinct:,
key:,
maxTimeMS:
db.getLastError()anddb.getLastErrorObj() will return errors for interrupted options:
{,
"connectionId",
"err",
"ok"
killOpThedb.killOp()method interrupts a running operation at the nextinterrupt point.db.killOp()
identies the target operation by operation ID.
db.killOp(<opId>)
Related
To return a list of running operations seedb.currentOp().
Analyze Performance of Database Operations
The database proler collects ne grained data about MongoDB write operations, cursors, database commands on
a runningmongodinstance. You can enable proling on a per-database or per-instance basis. Theproling level
(page 211) is also congurable when enabling proling.
The database proler writes all the data it collects to thesystem.profile(page 271) collection, which is acapped
collection(page 196). SeeDatabase Proler Output(page 271) for overview of the data in thesystem.profile
(page 271) documents created by the proler.
This document outlines a number of key administration options for the database proler. For additional related infor-
mation, consider the following resources:
Database Proler Output(page 271)
210 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Profile Command
http://docs.mongodb.org/manualreference/method/db.currentOp
Proling Levels
The following proling levels are available:
0- the proler is off, does not collect any data.mongodalways writes operations longer than the
slowOpThresholdMsthreshold to its log.
1- collects proling data for slow operations only. By default slow operations are those slower than 100
milliseconds.
You can modify the threshold for slow operations with theslowOpThresholdMs runtime option or the
setParametercommand. See theSpecify the Threshold for Slow Operations(page 211) section for more
information.
2- collects proling data for all database operations.
Enable Database Proling and Set the Proling Level
You can enable database proling from themongoshell or through a driver using theprofilecommand. This
section will describe how to do so from themongoshell. See yourdriver documentation if you want to
control the proler from within your application.
When you enable proling, you also set theproling level(page 211). The proler records data in the
system.profile(page 271) collection. MongoDB creates thesystem.profile(page 271) collection in a
database after you enable proling for that database.
To enable proling and set the proling level, use thedb.setProfilingLevel() helper in themongoshell,
passing the proling level as a parameter. For example, to enable proling for all database operations, consider the
following operation in themongoshell:
db.setProfilingLevel(2)
The shell returns a document showing thepreviouslevel of proling. The"ok" : 1key-value pair indicates the
operation succeeded:
{,,
To verify the new setting, see theCheck Proling Level(page 212) section.
Specify the Threshold for Slow OperationsThe threshold for slow operations applies to the entiremongodin-
stance. When you change the threshold, you change it for all databases on the instance.
Important:Changing the slow operation threshold for the database proler also affects the proling subsystem's
slow operation threshold for the entiremongodinstance. Always set the threshold to the highest useful value.
By default the slow operation threshold is 100 milliseconds. Databases with a proling level of1will log operations
slower than 100 milliseconds.
To change the threshold, pass two parameters to thedb.setProfilingLevel() helper in themongoshell. The
rst parameter sets the proling level for the current database, and the second sets the default slow operation threshold
for the entiremongodinstance.
5.2. Administration Tutorials 211

MongoDB Documentation, Release 2.6.4
For example, the following command sets the proling level for the current database to0, which disables proling,
and sets the slow-operation threshold for themongodinstance to 20 milliseconds. Any database on the instance with
a proling level of1will use this threshold:
db.setProfilingLevel(0,20)
Check Proling LevelTo view theproling level(page 211), issue the following from themongoshell:
db.getProfilingStatus()
The shell returns a document similar to the following:
{,
Thewaseld indicates the current level of proling.
Theslowmseld 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 proling level is1. This document
returns the proling level in thewaseld. For an explanation of proling levels, seeProling Levels(page 211).
To return only the proling level, use thedb.getProfilingLevel() helper in themongoas in the following:
db.getProfilingLevel()
Disable ProlingTo disable proling, use the following helper in themongoshell:
db.setProfilingLevel(0)
Enable Proling for an EntiremongodInstanceFor development purposes in testing environments, you can
enable database proling for an entiremongodinstance. The proling level applies to all databases provided by the
mongodinstance.
To enable proling for amongodinstance, pass the following parameters tomongodat startup or within the
configuration file:
mongod --profile=1 --slowms=15
This sets the proling level to1, which collects proling data for slow operations only, and denes slow operations as
those that last longer than15milliseconds.
See also:
modeandslowOpThresholdMs.
Database Proling and ShardingYoucannotenable proling on amongosinstance. To enable proling in a
shard cluster, you must enable proling for eachmongodinstance in the cluster.
View Proler Data
The database proler logs information about database operations in thesystem.profile(page 271) collection.
To view proling information, query thesystem.profile(page 271) collection. To view example queries, see
Proler Overhead(page 213)
For an explanation of the output data, seeDatabase Proler Output(page 271).
212 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Example Proler Data QueriesThis section displays example queries to thesystem.profile(page 271) col-
lection. For an explanation of the query output, seeDatabase Proler Output(page 271).
To return the most recent 10 log entries in thesystem.profile(page 271) collection, run a query similar to the
following:
db.system.profile.find().limit(10).sort( { ts1
To return all operations except command operations ($cmd), run a query similar to the following:
db.system.profile.find( { op:
To return operations for a particular collection, run a query similar to the following. This example returns operations
in themydbdatabase'stestcollection:
db.system.profile.find( { ns
To return operations slower than5milliseconds, run a query similar to the following:
db.system.profile.find( { millis
To return information from a certain time range, run a query similar to the following:
db.system.profile.find(
{
ts
$gt newISODate("2012-12-09T03:00:00Z") ,
$lt newISODate("2012-12-09T03:40:00Z")
}
}
).pretty()
The following example looks at the time range, suppresses theusereld 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 newISODate("2011-07-12T03:00:00Z") ,
$lt newISODate("2011-07-12T03:40:00Z")
}
},
{ user
).sort( { millis1
Show the Five Most Recent EventsOn a database that has proling enabled, theshow profilehelper in the
mongoshell displays the 5 most recent operations that took at least 1 millisecond to execute. Issueshow profile
from themongoshell, as follows:
show profile
Proler Overhead
When enabled, proling has a minor effect on performance. Thesystem.profile(page 271) collection is a
capped collectionwith a default size of 1 megabyte. A collection of this size can typically store several thousand
prole documents, but some application may use more or less proling data per operation.
To change the size of thesystem.profile(page 271) collection, you must:
5.2. Administration Tutorials 213

MongoDB Documentation, Release 2.6.4
1.
2. system.profile(page 271) collection.
3. system.profile(page 271) collection.
4.
For example, to create a newsystem.profile(page 271) collections that's4000000bytes, use the following
sequence of operations in themongoshell:
db.setProfilingLevel(0)
db.system.profile.drop()
db.createCollection(, { capped: true, size:4000000
db.setProfilingLevel(1)
Change Size ofsystem.profileCollection
To change the size of thesystem.profile(page 271) collection on asecondary, 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, seePerform Maintenance on Replica Set Members(page 572).
Rotate Log Files
Overview
Log rotation using MongoDB's standard approach archives the current log le and starts a new one. To do this, the
mongodormongosinstance renames the current log le by appending a UTC (GMT) timestamp to the lename, in
ISODateformat. It then opens a new log le, closes the old log le, and sends all new log entries to the new log le.
MongoDB's standard approach to log rotation only rotates logs in response to thelogRotatecommand, or when
themongodormongosprocess receives aSIGUSR1signal from the operating system.
Alternately, you may congure mongod to send log data tosyslog. In this case, you can take advantage of alternate
logrotation tools.
See also:
For information on logging, see theProcess Logging(page 178) section.
Log Rotation With MongoDB
The following steps create and rotate a log le:
1. mongodwith verbose logging, with appending enabled, and with the following log le:
mongod -v --logpath /var/log/mongodb/server1.log --logappend
2.
ls /var/log/mongodb/server1.log *
For results, you get:
214 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
server1.log
3. oneof the following methods.
mongoshell, issue thelogRotatecommand from theadmindatabase:
use admin
db.runCommand( { logRotate
This is the only available method to rotate log les on Windows systems.

killSIGUSR1mongod process id>
4.
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 exactly11:30 pmonNovember 24th, 2011
UTC, which is the local time offset by the local time zone. The original log le is the one with the timestamp.
The new log isserver1.logle.
If you issue a secondlogRotatecommand an hour later, then an additional le would appear when listing
matching les, 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 theserver1.log.2011-11-24T23-30-00 le created earlier, while
server1.log.2011-11-25T00-30-00 is the previousserver1.logle, renamed.server1.log
is a new, empty le that receives all new log output.
Syslog Log Rotation
New in version 2.2.
To congure mongod to send log data to syslog rather than writing log data to a le, use the following procedure.
1. mongodwith thesyslogFacilityoption.
2.
Important:You cannot usesyslogFacilitywithsystemLog.path.
Manage Journaling
MongoDB useswrite ahead loggingto an on-diskjournalto guaranteewrite operation(page 67) durability and to
provide crash resiliency. Before applying a change to the data les, 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 les, MongoDB can re-apply the write operation and maintain a consistent state.
Withouta journal, ifmongodexits unexpectedly, you must assume your data is in an inconsistent state, and you must
run eitherrepair(page 246) or, preferably,resync(page 575) from a clean member of the replica set.
5.2. Administration Tutorials 215

MongoDB Documentation, Release 2.6.4
With journaling enabled, ifmongodstops 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. SeecommitIntervalMsfor 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, seeStorage Views used in Journaling(page 275).
Important:Changed in version 2.0: For 64-bit builds ofmongod, journaling is enabled by default. For other
platforms, seestorage.journal.enabled .
Procedures
Enable JournalingChanged in version 2.0: For 64-bit builds ofmongod, journaling is enabled by default.
To enable journaling, startmongodwith the--journalcommand line option.
If no journal les exist, whenmongodstarts, it must preallocate new journal les. During this operation, themongod
is not listening for connections until preallocation completes: for some systems this may take a several minutes.
During this period your applications and themongoshell are not available.
Disable Journaling
Warning:Do not disable journaling on production systems. If yourmongodinstance 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 unaffectedreplica setmember or backup, as described inrepair(page 246).
To disable journaling, startmongodwith the--nojournalcommand line option.
Get Commit AcknowledgmentYou can get commit acknowledgment with theWrite Concern(page 72) and thej
option. For details, seeWrite Concern Reference(page 118).
Avoid Preallocation LagTo avoidpreallocation lag(page 275), you can preallocate les in the journal directory by
copying them from another instance ofmongod.
Preallocated les do not contain data. It is safe to later remove them. But if you restartmongodwith journaling,
mongodwill create them again.
Example
The following sequence preallocates journal les for an instance ofmongodrunning on port27017with a database
path of/data/db.
For demonstration purposes, the sequence starts by creating a set of journal les in the usual way.
1.
mkdir ~/tmpDbpath
2. mongodinstance that uses the temporary directory:
mongod --port 10000 --dbpath ~/tmpDbpath --journal
3. mongodhas the les, press CONTROL+C to stop the
mongodinstance:
216 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
[initandlisten] forconnections on port 10000
4. mongodby moving the journal les from the data directory of
the existing instance to the data directory of the new instance:
mv ~/tmpDbpath/journal /data/db/
5. mongodinstance:
mongod --port 27017 --dbpath /data/db --journal
Monitor Journal StatusUse the following commands and methods to monitor journal status:
serverStatus
TheserverStatuscommand returns database status information that is useful for assessing performance.
journalLatencyTest
UsejournalLatencyTest 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 les.
ThejournalLatencyTest 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 IntervalChanged in version 2.0.
You can set the group commit interval using the--journalCommitInterval command line option. The allowed
range is2to300milliseconds.
Lower values increase the durability of the journal at the expense of disk performance.
Recover Data After Unexpected ShutdownOn a restart after a crash, MongoDB replays all journal les in the
journal directory before the server becomes available. If MongoDB must replay journal les,mongodnotes these
events in the log output.
There is no reason to runrepairDatabasein 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 namedsystem.jsthat can store JavaScript functions for reuse.
To store a function, you can use thedb.collection.save() , as in the following example:
5.2. Administration Tutorials 217

MongoDB Documentation, Release 2.6.4
db.system.js.save(
{
_id
value function(x, y){returnx
}
);
_ideld holds the name of the function and is unique per database.
valueeld holds the function denition
Once you save a function in thesystem.jscollection, you can use the function from any JavaScript context (e.g.
evalcommand or themongoshell methoddb.eval(),$whereoperator,mapReduceormongoshell method
db.collection.mapReduce() ).
Consider the following example from themongoshell that rst saves a function namedechoFunctionto the
system.jscollection and calls the function usingdb.eval()method:
db.system.js.save(
{ _id:,
value function(x) {returnx; }
}
)
db.eval(
See
New in version 2.1: In themongoshell, you can usedb.loadServerScripts() to load all the scripts saved in
thesystem.jscollection 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,);
Upgrade to the Latest Revision of MongoDB
Revisions provide security patches, bug xes, 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 theMongoDB version
number(page 808) indicates the revision.
Before Upgrading
MongoDB Backup Methods(page 172).

goDB release:
The release notes, located atRelease Notes(page 725).
The documentation for your driver. Seehttp://docs.mongodb.org/manualapplications/drivers .
replica sets, plan the upgrade during a predened maintenance window.
218 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
stagingenviron-
ment that reproduces your production environment, to ensure that your production conguration is compatible
with all changes.
Upgrade Procedure
Important:Always backup all of your data before upgrading MongoDB.
Upgrade eachmongodandmongosbinary separately, using the procedure described here. When upgrading a binary,
use the procedureUpgrade a MongoDB Instance(page 219).
Follow this upgrade procedure:
1. drivers. To upgrade, see the
documentation for your driver.
2. Upgrade Sharded Clusters(page 220).
3. Upgrade a MongoDB Instance(page 219).
4. Upgrade Replica Sets(page 220).
Upgrade a MongoDB Instance
To upgrade amongodormongosinstance, use one of the following approaches:

ages. This is the preferred approach. SeeInstall MongoDB(page 5).
Replace the Existing Binaries
(page 219).
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 ofcial MongoDB packages, as described
inInstall MongoDB(page 5).
To upgrade amongodormongosinstance by replacing the existing binaries:
1.
75
and store the
binaries in a temporary location. The binaries download as compressed les that uncompress to the directory
structure used by the MongoDB installation.
2.
3.
4.
75
http://downloads.mongodb.org/
5.2. Administration Tutorials 219

MongoDB Documentation, Release 2.6.4
Upgrade Sharded Clusters
To upgrade a sharded cluster:
1. Disable the Balancer(page 661).
2. mongosinstance by following the instructions below inUpgrade a MongoDB Instance
(page 219). You can upgrade themongosinstances in any order.
3. mongodcong server(page 616) individually starting with the last cong server listed in your
mongos --configdbstring and working backward. To keep the cluster online, make sure at least one cong
server is always running. For each cong server upgrade, follow the instructions below inUpgrade a MongoDB
Instance(page 219)
Example
Given the following cong string:
mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019
You would upgrade the cong servers in the following order:
(a)
(b)
(c)
4.
Upgrade Replica Sets
(page 220).
Upgrade a MongoDB
Instance(page 219).
5. Enable the Balancer(page 661).
Upgrade Replica Sets
To upgrade a replica set, upgrade each member individually, starting with thesecondariesand nishing with the
primary. Plan the upgrade during a predened maintenance window.
Upgrade SecondariesUpgrade each secondary separately as follows:
1. mongodbinary by following the instructions below inUpgrade a MongoDB Instance
(page 219).
2. SECONDARYstate before upgrading the
next instance. To check the member's state, issuers.status()in themongoshell.
The secondary may briey go intoSTARTUP2orRECOVERING. This is normal. Make sure to wait for the
secondary to fully recover toSECONDARYbefore you continue the upgrade.
Upgrade the Primary
1. failover(page 523) procedure. Using one of the following:
rs.stepDown()helper in themongoshell.
220 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
replSetStepDowndatabase command.
During failover, the set cannot accept writes. Typically this takes 10-20 seconds. Plan the upgrade during a
predened maintenance window.
Note:Stepping down the primary is preferable to directlyshutting downthe primary. Stepping down expedites
the failover procedure.
2. rs.status()method from themongoshell until you see that
another member has assumed thePRIMARYstate.
3. Upgrade a
MongoDB Instance(page 219).
Monitor MongoDB With SNMP on Linux
New in version 2.2.
Enterprise Feature
SNMP is only available in
76
.
Overview
MongoDB Enterprise can report system information into SNMP traps, to support centralized data collection and
aggregation. This procedure explains the setup and conguration of amongodinstance as an SNMP subagent, as
well as initializing and testing of SNMP support with MongoDB Enterprise.
See also:
Troubleshoot SNMP(page 224) andMonitor MongoDB Windows with SNMP(page 223) for complete instructions on
using MongoDB with SNMP on Windows systems.
Considerations
Onlymongodinstances provide SNMP support.mongosand the other MongoDB binaries do not support SNMP.
Conguration Files
Changed in version 2.6.
MongoDB Enterprise contains the following conguration les to support SNMP:
MONGOD-MIB.txt:
The management information base (MIB) le that denes MongoDB's SNMP output.
mongod.conf.subagent:
The conguration le to runmongodas the SNMP subagent. This le sets SNMP run-time conguration
options, including theAgentXsocket to connect to the SNMP master.
76
http://www.mongodb.com/products/mongodb-enterprise
5.2. Administration Tutorials 221

MongoDB Documentation, Release 2.6.4
mongod.conf.master:
The conguration le to runmongodas the SNMP master. This le sets SNMP run-time conguration options.
Procedure
Step 1: Copy conguration les.Use the following sequence of commands to move the SNMP conguration les
to the SNMP service conguration directory.
First, create the SNMP conguration directory if needed and then, from the installation directory, copy the congura-
tion les to the SNMP service conguration 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 conguration lename is tool-dependent. For example, when usingnet-snmpthe conguration le is
snmpd.conf.
By default SNMP uses UNIX domain for communication between the agent (i.e.snmpdor the master) and sub-agent
(i.e. MongoDB).
Ensure that theagentXAddressspecied in the SNMP conguration le for MongoDB matches the
agentXAddressin the SNMP master conguration le.
Step 2: Start MongoDB.Startmongodwith thesnmp-subagentto send data to the SNMP master.
mongod --snmp-subagent
Step 3: Conrm SNMP data retrieval.Usesnmpwalkto collect data frommongod:
Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.
Install the
77
package to access thesnmpwalkclient.net-snmpprovides thesnmpwalkSNMP 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 dened by the SNMP master,notthe primaryportused bymongodfor client communi-
cation.
Optional: Run MongoDB as SNMP Master
You can runmongodwith thesnmp-masteroption for testing purposes. To do this, use the SNMP master congu-
ration le instead of the subagent conguration le. From the directory containing the unpacked MongoDB installation
les:
cp mongod.conf.master /etc/snmp/mongod.conf
Additionally, startmongodwith thesnmp-masteroption, as in the following:
mongod --snmp-master
77
http://www.net-snmp.org/
222 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Monitor MongoDB Windows with SNMP
New in version 2.6.
Enterprise Feature
SNMP is only available in
78
.
Overview
MongoDB Enterprise can report system information into SNMP traps, to support centralized data collection and
aggregation. This procedure explains the setup and conguration of amongod.exeinstance as an SNMP subagent,
as well as initializing and testing of SNMP support with MongoDB Enterprise.
See also:
Monitor MongoDB With SNMP on Linux(page 221) andTroubleshoot SNMP(page 224) for more information.
Considerations
Onlymongod.exeinstances provide SNMP support.mongos.exeand the other MongoDB binaries do not support
SNMP.
Conguration Files
Changed in version 2.6.
MongoDB Enterprise contains the following conguration les to support SNMP:
MONGOD-MIB.txt:
The management information base (MIB) le that denes MongoDB's SNMP output.
mongod.conf.subagent:
The conguration le to runmongod.exeas the SNMP subagent. This le sets SNMP run-time conguration
options, including theAgentXsocket to connect to the SNMP master.
mongod.conf.master:
The conguration le to runmongod.exeas the SNMP master. This le sets SNMP run-time conguration
options.
Procedure
Step 1: Copy conguration les.Use the following sequence of commands to move the SNMP conguration les
to the SNMP service conguration directory.
First, create the SNMP conguration directory if needed and then, from the installation directory, copy the congura-
tion les to the SNMP service conguration 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
78
http://www.mongodb.com/products/mongodb-enterprise
5.2. Administration Tutorials 223

MongoDB Documentation, Release 2.6.4
The conguration lename is tool-dependent. For example, when usingnet-snmpthe conguration le is
snmpd.conf.
Edit the conguration le to ensure that the communication between the agent (i.e.snmpdor the master) and sub-
agent (i.e. MongoDB) uses TCP.
Ensure that theagentXAddressspecied in the SNMP conguration le for MongoDB matches the
agentXAddressin the SNMP master conguration le.
Step 2: Start MongoDB.Startmongod.exewith thesnmp-subagentto send data to the SNMP master.
mongod.exe --snmp-subagent
Step 3: Conrm SNMP data retrieval.Usesnmpwalkto collect data frommongod.exe:
Connect an SNMP client to verify the ability to collect SNMP data from MongoDB.
Install the
79
package to access thesnmpwalkclient.net-snmpprovides thesnmpwalkSNMP 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 dened by the SNMP master,notthe primaryportused bymongod.exefor client
communication.
Optional: Run MongoDB as SNMP Master
You can runmongod.exewith thesnmp-masteroption for testing purposes. To do this, use the SNMP master
conguration le instead of the subagent conguration le. From the directory containing the unpacked MongoDB
installation les:
copy mongod.conf.master C:\snmp\etc\config\mongod.conf
Additionally, startmongod.exewith thesnmp-masteroption, 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 identies common problems you may encounter when deploying MongoDB Enterprise
with SNMP as well as possible solutions for these issues.
SeeMonitor MongoDB With SNMP on Linux(page 221) andMonitor MongoDB Windows with SNMP(page 223) for
complete installation instructions.
79
http://www.net-snmp.org/
224 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Issues
Failed to ConnectThe following in themongodlogle:
Warning: Failed to connect to the agentx master agent
AgentX is the SNMP agent extensibility protocol dened in Internet
80
. It explains how to dene 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.
1.
2.
socket denition is the same between the two.
3.
mongodhas appropriate permissions to open a UNIX domain socket.
Error Parsing Command LineOne 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
mongodbinaries that are not part of the Enterprise Edition produce this error.Install the Enterprise Edition(page 24)
and attempt to startmongodagain.
Other MongoDB binaries, includingmongoswill produce this error if you attempt to star them withsnmp-master
orsnmp-subagent. Onlymongodsupports SNMP.
Error StartingSNMPAgentThe following line in the log le indicates thatmongodcannot read the
mongod.confle:
[SNMPAgent] warning: error starting SNMPAgent as master err:1
If running on Linux, ensuremongod.confexists in the/etc/snmpdirectory, and ensure that themongodUNIX
user has permission to read themongod.confle.
If running on Windows, ensuremongod.confexists inC:\snmp\etc\config.
MongoDB Tutorials
This page lists the tutorials available as part of theMongoDB Manual. In addition to these documents, you can refer
to the introductoryMongoDB Tutorial(page 43). If there is a process or pattern that you would like to see included
here, please open a
81
.
Getting Started
Install MongoDB on Linux Systems(page 14)
Install MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux(page 6)
80
http://www.ietf.org/rfc/rfc2741.txt
81
https://jira.mongodb.org/browse/DOCS
5.2. Administration Tutorials 225

MongoDB Documentation, Release 2.6.4
Install MongoDB on Debian(page 12)
Install MongoDB on Ubuntu(page 9)
Install MongoDB on OS X(page 16)
Install MongoDB on Windows(page 19)
Getting Started with MongoDB(page 43)
Generate Test Data(page 47)
Administration
Replica Sets
Deploy a Replica Set(page 545)
Deploy Replica Set and Congure Authentication and Authorization(page 313)
Convert a Standalone to a Replica Set(page 556)
Add Members to a Replica Set(page 557)
Remove Members from Replica Set(page 560)
Replace a Replica Set Member(page 561)
Adjust Priority for Replica Set Member(page 562)
Resync a Member of a Replica Set(page 575)
Deploy a Geographically Redundant Replica Set(page 550)
Change the Size of the Oplog(page 570)
Force a Member to Become Primary(page 573)
Change Hostnames in a Replica Set(page 584)
Add an Arbiter to Replica Set(page 555)
Convert a Secondary to an Arbiter(page 568)
Congure a Secondary's Sync Target(page 587)
Congure a Delayed Replica Set Member(page 566)
Congure a Hidden Replica Set Member(page 565)
Congure Non-Voting Replica Set Member(page 567)
Prevent Secondary from Becoming Primary(page 563)
Congure Replica Set Tag Sets(page 576)
Manage Chained Replication(page 583)
Recongure a Replica Set with Unavailable Members(page 580)
Recover Data after an Unexpected Shutdown(page 246)
Troubleshoot Replica Sets(page 588)
226 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Sharding
Deploy a Sharded Cluster(page 635)
Convert a Replica Set to a Replicated Sharded Cluster(page 643)
Add Shards to a Cluster(page 642)
Remove Shards from an Existing Sharded Cluster(page 663)
Deploy Three Cong Servers for Production Deployments(page 643)
Migrate Cong Servers with the Same Hostname(page 652)
Migrate Cong Servers with Different Hostnames(page 652)
Replace Disabled Cong Server(page 653)
Migrate a Sharded Cluster to Different Hardware(page 654)
Backup Cluster Metadata(page 657)
Backup a Small Sharded Cluster with mongodump(page 238)
Backup a Sharded Cluster with Filesystem Snapshots(page 239)
Backup a Sharded Cluster with Database Dumps(page 241)
Restore a Single Shard(page 243)
Restore a Sharded Cluster(page 244)
Schedule Backup Window for Sharded Clusters(page 243)
Manage Shard Tags(page 672)
Basic Operations
Use Database Commands(page 206)
Recover Data after an Unexpected Shutdown(page 246)
Expire Data from Collections by Setting TTL(page 198)
Analyze Performance of Database Operations(page 210)
Rotate Log Files(page 214)
Build Old Style Indexes(page 471)
Manage mongod Processes(page 207)
Back Up and Restore with MongoDB Tools(page 234)
Backup and Restore with Filesystem Snapshots(page 229)
Security
Congure Linux iptables Firewall for MongoDB(page 297)
Congure Windows netsh Firewall for MongoDB(page 300)
Enable Client Access Control(page 317)
Create a User Administrator(page 343)
Add a User to a Database(page 344)
Create a Role(page 347)
5.2. Administration Tutorials 227

MongoDB Documentation, Release 2.6.4
Modify a User's Access(page 352)
View Roles(page 353)
Generate a Key File(page 338)
Congure MongoDB with Kerberos Authentication on Linux(page 331)
Create a Vulnerability Report(page 359)
Development Patterns
Perform Two Phase Commits(page 102)
Isolate Sequence of Operations(page 111)
Create an Auto-Incrementing Sequence Field(page 113)
Enforce Unique Keys for Sharded Collections(page 674)
Aggregation Examples(page 403)
Model Data to Support Keyword Search(page 155)
Limit Number of Elements in an Array after an Update(page 116)
Perform Incremental Map-Reduce(page 413)
Troubleshoot the Map Function(page 415)
Troubleshoot the Reduce Function(page 416)
Store a JavaScript Function on the Server(page 217)
Text Search Patterns
Create a text Index(page 486)
Specify a Language for Text Index(page 487)
Specify Name for text Index(page 489)
Control Search Results with Weights(page 490)
Limit the Number of Entries Scanned(page 491)
Data Modeling Patterns
Model One-to-One Relationships with Embedded Documents(page 140)
Model One-to-Many Relationships with Embedded Documents(page 141)
Model One-to-Many Relationships with Document References(page 143)
Model Data for Atomic Operations(page 154)
Model Tree Structures with Parent References(page 146)
Model Tree Structures with Child References(page 148)
Model Tree Structures with Materialized Paths(page 151)
Model Tree Structures with Nested Sets(page 153)
228 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
5.2.2
The following tutorials describe backup and restoration for amongodinstance:
Backup and Restore with Filesystem Snapshots(page 229)An outline of procedures for creating MongoDB data set
backups using system-level le snapshot tool, such asLVMor native storage appliance tools.
Restore a Replica Set from MongoDB Backups(page 232)Describes procedure for restoring a replica set from an
archived backup such as amongodumpor
82
le.
Back Up and Restore with MongoDB Tools(page 234)The procedure for writing the contents of a database to a
BSON (i.e. binary) dump le for backing up MongoDB databases.
Backup and Restore Sharded Clusters(page 238)Detailed procedures and considerations for backing up sharded
clusters and single shards.
Recover Data after an Unexpected Shutdown(page 246)Recover data from MongoDB data les that were not prop-
erly closed or have an invalid state.
Backup and Restore with Filesystem Snapshots
This document describes a procedure for creating backups of MongoDB systems using system-level tools, such as
LVMor storage appliance, as well as the corresponding restoration strategies.
These lesystem snapshots, or block-level backup methods use system level tools to create copies of the device that
holds MongoDB's data les. These methods complete quickly and work reliably, but require more system congura-
tion outside of MongoDB.
See also:
MongoDB Backup Methods(page 172) andBack Up and Restore with MongoDB Tools(page 234).
Snapshots Overview
Snapshots work by creating pointers between the live data and a special snapshot volume. These pointers are the-
oretically 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 modied data.
After making the snapshot, you mount the snapshot image on your le system and copy data from the snapshot. The
resulting backup contains a full copy of all data.
Snapshots have the following limitations:

need to be fully written to disk: either to thejournalor to data les.
If all writes are not on disk when the backup occurs, the backup will not reect these changes. If writes arein
progresswhen the backup occurs, the data les will reect an inconsistent state. Withjournalingall data-le
states resulting from in-progress writes are recoverable; without journaling you must ush 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 journalmustreside on the same volume as the data.

isolating your MongoDB data les, journal (if applicable), and conguration on one logical disk that doesn't
contain any other data.
82
https://mms.mongodb.com/?pk_campaign=mongodb-docs-admin-tutorials
5.2. Administration Tutorials 229

MongoDB Documentation, Release 2.6.4
Alternately, store all MongoDB data les on a dedicated device so that you can make backups without duplicat-
ing extraneous data.

provide any capacity for capturing incremental backups.
Snapshots With JournalingIf yourmongodinstance has journaling enabled, then you can use any kind of le
system or volume/block level snapshot tool to create backups.
If you manage your own infrastructure on a Linux-based system, congure your system withLVMto provide your disk
packages and provide snapshot capability. You can also use LVM-based setupswithina cloud/virtualized environment.
Note:RunningLVMprovides additional exibility and enables the possibility of using snapshots to back up Mon-
goDB.
Snapshots with Amazon EBS in a RAID 10 CongurationIf your deployment depends on Amazon's Elastic
Block Storage (EBS) with RAID congured 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:

If you choose this option seeCreate Backups on Instances that do not have Journaling Enabled(page 232).
LVMto run and hold your MongoDB data les on top of the RAID within your system.
If you choose this option, perform the LVM backup operation described inCreate a Snapshot(page 230).
Backup and Restore Using LVM on a Linux System
This section provides an overview of a simple backup process usingLVMon a Linux system. While the tools, com-
mands, 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 specic requirements and factors unique to specic environments.
Create a SnapshotTo create a snapshot withLVM, issue a command as root in the following format:
lvcreate --size 100M --snapshot --name mdb-snap01 /dev/vg0/mongodb
This command creates anLVMsnapshot (with the--snapshotoption) namedmdb-snap01of themongodb
volume in thevg0volume group.
This example creates a snapshot namedmdb-snap01located athttp://docs.mongodb.org/manualdev/vg0/mdb-snap01 .
The location and paths to your systems volume groups and devices may vary slightly depending on your operating
system'sLVMconguration.
The snapshot has a cap of at 100 megabytes, because of the parameter--size 100M. This size does not
reect the total amount of the data on the disk, but rather the quantity of differences between the current
state ofhttp://docs.mongodb.org/manualdev/vg0/mongodb and the creation of the snapshot (i.e.
http://docs.mongodb.org/manualdev/vg0/mdb-snap01 .)
230 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
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 SnapshotAfter 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 ofine. Alternatively, take a block level copy of the
snapshot image, such as with the following procedure:
umount /dev/vg0/mdb-snap01
ddif=/dev/vg0/mdb-snap01 | gzip > mdb-snap01.gz
The above command sequence does the following:
http://docs.mongodb.org/manualdev/vg0/mdb-snap01 device is not mounted.
Never take a block level copy of a lesystem or lesystem snapshot that is mounted.
ddcommand and compresses the result in a
gzipped le in the current working directory.
Warning:This command will create a largegzle in your current working directory. Make sure that you
run this command in a le system that has enough free space.
Restore a SnapshotTo restore a snapshot created with the above method, issue the following sequence of com-
mands:
lvcreate --size 1G --name mdb-new vg0
gzip -d -c mdb-snap01.gz | dd=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb
The above sequence does the following:
mdb-new, in thehttp://docs.mongodb.org/manualdev/vg0
volume group. The path to the new device will behttp://docs.mongodb.org/manualdev/vg0/mdb-new .
Warning:This volume will have a maximum size of 1 gigabyte. The original le system must have had a
total size of 1 gigabyte or smaller, or else the restoration will fail.
Change1Gto your desired volume size.
mdb-snap01.gzinto themdb-newdisk image.
mdb-newdisk image to the/srv/mongodbdirectory. Modify the mount point to correspond to
your MongoDB data le location, or other location as needed.
Note:The restored snapshot will have a stalemongod.lockle. If you do not remove this le from the snap-
shot, and MongoDB may assume that the stale lock le indicates an unclean shutdown. If you're running with
storage.journal.enabled enabled, and youdo notusedb.fsyncLock(), you do not need to remove
themongod.lockle. If you usedb.fsyncLock()you will need to remove the lock.
5.2. Administration Tutorials 231

MongoDB Documentation, Release 2.6.4
Restore Directly from a SnapshotTo restore a backup without writing to a compressedgzle, use the following
sequence of commands:
umount /dev/vg0/mdb-snap01
lvcreate --size 1G --name mdb-new vg0
ddif=/dev/vg0/mdb-snap01=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb
Remote Backup StorageYou can implement off-system backups using thecombined process(page 232) 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
ddif=/dev/vg0/mdb-snap01 | ssh [email protected] gzip > /opt/backup/mdb-snap01.gz
lvcreate --size 1G --name mdb-new vg0
ssh [email protected] gzip -d -c /opt/backup/mdb-snap01.gz | dd=/dev/vg0/mdb-new
mount /dev/vg0/mdb-new /srv/mongodb
Create Backups on Instances that do not have Journaling Enabled
If yourmongodinstance 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 ush all writes to
disk and lock the database to prevent writes during the backup process. If you have areplica setconguration, then
for your backup use asecondarywhich is not receiving reads (i.e.hidden member).
Step 1: Flush writes to disk and lock the database to prevent further writes.To ush writes to disk and to lock
the database, issue thedb.fsyncLock()method in themongoshell:
db.fsyncLock();
Step 2: Perform the backup operation described inCreate a Snapshot.
Step 3: After the snapshot completes, unlock the database.To unlock the database after the snapshot has com-
pleted, use the following command in themongoshell:
db.fsyncUnlock();
Changed in version 2.2: When used in combination withfsyncordb.fsyncLock(),mongodmay block some
reads, including those frommongodump, when queued write operation waits behind thefsynclock.
Restore a Replica Set from MongoDB Backups
This procedure outlines the process for taking MongoDB data and restoring that data into a newreplica set. Use this
approach for seeding test deployments from production backups as well as part of disaster recovery.
Youcannotrestore a single data set to three newmongodinstances andthencreate 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 efcient ways to deploy a replica set.
232 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Restore Database into a Single Node Replica Set
Step 1: Obtain backup MongoDB Database les.The backup les may come from ale system snapshot
(page 229). The
83
produces MongoDB database les for
84
and
85
. You can also usemongorestoreto restore database les using data created with
mongodump. SeeBack Up and Restore with MongoDB Tools(page 234) for more information.
Step 2: Start amongodusing data les from the backup as the data path.The following example uses
/data/dbas the data path, as specied in thedbpathsetting:
mongod --dbpath /data/db
Step 3: Convert the standalonemongodto a single-node replica setConvert the standalonemongodprocess to
a single-node replica set by shutting down themongodinstance, and restarting it with the--replSetoption, as in
the following example:
mongod --dbpath /data/db --replSet <replName>
Optionally, you can explicitly set aoplogSizeMBto control the size of theoplogcreated for this replica set member.
Step 4: Connect to themongodinstance.For example, rst use the following command to amongodinstance
running on the localhost interface:
mongo
Step 5: Initiate the new replica set.Users.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:

initial sync(page 537) 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 les onto each host.
Copy Database Files and RestartmongodInstanceUse the following sequence of operations to seed additional
members of the replica set with the restored data by copying MongoDB data les directly.
Step 1: Shut down themongodinstance that you restored.Use--shutdownordb.shutdownServer()
to ensure a clean shut down.
83
https://mms.mongodb.com/?pk_campaign=mongodb-docs-restore-rs-tutorial
84
https://mms.mongodb.com/help/backup/tutorial/restore-from-snapshot/
85
https://mms.mongodb.com/help/backup/tutorial/restore-from-point-in-time-snapshot/
5.2. Administration Tutorials 233

MongoDB Documentation, Release 2.6.4
Step 2: Copy the primary's data directory to each secondary.Copy theprimary'sdata directory into thedbPath
of the other members of the replica set. ThedbPathis/data/dbby default.
Step 3: Start themongodinstance that you restored.
Step 4: Add the secondaries to the replica set.In amongoshell connected to theprimary, add thesecondariesto
the replica set usingrs.add(). SeeDeploy a Replica Set(page 545) for more information about deploying a replica
set.
Update Secondaries using Initial SyncUse the following sequence of operations to seed additional members of
the replica set with the restored data using the defaultinitial syncoperation.
Step 1: Ensure that the data directories on the prospective replica set members are empty.
Step 2: Add each prospective member to the replica set.When you add a member to the replica set,Initial Sync
(page 537) copies the data from theprimaryto the new member.
Back Up and Restore with MongoDB Tools
This document describes the process for writing and restoring backups to les in binary format with themongodump
andmongorestoretools.
Use these tools for backups if other backup methods, such as the
86
orle system snapshots
(page 229) are unavailable.
See also:
MongoDB Backup Methods(page 172),http://docs.mongodb.org/manualreference/program/mongodump ,
andhttp://docs.mongodb.org/manualreference/program/mongorestore .
Backup a Database withmongodump
mongodumpdoesnotdump the content of thelocaldatabase.
To backup all the databases in a cluster viamongodump, you should have thebackup(page 367) role. Thebackup
(page 367) role provides all the needed privileges for backing up all database. The role confers no additional access,
in keeping with the policy ofleast privilege.
To backup a given database, you must havereadaccess on the database. Several roles provide this access, including
thebackup(page 367) role.
To backup thesystem.profilecollection in a database, you must havereadaccess on certain system collec-
tions in the database. Several roles provide this access, including theclusterAdmin(page 364) anddbAdmin
(page 363) roles.
Changed in version 2.6.
To backup users anduser-dened roles(page 286) for a given database, you must have access to theadmindatabase.
MongoDB stores the user data and role denitions for all databases in theadmindatabase.
86
https://mms.mongodb.com/?pk_campaign=mongodb-docs-tools
234 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Specically, to backup a given database's users, you must have thefind(page 375)action(page 375)
on theadmindatabase'sadmin.system.users (page 271) collection. Thebackup(page 367) and
userAdminAnyDatabase (page 368) roles both provide this privilege.
To backup the user-dened roles on a database, you must have thefind(page 375) action on theadmindatabase's
admin.system.roles (page 270) collection. Both thebackup(page 367) anduserAdminAnyDatabase
(page 368) roles provide this privilege.
BasicmongodumpOperationsThemongodumputility can back up data by either:
mongodormongosinstance, or

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 runmongodumpwithout any arguments, the command connects to the MongoDB instance on the local
system (e.g.127.0.0.1orlocalhost) on port27017and creates a database backup nameddump/in the
current directory.
To backup data from amongodormongosinstance running on the same machine and on the default port of27017,
use the following command:
mongodump
The data format used bymongodumpfrom version 2.2 or later isincompatiblewith earlier versions ofmongod. Do
not use recent versions ofmongodumpto back up older data stores.
You can also specify the--hostand--portof the MongoDB instance that themongodumpshould connect to.
For example:
mongodump --host mongodb.example.net --port 27017
mongodumpwill writeBSONles that hold a copy of data accessible via themongodlistening on port27017of
themongodb.example.net host. SeeCreate Backups from Non-Local mongod Instances(page 236) for more
information.
To usemongodumpwithout a running MongoDB instance, specify the--dbpathoption to read directly from
MongoDB data les. SeeCreate Backups Without a Running mongod Instance(page 236) for details.
To specify a different output directory, you can use the--out or -ooption:
mongodump --out /data/backup/
To limit the amount of data included in the database dump, you can specify--dband--collectionas options to
mongodump. For example:
mongodump --collection myCollection --db test
This operation creates a dump of the collection namedmyCollectionfrom the databasetestin adump/subdi-
rectory of the current working directory.
mongodumpoverwrites output les if they exist in the backup data folder. Before running themongodumpcommand
multiple times, either ensure that you no longer need the les in the output folder (the default is thedump/folder) or
rename the folders or les.
Point in Time Operation Using OplogsUse the--oplogoption withmongodumpto collect theoplogentries to
build a point-in-time snapshot of a database within a replica set. With--oplog,mongodumpcopies all the data from
the source database as well as all of theoplogentries from the beginning of the backup procedure to until the backup
5.2. Administration Tutorials 235

MongoDB Documentation, Release 2.6.4
procedure completes. This backup procedure, in conjunction withmongorestore --oplogReplay , allows you
to restore a backup that reects the specic moment in time that corresponds to whenmongodumpcompleted creating
the dump le.
Create Backups Without a RunningmongodInstanceIf your MongoDB instance is not running, you can use
the--dbpathoption to specify the location to your MongoDB instance's database les.mongodumpreads from
the data les directly with this operation. This locks the data directory to prevent conicting writes. Themongod
process mustnotbe running or attached to these data les when you runmongodumpin this conguration. Consider
the following example:
Given a MongoDB instance that contains thecustomers,products, andsuppliersdatabases, the follow-
ingmongodumpoperation backs up the databases using the--dbpathoption, which species the location of the
database les on the host:
mongodumpdbpathdatao dataout
The--out or -ooption allows you to specify the directory wheremongodumpwill save the backup.
mongodumpcreates a separate backup directory for each of the backed up databases:dataout/customers,
dataout/products, anddataout/suppliers.
Create Backups from Non-LocalmongodInstancesThe--hostand--portoptions formongodumpallow
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 anymongodumpcommand you may, as above, specify username and password credentials to specify database
authentication.
Restore a Database withmongorestore
Changed in version 2.6.
To restore users anduser-dened roles(page 286) on a given database, you must have access to theadmindatabase.
MongoDB stores the user data and role denitions for all databases in theadmindatabase.
Specically, to restore users to a given database, you must have theinsert(page 375)action(page 375) on the
admindatabase'sadmin.system.users (page 271) collection. Therestore(page 367) role provides this
privilege.
To restore user-dened roles to a database, you must have theinsert(page 375) action on theadmindatabase's
admin.system.roles (page 270) collection. Therestore(page 367) role provides this privilege.
BasicmongorestoreOperationsThemongorestoreutility restores a binary backup created by
mongodump. By default,mongorestorelooks for a database backup in thedump/directory.
Themongorestoreutility can restore data either by:
mongodormongosdirectly, or
mongod.
mongorestorecan restore either an entire database backup or a subset of the backup.
To usemongorestoreto connect to an activemongodormongos, use a command with the following prototype
form:
236 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
mongorestore --port <port number> <path to the backup>
To usemongorestoreto write to data les without using a runningmongod, 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,mongorestoreimports the database backup in thedump-2013-10-25directory to themongodinstance
running on the localhost interface.
Restore Point in Time Oplog BackupIf you created your database dump using the--oplogoption to ensure a
point-in-time snapshot, callmongorestorewith the--oplogReplayoption, as in the following example:
mongorestore --oplogReplay
You may also consider using themongorestore --objcheck option to check the integrity of objects while
inserting them into the database, or you may consider themongorestore --drop option to drop each collection
from the database before restoring from backups.
Restore a Subset of data from a Binary Database Dumpmongorestorealso includes the ability to a lter to
all input before inserting it into the new database. Consider the following example:
mongorestore --filter
Here,mongorestoreonly adds documents to the database from the dump located in thedump/folderifthe
documents have a eld namefieldthat holds a value of1. Enclose the lter in single quotes (e.g.') to prevent the
lter from interacting with your shell environment.
Restore Without a Runningmongodmongorestorecan write data to MongoDB data les without needing to
connect to amongoddirectly.
Example
Restore a Database Without a Runningmongod
Given a set of backed up databases in the/data/backup/directory:
/data/backup/customers ,
/data/backup/products , and
/data/backup/suppliers
The followingmongorestorecommand restores theproductsdatabase. The command uses the--dbpath
option to specify the path to the MongoDB data les:
mongorestoredbpathdata/dbjournaldata/backup/products
Themongorestoreimports the database backup in the/data/backup/products directory to themongod
instance that runs on the localhost interface. Themongorestoreoperation imports the backup even if themongod
is not running.
The--journaloption ensures thatmongorestorerecords all operation in the durabilityjournal. The journal
prevents data le corruption if anything (e.g. power failure, disk failure, etc.) interrupts the restore operation.
5.2. Administration Tutorials 237

MongoDB Documentation, Release 2.6.4
See also:
http://docs.mongodb.org/manualreference/program/mongodump and
http://docs.mongodb.org/manualreference/program/mongorestore .
Restore Backups to Non-LocalmongodInstancesBy default,mongorestoreconnects 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--hostand--portoptions.
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 yourmongodrequires authentication.
Backup and Restore Sharded Clusters
The following tutorials describe backup and restoration for sharded clusters:
Backup a Small Sharded Cluster with mongodump(page 238)If yoursharded clusterholds a small data set, you
can usemongodumpto capture the entire backup in a reasonable amount of time.
Backup a Sharded Cluster with Filesystem Snapshots(page 239)Use le system snapshots back up each compo-
nent in the sharded cluster individually. The procedure involves stopping the cluster balancer. If your system
conguration allows le system backups, this might be more efcient than using MongoDB tools.
Backup a Sharded Cluster with Database Dumps(page 241)Create backups usingmongodumpto back up each
component in the cluster individually.
Schedule Backup Window for Sharded Clusters(page 243)Limit the operation of the cluster balancer to provide a
window for regular backup operations.
Restore a Single Shard(page 243)An outline of the procedure and consideration for restoring a single shard from a
backup.
Restore a Sharded Cluster(page 244)An outline of the procedure and consideration for restoring anentiresharded
cluster from backup.
Backup a Small Sharded Cluster withmongodump
OverviewIf yoursharded clusterholds a small data set, you can connect to amongosusingmongodump. 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.
SeeMongoDB Backup Methods(page 172) andBackup and Restore Sharded Clusters(page 238) for complete infor-
mation on backups in MongoDB and backups of sharded clusters in particular.
Important:By defaultmongodumpissue its queries to the non-primary nodes.
To backup all the databases in a cluster viamongodump, you should have thebackup(page 367) role. Thebackup
(page 367) role provides all the needed privileges for backing up all database. The role confers no additional access,
in keeping with the policy ofleast privilege.
To backup a given database, you must havereadaccess on the database. Several roles provide this access, including
thebackup(page 367) role.
238 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
To backup thesystem.profilecollection in a database, you must havereadaccess on certain system collec-
tions in the database. Several roles provide this access, including theclusterAdmin(page 364) anddbAdmin
(page 363) roles.
Changed in version 2.6.
To backup users anduser-dened roles(page 286) for a given database, you must have access to theadmindatabase.
MongoDB stores the user data and role denitions for all databases in theadmindatabase.
Specically, to backup a given database's users, you must have thefind(page 375)action(page 375)
on theadmindatabase'sadmin.system.users (page 271) collection. Thebackup(page 367) and
userAdminAnyDatabase (page 368) roles both provide this privilege.
To backup the user-dened roles on a database, you must have thefind(page 375) action on theadmindatabase's
admin.system.roles (page 270) collection. Both thebackup(page 367) anduserAdminAnyDatabase
(page 368) roles provide this privilege.
ConsiderationsIf you usemongodumpwithout specifying a database or collection,mongodumpwill capture
collection dataandthe cluster meta-data from thecong servers(page 616).
You cannot use the--oplogoption formongodumpwhen capturing data frommongos. As a result, if you need
to capture a backup that reects a single moment in time, you must stop all writes to the cluster for the duration of the
backup operation.
Procedure
Capture DataYou can perform a backup of asharded clusterby connectingmongodumpto amongos. Use the
following operation at your system's prompt:
mongodump --host mongos3.example.net --port 27017
mongodumpwill writeBSONles that hold a copy of data stored in thesharded clusteraccessible via themongos
listening on port27017of themongos3.example.net host.
Restore DataBackups created withmongodumpdo not reect the chunks or the distribution of data in the sharded
collection or collections. Like allmongodumpoutput, these backups contain separate directories for each database
andBSONles for each collection in that database.
You can restoremongodumpoutput to any MongoDB instance, including a standalone, areplica set, or a newsharded
cluster. When restoring data to sharded cluster, you must deploy and congure sharding before restoring data from
the backup. SeeDeploy a Sharded Cluster(page 635) for more information.
Backup a Sharded Cluster with Filesystem Snapshots
OverviewThis document describes a procedure for taking a backup of all components of a sharded cluster. This pro-
cedure uses le system snapshots to capture a copy of themongodinstance. An alternate procedure usesmongodump
to create binary database dumps when le-system snapshots are not available. SeeBackup a Sharded Cluster with
Database Dumps(page 241) for the alternate procedure.
SeeMongoDB Backup Methods(page 172) andBackup and Restore Sharded Clusters(page 238) for complete infor-
mation on backups in MongoDB and backups of sharded clusters in particular.
Important:To capture a point-in-time backup from a sharded cluster youmuststopallwrites to the cluster. On a
running production system, you can only capture anapproximationof point-in-time snapshot.
5.2. Administration Tutorials 239

MongoDB Documentation, Release 2.6.4
Considerations
BalancingIt isessentialthat 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,
aschunksmay migrate while recording backups.
PrecisionIn this procedure, you will stop the cluster balancer and take a backup up of thecong database, and
then take backups of each shard in the cluster using a le-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 lesystem 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.
Procedure
Step 1: Disable the balancer.Disable thebalancerprocess that equalizes the distribution of data among theshards.
To disable the balancer, use thesh.stopBalancer()method in themongoshell. For example:
use config
sh.stopBalancer()
For more information, see theDisable the Balancer(page 661) procedure.
Step 2: Lock one secondary member of each replica set in each shard.Lock one secondary member of each
replica set in each shard so that your backups reect the state of your database at the nearest possible approximation
of a single moment in time. Lock thesemongodinstances in as short of an interval as possible.
To lock a secondary, connect through themongoshell to the secondary member'smongodinstance and issue the
db.fsyncLock()method.
Step 3: Back up one of the cong servers.Backing up acong server(page 616) backs up the sharded cluster's
metadata. You need back up only one cong server, as they all hold the same data. Do one of the following to back up
one of the cong servers:
Create a le-system snapshot of the cong server.Do thisonly ifthe cong server hasjournalingenabled. Use
the procedure inBackup and Restore with Filesystem Snapshots(page 229).Neverusedb.fsyncLock()on cong
databases.
Create a database dump to backup the cong server.Issuemongodumpagainst one of the congmongod
instances or via themongos. If you are running MongoDB 2.4 or later with the--configsvroption, then include
the--oplogoption 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 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 inBackup and Restore with Filesystem Snapshots(page 229).
240 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Step 5: Unlock locked replica set members.Unlock all locked replica set members of each shard using the
db.fsyncUnlock()method in themongoshell.
Step 6: Enable the balancer.Re-enable the balancer with thesh.setBalancerState() method. Use the
following command sequence when connected to themongoswith themongoshell:
use config
sh.setBalancerState(true)
Backup a Sharded Cluster with Database Dumps
OverviewThis document describes a procedure for taking a backup of all components of a sharded cluster. This
procedure usesmongodumpto create dumps of themongodinstance. An alternate procedure uses le system snap-
shots to capture the backup data, and may be more efcient in some situations if your system conguration allows le
system backups. SeeBackup and Restore Sharded Clusters(page 238) for more information.
SeeMongoDB Backup Methods(page 172) andBackup and Restore Sharded Clusters(page 238) for complete infor-
mation on backups in MongoDB and backups of sharded clusters in particular.
Prerequisites
Important:To capture a point-in-time backup from a sharded cluster youmuststopallwrites to the cluster. On a
running production system, you can only capture anapproximationof point-in-time snapshot.
To backup all the databases in a cluster viamongodump, you should have thebackup(page 367) role. Thebackup
(page 367) role provides all the needed privileges for backing up all database. The role confers no additional access,
in keeping with the policy ofleast privilege.
To backup a given database, you must havereadaccess on the database. Several roles provide this access, including
thebackup(page 367) role.
To backup thesystem.profilecollection in a database, you must havereadaccess on certain system collec-
tions in the database. Several roles provide this access, including theclusterAdmin(page 364) anddbAdmin
(page 363) roles.
Changed in version 2.6.
To backup users anduser-dened roles(page 286) for a given database, you must have access to theadmindatabase.
MongoDB stores the user data and role denitions for all databases in theadmindatabase.
Specically, to backup a given database's users, you must have thefind(page 375)action(page 375)
on theadmindatabase'sadmin.system.users (page 271) collection. Thebackup(page 367) and
userAdminAnyDatabase (page 368) roles both provide this privilege.
To backup the user-dened roles on a database, you must have thefind(page 375) action on theadmindatabase's
admin.system.roles (page 270) collection. Both thebackup(page 367) anduserAdminAnyDatabase
(page 368) roles provide this privilege.
ConsiderationTo create these backups of a sharded cluster, you will stop the cluster balancer and take a backup up
of thecong database, and then take backups of each shard in the cluster usingmongodumpto 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 lesystem snapshots; otherwise the snapshot will only approximate a moment in time.
For approximate point-in-time snapshots, taking the backup from a single ofine secondary member of the replica set
that provides each shard can improve the quality of the backup while minimizing impact on the cluster.
5.2. Administration Tutorials 241

MongoDB Documentation, Release 2.6.4
Procedure
Step 1: Disable the balancer process.Disable thebalancerprocess that equalizes the distribution of data among
theshards. To disable the balancer, use thesh.stopBalancer()method in themongoshell. For example:
use config
sh.setBalancerState(false)
For more information, see theDisable the Balancer(page 661) procedure.
If you do not stop the balancer, the backup could have duplicate data or omit data aschunksmigrate while recording
backups.
Step 2: Lock replica set members.Lock one member of each replica set in each shard so that your backups reect
the state of your database at the nearest possible approximation of a single moment in time. Lock thesemongod
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 theoploghas sufcient
capacity to allow these secondaries to catch up to the state of the primaries after nishing the backup procedure. See
Oplog Size(page 535) for more information.
Step 3: Backup one cong server.Usemongodumpto backup one of thecong servers(page 616). This backs up
the cluster's metadata. You only need to back up one cong server, as they all hold the same data.
Use themongodumptool to capture the content of the congmongodinstances.
Your cong servers must run MongoDB 2.4 or later with the--configsvroption and themongodumpoption
must include the--oplogto capture a consistent copy of the cong database:
mongodump --oplog --db config
Step 4: Backup replica set members.Back up the replica set members of the shards that shut down using
mongodumpand specifying the--dbpathoption. You may back up the shards in parallel. Consider the following
invocation:
mongodump --journal --dbpath /data/db/ --out /data/backup/
You must runmongodumpon the same system where themongodran. This operation will create a dump of all the
data managed by themongodinstances that used thedbPath /data/db/.mongodumpwrites the output of this
dump to the/data/backup/directory.
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.
Step 6: Re-enable the balancer process.Re-enable the balancer with thesh.setBalancerState() method.
Use the following command sequence when connected to themongoswith themongoshell:
use config
sh.setBalancerState(true)
242 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Schedule Backup Window for Sharded Clusters
OverviewIn asharded cluster, the balancer process is responsible for distributing sharded data around the cluster,
so that eachshardhas 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 sectionDisable the Balancer(page 661) you can manually stop the balancer process
temporarily. As an alternative you can use this procedure to dene a balancing window so that the balancer is always
disabled during your automated backup operation.
ProcedureIf 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, stop true)
This operation congures the balancer to run between 6:00am and 11:00pm, server time. Schedule your backup
operation to runand completeoutside of this time. Ensure that the backup can complete outside the window when
the balancer is runningandthat the balancer can effectively balance the collection among the shards in the window
allotted to each.
Restore a Single Shard
OverviewRestoring a single shard from backup with other unaffected shards requires a number of special consider-
ations 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 speci-
cally:
Backup and Restore Sharded Clusters(page 238)
Restore a Sharded Cluster(page 244)
MongoDB Backup Methods(page 172)
ProcedureAlways restoresharded clustersas a whole. When you restore a single shard, keep in mind that the
balancerprocess might have movedchunksto or from this shard since the last backup. If that's the case, you must
manually move those chunks, as described in this procedure.
Step 1: Restore the shard as you would any othermongodinstance.SeeMongoDB Backup Methods(page 172)
for overviews of these procedures.
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 ltered out
from queries bymongos. 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 back-
ups of other shards, or some other source. To determine what chunks have moved, view thechangelogcollection
in theCong Database(page 679).
5.2. Administration Tutorials 243

MongoDB Documentation, Release 2.6.4
Restore a Sharded Cluster
OverviewYou can restore a sharded cluster either fromsnapshots(page 229) or fromBSON
(page 241) created by themongodumptool. This document provides procedures for both:
Restore a Sharded Cluster with Filesystem Snapshots(page 244)
restore-sh-cl-dmp
Related DocumentsFor an overview of backups in MongoDB, seeMongoDB Backup Methods(page 172). For
complete information on backups and backups of sharded clusters in particular, seeBackup and Restore Sharded
Clusters(page 238).
For backup procedures, see:
Backup a Sharded Cluster with Filesystem Snapshots(page 239)
Backup a Sharded Cluster with Database Dumps(page 241)
ProceduresUse the procedure for the type of backup les to restore.
Restore a Sharded Cluster with Filesystem Snapshots
Step 1: Shut down the entire cluster.Stop allmongosandmongodprocesses, including all shardsandall cong
servers.
Connect to each member use the following operation:
use admin
db.shutdownServer()
For version 2.4 or earlier, usedb.shutdownServer({force:true}) .
Step 2: Restore the data les.One each server, extract the data les to the location where themongodinstance
will access them. Restore the following:
Data les for each server in each shard.Because replica sets provide each productionshard, restore all the mem-
bers of the replica set or use the other standard approaches for restoring a replica set from backup. See theRestore a
Snapshot(page 231) andRestore a Database with mongorestore(page 236) sections for details on these procedures.
Data les for each cong server.
Step 3: Restart the cong servers.Restart eachcong server(page 616)mongodinstance by issuing a command
similar to the following for each, using values appropriate to your conguration:
mongod --configsvr --dbpath /data/configdb --port 27019
Step 4: If shard hostnames have changed, update the cong string and cong database.If shard hostnames
have changed, startonemongosinstance using the updated cong string with the newconfigdbhostnames and
ports.
Then update theshardscollection in theCong Database(page 679) to reect the new hostnames. Then stop the
mongosinstance.
244 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Step 5: Restart all the shardmongodinstances.
Step 6: Restart all themongosinstances.If shard hostnameshave changed, make sure to use the updated cong
string.
Step 7: Connect to amongosto ensure the cluster is operational.Connect to amongosinstance from amongo
shell and use thedb.printShardingStatus() method to ensure that the cluster is operational, as follows:
db.printShardingStatus()
show collections
Restore a Sharded Cluster with Database Dumps
Step 1: Shut down the entire cluster.Stop allmongosandmongodprocesses, including all shardsandall cong
servers.
Connect to each member use the following operation:
use admin
db.shutdownServer()
For version 2.4 or earlier, usedb.shutdownServer({force:true}) .
Step 2: Restore the data les.One each server, usemongorestoreto restore the database dump to the location
where themongodinstance will access the data.
The following example restores a database dump located athttp://docs.mongodb.org/manualopt/backup/
to the/data/directory. This requires that there are no activemongodinstances attached to the/datadirectory.
mongorestore --dbpath /data /opt/backup
Step 3: Restart the cong servers.Restart eachcong server(page 616)mongodinstance by issuing a command
similar to the following for each, using values appropriate to your conguration:
mongod --configsvr --dbpath /data/configdb --port 27019
Step 4: If shard hostnames have changed, update the cong string and cong database.If shard hostnames
have changed, startonemongosinstance using the updated cong string with the newconfigdbhostnames and
ports.
Then update theshardscollection in theCong Database(page 679) to reect the new hostnames. Then stop the
mongosinstance.
Step 5: Restart all the shardmongodinstances.
Step 6: Restart all themongosinstances.If shard hostnameshave changed, make sure to use the updated cong
string.
5.2. Administration Tutorials 245

MongoDB Documentation, Release 2.6.4
Step 7: Connect to amongosto ensure the cluster is operational.Connect to amongosinstance from amongo
shell and use thedb.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
87
the on-disk representation of the data les will likely reect an inconsistent
state which could lead to data corruption.
88
To prevent data inconsistency and corruption, always shut down the database cleanly and use thedurability 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 arenotrunning as part of areplica setanddonothave 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 shouldalwaysrestore
from a backup or restart themongodinstance with an emptydbPathand allow MongoDB to perform an initial sync
to restore the data.
See also:
TheAdministration(page 171) documents, includingReplica Set Syncing(page 535), and the documentation on the
--repairrepairPathandstorage.journal.enabled settings.
Process
IndicationsWhen you are aware of amongodinstance running without journaling that stops unexpectedlyand
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 initialsync(page 535) to
restore data.
If themongod.lockle in the data directory specied bydbPath,/data/dbby default, isnota zero-byte le,
thenmongodwill refuse to start, and you will nd a message that contains the following line in your MongoDB log
our output:
Unclean shutdown detected.
This indicates that you need to runmongodwith the--repairoption. If you run repair when themongodb.lock
le exists in yourdbPath, 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 lockleandrun the repair operation before starting the
database normally, as in the following procedure:
87
To ensure a clean shut down, use thedb.shutdownServer() from themongoshell, your control script, themongod --shutdown
option on Linux systems, Control-C when runningmongodin interactive mode, orkill $(pidof mongod) orkill -2 $(pidof
mongod).
88
You can also use thedb.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.
246 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Overview
Warning:Recovering a member of a replica set.
Do not use this procedure to recover a member of areplica set. Instead you should either restore from abackup
(page 172) or perform an initial sync using data from an intact member of the set, as described inResync a Member
of a Replica Set(page 575).
There are two processes to repair data les that result from an unexpected shutdown:
--repairoption in conjunction with the--repairpathoption.mongodwill read the existing
data les, and write the existing data to new data les. This does not modify or alter the existing data les.
You do not need to remove themongod.lockle before using this procedure.
--repairoption.mongodwill read the existing data les, write the existing data to new les and
replace the existing, possibly corrupt, les with new les.
You must remove themongod.lockle before using this procedure.
Note:--repairfunctionality is also available in the shell with thedb.repairDatabase() helper for the
repairDatabasecommand.
Procedures
Important:Always Runmongodas the same user to avoid changing the permissions of the MongoDB data les.
Repair Data Files and Preserve Original FilesTo repair your data les using the--repairpathoption to
preserve the original data les unmodied.
Repair Data Files without Preserving Original FilesTo repair your data les without preserving the original les,
do not use the--repairpathoption, as in the following procedure:
Warning:After you remove themongod.lockle youmustrun the--repairprocess before using your
database.
Step 1: Startmongodusing the option to replace the original les with the repaired les.Start themongod
instance using the--repairoptionandthe--repairpathoption. Issue a command similar to the following:
mongod --dbpath /data/db --repair --repairpath /data/db0
When this completes, the new repaired data les will be in the/data/db0directory.
Step 2: Startmongodwith the new data directory.Startmongodusing the following invocation to point the
dbPathat/data/db0:
mongod --dbpath /data/db0
Once you conrm that the data les are operational you may delete or archive the old data les in the/data/db
directory. You may also wish to move the repaired les to the old database location or update thedbPathto indicate
the new location.
Step 1: Remove the stale lock le.For example:
5.2. Administration Tutorials 247

MongoDB Documentation, Release 2.6.4
rm /data/db/mongod.lock
Replace/data/dbwith yourdbPathwhere your MongoDB instance's data les reside.
Step 2: Startmongodusing the option to replace the original les with the repaired les.Start themongod
instance using the--repairoption, which replaces the original data les with the repaired data les. Issue a
command similar to the following:
mongod --dbpath /data/db --repair
When this completes, the repaired data les will replace the original data les in the/data/dbdirectory.
Step 3: Startmongodas usual.Startmongodusing the following invocation to point thedbPathat/data/db:
mongod --dbpath /data/db
mongod.lock
In normal operation, you shouldneverremove themongod.lockle and startmongod. Instead consider the one
of the above methods to recover the database and remove the lock les. In dire situations you can remove the lockle,
and start the database using the possibly corrupt les, 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 foranyreason, you should always
proceedas ifyour database is in an inconsistent and likely corrupt state. If at all possible restore frombackup
(page 172) or, if running as areplica set, restore by performing an initial sync using data from an intact member of the
set, as described inResync a Member of a Replica Set(page 575).
5.2.3
Themongoshell is an interactive JavaScript shell for MongoDB, and is part of all
89
. This
section provides an introduction to the shell, and outlines key functions, operations, and use of themongoshell. Also
considerFAQ: The mongo Shell(page 700) and theshell methodand other relevantreference material.
Note:Most examples in theMongoDB Manualuse themongoshell; however, manydriversprovide similar
interfaces to MongoDB.
Server-side JavaScript(page 249)Details MongoDB's support for executing JavaScript code for server-side opera-
tions.
Data Types in the mongo Shell(page 250)Describes the super-set of JSON available for use in themongoshell.
Write Scripts for the mongo Shell(page 253)An introduction to themongoshell for writing scripts to manipulate
data and administer MongoDB.
Getting Started with the mongo Shell(page 255)Introduces the use and operation of the MongoDB shell.
Access the mongo Shell Help Information(page 259)Describes the available methods for accessing online help for
the operation of themongointeractive shell.
mongo Shell Quick Reference(page 261)A high level reference to the use and operation of themongoshell.
89
http://www.mongodb.org/downloads
248 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Server-side JavaScript
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 singlemongodcould only run a single JavaScript operation at a time.
Overview
MongoDB supports the execution of JavaScript code for the following server-side operations:
mapReduceand the correspondingmongoshell methoddb.collection.mapReduce() . SeeMap-
Reduce(page 394) for more information.
evalcommand, and the correspondingmongoshell methoddb.eval()
$whereoperator
Running .js les via a mongo shell Instance on the Server(page 249)
JavaScript in MongoDB
Although the above operations use JavaScript, most interactions with MongoDB do not use JavaScript but use an
idiomatic driverin the language of the interacting application.
See also:
Store a JavaScript Function on the Server(page 217)
You can disable all server-side execution of JavaScript, by passing the--noscriptingoption on the command
line or settingsecurity.javascriptEnabled in a conguration le.
Running.jsles via amongoshell Instance on the Server
You can run a JavaScript (.js) le using amongoshell instance on the server. This is a good technique for performing
batch administrative work. When you runmongoshell on the server, connecting via the localhost interface, the
connection is fast with low latency.
Thecommand helpers(page 261) provided in themongoshell are not available in JavaScript les because they are
not valid JavaScript. The following table maps the most commonmongoshell helpers to their JavaScript equivalents.
5.2. Administration Tutorials 249

MongoDB Documentation, Release 2.6.4
Shell Helpers JavaScript Equivalents
show dbs,show databases
db.adminCommand(listDatabases)
use <db>
db<db>)
show collections
db.getCollectionNames()
show users
db.getUsers()
show roles
db.getRoles({showBuiltinRoles: true})
show log <logname>
db.adminCommand({
show logs
db.adminCommand({ *
it
cursor
if( cursor.hasNext() ){
cursor.next();
}
Concurrency
Refer to the individual method or operator documentation for any concurrency information. See also theconcurrency
table(page 703).
Data Types in themongoShell
MongoDBBSONprovides support for additional data types thanJSON.Driversprovide na-
tive support for these data types in host languages and themongoshell also provides sev-
eral helper classes to support the use of these data types in themongoJavaScript shell. See
http://docs.mongodb.org/manualreference/mongodb-extended-json for additional infor-
mation.
Types
DateThemongoshell provides various methods to return the date, either as a string or as aDateobject:
Date()method which returns the current date as a string.
new Date()constructor which returns aDateobject using theISODate()wrapper.
ISODate()constructor which returns aDateobject using theISODate()wrapper.
Internally,Dateobjects 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.
250 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Return Date as a StringTo return the date as a string, use theDate()method, as in the following example:
varmyDateString();
To print the value of the variable, type the variable name in the shell, as in the following:
myDateString
The result is the value ofmyDateString:
Wed Dec:03:25-0500
To verify the type, use thetypeofoperator, as in the following:
typeofmyDateString
The operation returnsstring.
ReturnDateThemongoshell wrap objects ofDatetype with theISODatehelper; however, the objects remain
of typeDate.
The following example uses both thenew Date()constructor and theISODate()constructor to returnDate
objects.
varmyDate newDate();
varmyDateInitUsingISODateWrapper
You can use thenewoperator with theISODate()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 theDatevalue ofmyDatewrapped in theISODate()helper:
ISODate("2012-12-19T06:01:17.171Z")
To verify the type, use theinstanceofoperator, as in the following:
myDateinstanceofDate
myDateInitUsingISODateWrapper instanceofDate
The operation returnstruefor both.
ObjectIdThemongoshell provides theObjectId()wrapper class around theObjectIddata type. To generate a
new ObjectId, use the following operation in themongoshell:
newObjectId
See
ObjectId(page 165) for full documentation of ObjectIds in MongoDB.
NumberLongBy default, themongoshell treats all numbers as oating-point values. Themongoshell provides
theNumberLong()wrapper to handle 64-bit integers.
TheNumberLong()wrapper accepts the long as a string:
5.2. Administration Tutorials 251

MongoDB Documentation, Release 2.6.4
NumberLong("2090845886852")
The following examples use theNumberLong()wrapper to write to the collection:
db.collection.insert( { _id:, calc:"2090845886852") } )
db.collection.update( { _id:
{ $set::"2555555000000") } } )
db.collection.update( { _id:
{ $inc::5) } } )
Retrieve the document to verify:
db.collection.findOne( { _id:
In the returned document, thecalceld contains aNumberLongobject:
{("2555555000005")
If you use the$incto increment the value of a eld that contains aNumberLongobject by aoat, the data type
changes to a oating point value, as in the following example:
1. $incto increment thecalceld by5, which themongoshell treats as a oat:
db.collection.update( { _id:
{ $inc::
2.
db.collection.findOne( { _id:
In the updated document, thecalceld contains a oating point value:
{
NumberIntBy default, themongoshell treats all numbers as oating-point values. Themongoshell provides the
NumberInt()constructor to explicitly specify 32-bit integers.
Check Types in themongoShell
To determine the type of elds, themongoshell provides theinstanceofandtypeofoperators.
instanceofinstanceofreturns a boolean to test if a value is an instance of some type.
For example, the following operation tests whether the_ideld is an instance of typeObjectId:
mydoc._idinstanceofObjectId
The operation returnstrue.
typeoftypeofreturns the type of a eld.
For example, the following operation returns the type of the_ideld:
typeofmydoc._id
In this casetypeofwill return the more genericobjecttype rather thanObjectIdtype.
252 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Write Scripts for themongoShell
You can write scripts for themongoshell in JavaScript that manipulate data in MongoDB or perform administrative
operation. For more information about themongoshell seeMongoDB Scripting(page 248), and see theRunning .js
les via a mongo shell Instance on the Server(page 249) section for more information about using thesemongoscript.
This tutorial provides an introduction to writing JavaScript that uses themongoshell to access MongoDB.
Opening New Connections
From themongoshell or from a JavaScript le, you can instantiate database connections using theMongo()con-
structor:
newMongo()
newMongo(<host>)
newMongo(<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 globaldbvariable tomyDatabaseusing thegetDB()method:
conn newMongo();
db"myDatabase");
Additionally, you can use theconnect()method to connect to the MongoDB instance. The following example
connects to the MongoDB instance that is running onlocalhostwith the non-default port27020and set the
globaldbvariable:
db"localhost:27020/myDatabase");
Differences Between Interactive and Scriptedmongo
When writing scripts for themongoshell, consider the following:
dbglobal variable, use thegetDB()method or theconnect()method. You can assign the
database reference to a variable other thandb.
mongoshell use the safe writes by default. If performing bulk operations, use the
Bulk()methods. SeeWrite Method Acknowledgements(page 743) for more information.
Changed in version 2.6: Before MongoDB 2.6, calldb.getLastError()explicitly to wait for the result of
write operations(page 67).
cannotuse any shell helper (e.g.use <dbname>,show dbs, etc.) inside the JavaScript le because
they are not valid JavaScript.
The following table maps the most commonmongoshell helpers to their JavaScript equivalents.
5.2. Administration Tutorials 253

MongoDB Documentation, Release 2.6.4
Shell Helpers JavaScript Equivalents
show dbs,show databases
db.adminCommand(listDatabases)
use <db>
db<db>)
show collections
db.getCollectionNames()
show users
db.getUsers()
show roles
db.getRoles({showBuiltinRoles: true})
show log <logname>
db.adminCommand({
show logs
db.adminCommand({ *
it
cursor
if( cursor.hasNext() ){
cursor.next();
}
mongoprints the results of operations including the content of all cursors. In scripts, either
use the JavaScriptprint()function or themongospecicprintjson()function which returns formatted
JSON.
Example
To print all items in a result cursor inmongoshell scripts, use the following idiom:
cursor
while( cursor.hasNext() ) {
printjson( cursor.next() );
}
Scripting
From the system prompt, usemongoto evaluate JavaScript.
--evaloptionUse the--evaloption tomongoto pass the shell a JavaScript fragment, as in the following:
mongo
This returns the output ofdb.getCollectionNames() using themongoshell connected to themongodor
mongosinstance running on port27017on thelocalhostinterface.
Execute a JavaScript leYou can specify a.jsle to themongoshell, andmongowill execute the JavaScript
directly. Consider the following example:
254 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
mongo localhost:27017/test myjsfile.js
This operation executes themyjsfile.jsscript in amongoshell that connects to thetestdatabaseon the
mongodinstance accessible via thelocalhostinterface on port27017.
Alternately, you can specify the mongodb connection parameters inside of the javascript le using theMongo()
constructor. SeeOpening New Connections(page 253) for more information.
You can execute a.jsle from within themongoshell, using theload()function, as in the following:
load("myjstest.js")
This function loads and executes themyjstest.jsle.
Theload()method accepts relative and absolute paths. If the current working directory of themongoshell is
/data/db, and themyjstest.jsresides in the/data/db/scriptsdirectory, then the following calls within
themongoshell would be equivalent:
load("scripts/myjstest.js")
load("/data/db/scripts/myjstest.js")
Note:There is no search path for theload()function. If the desired script is not in the current working directory
or the full specied path,mongowill not be able to access the le.
Getting Started with themongoShell
This document provides a basic introduction to using themongoshell. SeeInstall MongoDB(page 5) for instructions
on installing MongoDB for your system.
Start themongoShell
To start themongoshell and connect to yourMongoDBinstance running onlocalhostwithdefault port:
1. <mongodb installation dir> :
cd
2. ./bin/mongoto startmongo:
./bin/mongo
If you have added the<mongodb installation dir>/bin to thePATHenvironment variable, you can
just typemongoinstead of./bin/mongo.
3. db:
db
The operation should returntest, which is the default database. To switch databases, issue theuse <db>
helper, as in the following example:
usedatabase>
To list the available databases, use the helpershow dbs. See alsoHow can I access different databases
temporarily?(page 700) to access a different database from the current database without switching your current
database context (i.e.db..)
5.2. Administration Tutorials 255

MongoDB Documentation, Release 2.6.4
To start themongoshell with other options, seeexamples of starting up mongoandmongo referencewhich
provides details on the available options.
Note:When starting,mongochecks the user'sHOMEdirectory for a JavaScript le named.mongorc.js. If found,
mongointerprets the content of.mongorc.jsbefore displaying the prompt for the rst time. If you use the shell to
evaluate a JavaScript le or expression, either by using the--evaloption on the command line or by specifyinga .js
le to mongo,mongowill read the.mongorc.jsleafterthe JavaScript has nished processing. You can prevent
.mongorc.jsfrom being loaded by using the--norcoption.
Executing Queries
From themongoshell, you can use theshell methodsto run queries, as in the following example:
db.<collection>.find()
dbrefers to the current database.
<collection>is the name of the collection to query. SeeCollection Help(page 259) to list the available
collections.
If themongoshell 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()
find()method is the JavaScript method to retrieve documents from<collection>. Thefind()
method returns acursorto the results; however, in themongoshell, if the returned cursor is not assigned to a
variable using thevarkeyword, then the cursor is automatically iterated up to 20 times to print up to the rst
20 documents that match the query. Themongoshell will promptType itto iterate another 20 times.
You can set theDBQuery.shellBatchSize attribute to change the number of iteration from the default
value20, as in the following example which sets it to10:
DBQuery.shellBatchSize;
For more information and examples on cursor handling in themongoshell, seeCursors(page 59).
See alsoCursor Help(page 260) for list of cursor help in themongoshell.
For more documentation of basic MongoDB operations in themongoshell, see:
Getting Started with MongoDB(page 43)
mongo Shell Quick Reference(page 261)
Read Operations(page 55)
Write Operations(page 67)
Indexing Tutorials(page 464)
Print
Themongoshell automatically prints the results of thefind()method if the returned cursor is not assigned to
a variable using thevarkeyword. To format the result, you can add the.pretty()to the operation, as in the
following:
256 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
db.<collection>.find().pretty()
In addition, you can use the following explicit print methods in themongoshell:
print()to print without formatting
print(tojson(<obj>)) to print withJSONformatting and equivalent toprintjson()
printjson()to print withJSONformatting and equivalent toprint(tojson(<obj>))
Evaluate a JavaScript File
You can execute a.jsle from within themongoshell, using theload()function, as in the following:
load("myjstest.js")
This function loads and executes themyjstest.jsle.
Theload()method accepts relative and absolute paths. If the current working directory of themongoshell is
/data/db, and themyjstest.jsresides in the/data/db/scriptsdirectory, then the following calls within
themongoshell would be equivalent:
load("scripts/myjstest.js")
load("/data/db/scripts/myjstest.js")
Note:There is no search path for theload()function. If the desired script is not in the current working directory
or the full specied path,mongowill not be able to access the le.
Use a Custom Prompt
You may modify the content of the prompt by creating the variablepromptin the shell. The prompt variable can
hold strings as well as any arbitrary JavaScript. Ifpromptholds a function that returns a string,mongocan display
dynamic information in each prompt. Consider the following examples:
Example
Create a prompt with the number of operations issued in the current session, dene the following variables:
cmdCount;
prompt function() {
return(cmdCount++);
}
The prompt would then resemble the following:
1>
2>
3>
Example
To create amongoshell prompt in the form of<database>@<hostname>$ dene the following variables:
host
prompt function() {
5.2. Administration Tutorials 257

MongoDB Documentation, Release 2.6.4
returndb+"@"+host+"$ ";
}
The prompt would then resemble the following:
<database>@<hostname>$ use records
switched to db records
records@<hostname>$
Example
To create amongoshell prompt that contains the system up timeandthe number of documents in the current database,
dene the following prompt variable:
prompt function() {
return"Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > ";
}
The prompt would then resemble the following:
Uptime:5897:6});
Uptime:5948:7
Use an External Editor in themongoShell
New in version 2.2.
In themongoshell you can use theeditoperation to edit a function or variable in an external editor. Theedit
operation uses the value of your environmentsEDITORvariable.
At your system prompt you can dene theEDITORvariable and startmongowith the following two operations:
export=vim
mongo
Then, consider the following example shell session:
MongoDB shell version:.0
>functionf() {}
>
>
functionf() {
print("this really works");
}
>
thisreally works
>
{ }
>
>
{
>
Note:Asmongoshell interprets code edited in an external editor, it may modify code in functions, depending on
the JavaScript compiler. Formongomay convert1+1to2or 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.
258 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Exit the Shell
To exit the shell, typequit()or use the<Ctrl-c>shortcut.
Access themongoShell Help Information
In addition to the documentation in theMongoDB Manual, themongoshell 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(page 248), and
mongo Shell Quick Reference(page 261).
Command Line Help
To see the list of options and help for starting themongoshell, use the--helpoption from the command line:
mongo --help
Shell Help
To see the list of help, in themongoshell, typehelp:
help
Database Help
show dbscommand:
show dbs
New in version 2.4:show databasesis now an alias forshow dbs
dbobject, call thedb.help()method:
db.help()
db.<method name>without the parenthesis
(()), as in the following example which will return the implementation of the methoddb.addUser():
db.addUser
Collection Help
show collectionscommand:
5.2. Administration Tutorials 259

MongoDB Documentation, Release 2.6.4
show collections
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.
db.<collection>.<method> name without the
parenthesis (()), as in the following example which will return the implementation of thesave()method:
db.collection.save
Cursor Help
When you performread operations(page 55) with thefind()method in themongoshell, you can use various
cursor methods to modify thefind()behavior and various JavaScript methods to handle the cursor returned from
thefind()method.
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.
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, seecursor handling(page 59). See
alsojs-query-cursor-methodsfor all available cursor methods.
Type Help
To get a list of the wrapper classes available in themongoshell, such asBinData(), typehelp miscin the
mongoshell:
help misc
260 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
mongoShell Quick Reference
mongoShell Command History
You can retrieve previous commands issued in themongoshell with the up and down arrow keys. Command history
is stored in~/.dbshellle. See.dbshellfor more information.
Command Line Options
Themongoexecutable can be started with numerous options. Seemongo executablepage for details on all
available options.
The following table displays some common options formongo:
Op-
tion
Description
--helpShow command line options
--nodbStartmongoshell without connecting to a database.
To connect later, seeOpening New Connections(page 253).
--shellUsed in conjunction with a JavaScript le (i.e.<le.js>) to continue in themongoshell after running
the JavaScript le.
SeeJavaScript le(page 254) for an example.
Command Helpers
Themongoshell 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>. Themongoshell variabledbis 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-dened and built-in, for the current database.
show profile Print the ve most recent operations that took 1 millisecond or more. See documentation
on thedatabase proler(page 210) for more information.
show databases New in version 2.4: Print a list of all available databases.
load() Execute a JavaScript le. SeeGetting Started with the mongo Shell(page 255) for more
information.
Basic Shell JavaScript Operations
Themongoshell provides numeroushttp://docs.mongodb.org/manualreference/method methods
for database operations.
In themongoshell,dbis the variable that references the current database. The variable is automatically set to the
default databasetestor is set when you use theuse <db>to switch current database.
5.2. Administration Tutorials 261

MongoDB Documentation, Release 2.6.4
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 specic collection in the current database to a vari-
ablecoll, as in the following example:
coll
You can perform operations on themyCollection
using the variable, as in the following example:
coll.find();
find() Find all documents in the collection and returns a cursor.
See thedb.collection.find() andQuery Docu-
ments(page 87) for more information and examples.
SeeCursors(page 59) for additional information on cur-
sor handling in themongoshell.
insert() Insert a new document into the collection.
update() Update an existing document in the collection.
SeeWrite Operations(page 67) for more information.
save() Insert either a new document or update an existing doc-
ument in the collection.
SeeWrite Operations(page 67) for more information.
remove() Delete documents from the collection.
SeeWrite Operations(page 67) 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?
(page 700) for more information.
For more information on performing operations in the shell, see:
MongoDB CRUD Concepts(page 53)
Read Operations(page 55)
Write Operations(page 67)
http://docs.mongodb.org/manualreference/method
Keyboard Shortcuts
Changed in version 2.2.
Themongoshell provides most keyboard shortcuts similar to those found in thebashshell or in Emacs. For some
functionsmongoprovides multiple key bindings, to accommodate several familiar paradigms.
The following table enumerates the keystrokes supported by themongoshell:
Keystroke Function
Up-arrow previous-history
Down-arrow next-history
Home beginning-of-line
Continued on next page
262 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
Table 5.1 continued from previous page
Keystroke Function
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 themongoshell, perform read operations using thefind()andfindOne()methods.
Thefind()method returns a cursor object which themongoshell iterates to print documents on screen. By default,
mongoprints the rst 20. Themongoshell will prompt the user to Type it to continue iterating the next 20
results.
The following table provides some common read operations in themongoshell:
5.2. Administration Tutorials 263

MongoDB Documentation, Release 2.6.4
Read Operations Description
db.collection.find(<query>) Find the documents matching the<query>criteria in
the collection. If the<query>criteria is not specied
or is empty (i.e{}), the read operation selects all doc-
uments in the collection.
The following example selects the documents in the
userscollection with thenameeld equal to"Joe":
coll
coll.find( { name:
For more information on specifying the<query>cri-
teria, seeQuery Documents(page 87).
db.collection.find( <query>,
<projection> )
Find documents matching the<query>criteria and re-
turn just specic elds in the<projection>.
The following example selects all documents from the
collection but returns only thenameeld and the_id
eld. The_idis always returned unless explicitly spec-
ied to not return.
coll
coll.find( { },
{ name: true}
);
For more information on specifying the
<projection>, seeLimit Fields to Return from
a Query(page 94).
db.collection.find().sort( <sort
order> )
Return results in the specied<sort order>.
The following example selects all documents from the
collection and returns the results sorted by thename
eld in ascending order (1). Use-1for descending or-
der:
coll
coll.find().sort( { name:
db.collection.find( <query> ).sort(
<sort order> )
Return the documents matching the<query>criteria
in the specied<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 perfor-
mance.
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.
Thecount()ignoreslimit()andskip(). For
example, if 100 records match but the limit is 10,
count()will return 100. This will be faster than it-
erating 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 doc-
ument in theuserscollection with the
nameeld matches to"Joe":
coll
coll.findOne( { name:
Internally, thefindOne()method is thefind()
method with alimit(1).
264 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
SeeQuery Documents(page 87) andRead Operations(page 55) documentation for more information and examples.
Seehttp://docs.mongodb.org/manualreference/operator to specify other query operators.
Error Checking Methods
Changed in version 2.6.
Themongoshell write methods now integrates theWrite Concern(page 72) directly into the method execution rather
than with a separatedb.getLastError()method. As such, the write methods now return aWriteResult()
object that contains the results of the operation, including any write errors and write concern errors.
Previous versions useddb.getLastError()anddb.getLastErrorObj() methods to return error informa-
tion.
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>specied. 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 innoauthmode.
db.fromColl.renameCollection(<toColl>)Rename collection fromfromCollto<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 alsoadministrative database methodsfor a full list of methods.
Opening Additional Connections
You can create new connections within themongoshell.
The following table displays the methods to create the connections:
JavaScript Connection Create Methods Description
db"<host><:port>/<dbname>")
Open a new database connection.
conn newMongo()
db"dbname")
Open a connection to a new server usingnew
Mongo().
UsegetDB()method of the connection to select a
database.
See alsoOpening New Connections(page 253) for more information on the opening new connections from themongo
shell.
5.2. Administration Tutorials 265

MongoDB Documentation, Release 2.6.4
Miscellaneous
The following table displays some miscellaneous methods:
Method Description
Object.bsonsize(<document>) Prints theBSONsize of a <document> in bytes
See the
90
for a full list of JavaScript methods .
Additional Resources
Consider the following reference material that addresses themongoshell and its interface:
http://docs.mongodb.org/manualreference/program/mongo
http://docs.mongodb.org/manualreference/method
http://docs.mongodb.org/manualreference/operator
http://docs.mongodb.org/manualreference/command
Aggregation Reference(page 419)
Additionally, the MongoDB source code repository includes a
91
which contains numerousmongo
shell scripts.
See also:
The MongoDB Manual contains administrative documentation and tutorials though out several sections. SeeReplica
Set Tutorials(page 543) andSharded Cluster Tutorials(page 634) for additional tutorials and information.
5.3
UNIX ulimit Settings(page 266)Describes user resources limits (i.e.ulimit) and introduces the considerations
and optimal congurations for systems that run MongoDB deployments.
System Collections(page 270)Introduces the internal collections that MongoDB uses to track per-database metadata,
including indexes, collections, and authentication credentials.
Database Proler Output(page 271)Describes the data collected by MongoDB's operation proler, which intro-
spects operations and reports data for analysis on performance and behavior.
Journaling Mechanics(page 275)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(page 276)Lists the unique codes returned bymongosandmongodprocesses upon exit.
5.3.1 ulimitSettings
Most UNIX-like operating systems, including Linux and OS X, provide ways to limit and control the usage of system
resources such as threads, les, 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 overridesulimitset-
90
http://api.mongodb.org/js/index.html
91
https://github.com/mongodb/mongo/tree/master/jstests/
266 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
tings. Create a le named/etc/security/limits.d/99-mongodb-nproc.conf with newsoft nproc
andhard nprocvalues to increase the process limit. See/etc/security/limits.d/90-nproc.conf le
as an example.
Resource Utilization
mongodandmongoseach use threads and le descriptors to track connections and manage internal operations. This
section outlines the general resource utilization patterns for MongoDB. Use these gures in combination with the
actual information about your deployment and its use to determine idealulimitsettings.
Generally, allmongodandmongosinstances:
anda thread.
pthreadas a system process.
mongod
mongodinstance.
mongodinstance whenstorage.journal.enabled is
true.
mongodmaintains a connection to all other members of the set.
mongoduses background threads for a number of internal processes, includingTTL collections(page 198), replica-
tion, and replica set health checks, which may require a small number of additional resources.
mongos
In addition to the threads and le descriptors for client connections,mongosmust maintain connects to all cong
servers and all shards, which includes all members of all replica sets.
Formongos, consider the following behaviors:
mongosinstances maintain a connection pool to each shard so that themongoscan reuse connections and
quickly fulll requests without needing to create new connections.
maxIncomingConnections run-time option.
By restricting the number of incoming connections you can prevent a cascade effect where themongoscreates
too many connections on themongodinstances.
Note:Changed in version 2.6: MongoDB removed the upward limit on themaxIncomingConnections
setting.
Review and Set Resource Limits
ulimit
Note:Both the hard and the softulimitaffect MongoDB's performance. The hardulimitrefers 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 hardulimit. In contrast, the softulimitis the limit that is actually enforced for a session or
process, but any process can increase it up to hardulimitmaximum.
5.3. Administration Reference 267

MongoDB Documentation, Release 2.6.4
A low softulimitcan causecan't create new thread, closing connection errors if the number
of connections grows too high. For this reason, it is extremely important to setbothulimitvalues to the recom-
mended values.
ulimitwill modify both hard and soft values unless the-Hor-Smodiers are specied when modifying limit
values.
You can use theulimitcommand at the system prompt to check system limits, as in the following example:
$
-t: cpuseconds)
-f: file sizeblocks)
-d: data seg sizekbytes)
-s: stack sizekbytes)
-c: core file sizeblocks)
-m: residentkbytes)
-u: processes 192276
-n: file descriptors 21000
-l: locked-in-memory sizekb)
-v: address spacekb)
-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
ulimitrefers to the per-userlimitations for various resources. Therefore, if yourmongodinstance executes as
a user that is also running multiple processes, or multiplemongodprocesses, you might see contention for these
resources. Also, be aware that theprocessesvalue (i.e.-u) refers to the combined number of distinct processes
and sub-process threads.
You can changeulimitsettings by issuing a command in the following form:
ulimit
For many distributions of Linux you can change values by substituting the-noption for any possible value in the
output ofulimit -a. On OS X, use thelaunchctl limitcommand. See your operating system documentation
for the precise procedure for changing system limits on running systems.
Note:After changing theulimitsettings, youmustrestart the process to take advantage of the modied settings.
You can use thehttp://docs.mongodb.org/manualproc le system to see the current limitations on a
running process.
Depending on your system's conguration, and default settings, any change to system limits made usingulimit
may revert following system a system restart. Check your distribution and operating system documentation for more
information.
RecommendedulimitSettings
Every deployment may have unique requirements and settings; however, the following thresholds and settings are
particularly important formongodandmongosdeployments:
-f(le size):unlimited
-t(cpu time):unlimited
268 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
-v(virtual memory):unlimited
92
-n(open les):64000
-m(memory size):unlimited
1
-u(processes/threads):64000
Always remember to restart yourmongodandmongosinstances after changing theulimitsettings 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 startmongodand/or
mongosinstances as Upstart services. You can do this by usinglimitstanzas
94
.
Specify theRecommended ulimit Settings(page 268), 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)
Eachlimitstanza sets the soft limit to the rst value specied and the hard limit to the second.
After after changinglimitstanzas, ensure that the changes take effect by restarting the application services, using
the following form:
restart <service name>
Linux distributions usingsystemd
For Linux distributions that usesystemd, you can specify limits within the[Service]sections of service scripts
if you startmongodand/ormongosinstances assystemdservices. You can do this by using
tives
95
.
Specify theRecommended ulimit Settings(page 268), 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
92
If you limit virtual or resident memory size on a system running MongoDB the operating system will refuse to honor additional allocation
requests.
93
The-mparameter toulimithas no effect on Linux systems with kernel versions more recent than 2.4.30. You may omit-mif you wish.
94
http://upstart.ubuntu.com/wiki/Stanzas#limit
95
http://www.freedesktop.org/software/systemd/man/systemd.exec.html#LimitCPU=
5.3. Administration Reference 269

MongoDB Documentation, Release 2.6.4
Eachsystemdlimit directive sets both the hard and soft limits to the value specied.
After after changinglimitstanzas, ensure that the changes take effect by restarting the application services, using
the following form:
systemctl restart <service name>
/procFile System
Note:This section applies only to Linux operating systems.
Thehttp://docs.mongodb.org/manualproc le-system stores the per-process limits in the le system ob-
ject located at/proc/<pid>/limits, where<pid>is the process'sPIDor process identier. You can use the
followingbashfunction to return the content of thelimitsobject for a process or processes with a given name:
return-limits(){
forprocess in; do
process_pids=ps -C
if[; then
echo
else
forpid in; do
echo
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
5.3.2
Synopsis
MongoDB stores system information in collections that use the<database>.system.*namespace, which Mon-
goDB reserves for internal use. Do not create collections that begin withsystem.
MongoDB also stores some additional instance-local metadata in thelocal database(page 598), specically for repli-
cation purposes.
Collections
System collections include these collections stored in theadmindatabase:
270 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
admin.system.roles
New in version 2.6.
Theadmin.system.roles (page 270) collection stores custom roles that administrators create and assign
to users to provide access to specic resources.
admin.system.users
Changed in version 2.6.
Theadmin.system.users (page 271) collection stores the user's authentication credentials as well as any
roles assigned to the user. Users may dene authorization roles in theadmin.system.roles (page 270)
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 (page 271) collection contains information about all of the
database's collections. Additional namespace metadata exists in thedatabase.nsles and is opaque to
database users.
<database>.system.indexes
The<database>.system.indexes (page 271) collection lists all the indexes in the database. Add and
remove data from this collection via theensureIndex()anddropIndex()
<database>.system.profile
The<database>.system.profile (page 271) collection stores database proling information. For in-
formation on proling, seeDatabase Proling(page 180).
<database>.system.js
The<database>.system.js (page 271) collection holds special JavaScript code for use inserver side
JavaScript(page 249). SeeStore a JavaScript Function on the Server(page 217) for more information.
5.3.3
The database proler captures data information about read and write operations, cursor operations, and database com-
mands. To congure the database prole and set the thresholds for capturing prole data, see theAnalyze Performance
of Database Operations(page 210) section.
The database proler writes data in thesystem.profile(page 271) collection, which is acapped collection. To
view the proler's output, use normal MongoDB queries on thesystem.profile(page 271) collection.
Note:Because the database proler writes data to thesystem.profile(page 271) collection in a database, the
proler will prole some write activity, even for databases that are otherwise read-only.
Examplesystem.profileDocument
The documents in thesystem.profile(page 271) collection have the following form. This example document
reects an update operation:
{
"ts""2012-12-10T19:31:28.977Z"),
"op",
"ns",
5.3. Administration Reference 271

MongoDB Documentation, Release 2.6.4
"query"
"name"
},
"updateobj"
"$set"
"likes"
"basketball",
"trekking"
]
}
},
"nscanned",
"scanAndOrder" true,
"moved" true,
"nmoved",
"nupdated",
"keyUpdates",
"numYield",
"lockStats"
"timeLockedMicros"
"r"0),
"w"258)
},
"timeAcquiringMicros"
"r"0),
"w"7)
}
},
"millis",
"client",
"user"
}
Output Reference
For any single operation, the documents created by the database proler will include a subset of the following elds.
The precise selection of elds 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
Thenamespacethe operation targets. Namespaces in MongoDB take the form of thedatabase, followed by a
dot (.), followed by the name of thecollection.
272 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
system.profile.query
Thequery document(page 87) used.
system.profile.command
The command operation.
system.profile.updateobj
The<update>document passed in during anupdate(page 67) operation.
system.profile.cursorid
The ID of the cursor accessed by agetmoreoperation.
system.profile.ntoreturn
Changed in version 2.2: In 2.0, MongoDB includes this eld forqueryandcommandoperations. In 2.2, this
information MongoDB also includes this eld forgetmoreoperations.
The number of documents the operation specied to return. For example, theprofilecommand would
return one document (a results document) so thentoreturn(page 273) value would be1. Thelimit(5)
command would return ve documents so thentoreturn(page 273) value would be5.
If thentoreturn(page 273) value is0, the command did not specify a number of documents to return, as
would be the case with a simplefind()command with no limit specied.
system.profile.ntoskip
New in version 2.2.
The number of documents theskip()method specied to skip.
system.profile.nscanned
The number of documents that MongoDB scans in theindex(page 431) in order to carry out the operation.
In general, ifnscanned(page 273) is much higher thannreturned(page 274), the database is scanning
many objects to nd the target objects. Consider creating an index to improve this.
system.profile.scanAndOrder
scanAndOrder(page 273) is a boolean that istruewhen a querycannotuse the order of documents in the
index for returning sorted results: MongoDB must sort the documents after it receives the documents from a
cursor.
IfscanAndOrder(page 273) isfalse, MongoDBcanuse the order of the documents in an index to return
sorted results.
system.profile.moved
This eld appears with a value oftruewhen an update operation moved one or more documents to a new
location on disk. If the operation did not result in a move, this eld 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 eld appears only if the operation resulted in a
move. The eld's implicit value is zero, and the eld 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.
5.3. Administration Reference 273

MongoDB Documentation, Release 2.6.4
The number ofindex(page 431) 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, seethe FAQ on when operations yield(page 703).
system.profile.lockStats
New in version 2.2.
The time in microseconds the operation spent acquiring and holding locks. This eld reports data for the
following lock types:
R- global read lock
W- global write lock
r- database-specic read lock
w- database-specic write lock
system.profile.lockStats. timeLockedMicros
The time in microseconds the operation held a specic lock. For operations that require more than one
lock, like those that lock thelocaldatabase to update theoplog, this value may be longer than the total
length of the operation (i.e.millis(page 274).)
system.profile.lockStats. timeAcquiringMicros
The time in microseconds the operation spent waiting to acquire a specic 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 largeresponseLength(page 274) can affect
performance. To limit the size of the result document for a query operation, you can use any of the following:
Projections(page 94)
The limit() method
The batchSize() method
Note:When MongoDB writes query prole information to the log, theresponseLength(page 274) value
is in a eld namedreslen.
system.profile.millis
The time in milliseconds from the perspective of themongodfrom 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 asdb.eval(), the client is0.0.0.0:0instead of an actual client.
system.profile.user
The authenticated user who ran the operation.
274 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
5.3.4
When running with journaling, MongoDB stores and applieswrite operations(page 67) in memory and in the on-disk
journal before the changes are present in the data les on disk. This document discusses the implementation and
mechanics of journaling in MongoDB systems. SeeManage Journaling(page 215) for information on conguring,
tuning, and managing journaling.
Journal Files
With journaling enabled, MongoDB creates a journal subdirectory within the directory dened bydbPath, which is
/data/dbby default. The journal directory holds journal les, which contain write-ahead redo logs. The directory
also holds a last-sequence-number le. A clean shutdown removes all the les in the journal directory. A dirty shut-
down (crash) leaves les in the journal directory; these are used to automatically recover the database to a consistent
state when the mongod process is restarted.
Journal les are append-only les and have le names prexed withj._. When a journal le holds 1 gigabyte of data,
MongoDB creates a new journal le. Once MongoDB applies all the write operations in a particular journal le to the
database data les, it deletes the le, as it is no longer needed for recovery purposes. Unless you writemanybytes of
data per second, the journal directory should contain only two or three journal les.
You can use thestorage.smallFiles run time option when startingmongodto limit the size of each journal
le to 128 megabytes, if you prefer.
To speed the frequent sequential writes that occur to the current journal le, you can ensure that the journal directory
is on a different lesystem from the database data les.
Important:If you place the journal on a different lesystem from your data les youcannotuse a lesystem snapshot
alone to capture valid backups of adbPathdirectory. In this case, usefsyncLock()to ensure that database les
are consistent before the snapshot andfsyncUnlock()once the snapshot is complete.
Note:Depending on your lesystem, you might experience a preallocation lag the rst time you start amongod
instance with journaling enabled.
MongoDB may preallocate journal les if themongodprocess determines that it is more efcient to preallocate
journal les than create new journal les 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, seeAvoid Preallocation Lag(page 216).
Storage Views used in Journaling
Journaling adds three internal storage views to MongoDB.
Theshared viewstores modied data for upload to the MongoDB data les. Theshared viewis the only view
with direct access to the MongoDB data les. When running with journaling,mongodasks the operating system to
map your existing on-disk data les to theshared viewvirtual memory view. The operating system maps the les
but does not load them. MongoDB later loads data les into theshared viewas needed.
Theprivate viewstores data for use withread operations(page 55). Theprivate viewis the rst place
MongoDB applies newwrite operations(page 67). Upon a journal commit, MongoDB copies the changes made in
theprivate viewto theshared view, where they are then available for uploading to the database data les.
The journal is an on-disk view that stores new write operations after MongoDB applies the operation to theprivate
viewbut before applying them to the data les. The journal provides durability. If themongodinstance were to
5.3. Administration Reference 275

MongoDB Documentation, Release 2.6.4
crash without having applied the writes to the data les, the journal could replay the writes to theshared viewfor
eventual upload to the data les.
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
commitIntervalMsfor information on the default commit interval.
Journaling stores raw operations that allow MongoDB to reconstruct the following:

Aswrite operations(page 67) occur, MongoDB writes the data to theprivate viewin 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 les.
MongoDB next applies the journal's write operations to theshared view. At this point, theshared view
becomes inconsistent with the data les.
At default intervals of 60 seconds, MongoDB asks the operating system to ush theshared viewto disk. This
brings the data les up-to-date with the latest write operations. The operating system may choose to ush theshared
viewto disk at a higher frequency than 60 seconds, particularly if the system is low on free memory.
When MongoDB ushes write operations to the data les, MongoDB notes which journal writes have been ushed.
Once a journal le contains only ushed writes, it is no longer needed for recovery, and MongoDB either deletes it or
recycles it for a new journal le.
As part of journaling, MongoDB routinely asks the operating system to remap theshared viewto theprivate
view, in order to save physical RAM. Upon a new remapping, the operating system knows that physical memory
pages can be shared between theshared viewand theprivate viewmappings.
Note:The interaction between theshared viewand the on-disk data les is similar to how MongoDB works
withoutjournaling, which is that MongoDB asks the operating system to ush in-memory changes back to the data
les every 60 seconds.
5.3.5
MongoDB will return one of the following codes and statuses when exiting. Use this guide to interpret logs and when
troubleshooting issues withmongodandmongosinstances.
0
Returned by MongoDB applications upon successful exit.
2
The specied options are in error or are incompatible with other options.
3
Returned bymongodif there is a mismatch between hostnames specied on the command line and in the
local.sources(page 600) collection.mongodmay also return this status ifoplogcollection in thelocal
database is not readable.
276 Chapter 5. Administration

MongoDB Documentation, Release 2.6.4
4
The version of the database is different from the version supported by themongod(ormongod.exe) instance.
The instance exits cleanly. Restartmongodwith the--upgradeoption to upgrade the database to the version
supported by thismongodinstance.
5
Returned bymongodif amoveChunkoperation fails to conrm a commit.
12
Returned by themongod.exeprocess 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 le or cannot obtain a lock on a le.
47
MongoDB applications exit cleanly following a large clock skew (32768 milliseconds) event.
48
mongodexits cleanly if the server socket closes. The server socket is on port27017by default, or as specied
to the--portrun-time option.
49
Returned bymongod.exeormongos.exeon Windows when either receives a shutdown message from the
Windows Service Control Manager.
100
Returned bymongodwhen the process throws an uncaught exception.
5.3. Administration Reference 277

MongoDB Documentation, Release 2.6.4
278 Chapter 5. Administration

CHAPTER6
Security
This section outlines basic security and risk management strategies and access control. The included tutorials outline
specic tasks for conguring rewalls, authentication, and system privileges.
Security Introduction(page 279)A high-level introduction to security and MongoDB deployments.
Security Concepts(page 281)The core documentation of security.
Authentication(page 282)Mechanisms for verifying user and instance access to MongoDB.
Authorization(page 285)Control access to MongoDB instances using authorization.
Network Exposure and Security(page 288)Discusses potential security risks related to the network and strate-
gies for decreasing possible network-based attack vectors for MongoDB.
Continue reading fromSecurity Concepts(page 281) for additional documentation of MongoDB's security
features and operation.
Security Tutorials(page 294)Tutorials for enabling and conguring security features for MongoDB.
Security Checklist(page 295)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(page 297)Ensure that the underlying network conguration supports a secure op-
erating environment for MongoDB deployments, and appropriately limits access to MongoDB deploy-
ments.
Access Control Tutorials(page 316)These tutorials describe procedures relevant for the conguration, opera-
tion, and maintenance of MongoDB's access control system.
User and Role Management Tutorials(page 342)MongoDB's access control system provides a exible role-
based access control system that you can use to limit access to MongoDB deployments. The tutorials in
this section describe the conguration an setup of the authorization system.
Continue reading fromSecurity Tutorials(page 294) for additional tutorials that address the use and management
of secure MongoDB deployments.
Create a Vulnerability Report(page 359)Report a vulnerability in MongoDB.
Security Reference(page 360)Reference for security related functions.
6.1
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
279

MongoDB Documentation, Release 2.6.4
implement these controls and restrictions for any MongoDB deployment.
If you are already familiar with security and MongoDB security practices, consider theSecurity Checklist(page 295)
for a collection of recommended actions to protect a MongoDB deployment.
6.1.1
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 ofauthentication mechanisms(page 282) that clients can use to verify their identity.
MongoDB supports two mechanisms: a password-based challenge and response protocol and x.509 certicates. Ad-
ditionally,
1
also provides support forLDAP proxy authentication(page 283) andKerberos au-
thentication(page 283).
SeeAuthentication(page 282) for more information.
6.1.2
Access control, i.e.authorization(page 285), determines a user's access to resources and operations. Clients should
only be able to perform the operations required to fulll 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 enableautho-
rization(page 285), 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 ofactions, or a set of operations, and aresourceupon which
the actions are allowed.
Users may have one or more role that describes their access. MongoDB provides severalbuilt-in roles(page 361) and
users can construct specic roles tailored to clients' actual requirements.
SeeAuthorization(page 285) for more information.
6.1.3
Auditing provides administrators with the ability to verify that the implemented security policies are controlling activ-
ity 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.
SeeAuditing(page 290) for more information.
6.1.4
Transport Encryption
You can use SSL to encrypt all of MongoDB's network trafc. SSL ensures that MongoDB network trafc is only
readable by the intended client.
SeeCongure mongod and mongos for SSL(page 304) for more information.
1
http://www.mongodb.com/products/mongodb-enterprise
280 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
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-eld or per-document basis within the application layer. To encrypt document or eld
level data, write custom encryption and decryption routines or use a commercial solutions such as the
Security Platform
2
.
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 Unied Key Setup (LUKS)LUKS is available for most Linux distributions. For conguration explanation,
see the
3
.
IBM Guardium Data EncryptionIBM Guardium Data Encryption
4
provides support for disk-level encryption for
Linux and Windows operating systems.
Vormetric Data Security PlatformThe
5
provides disk and le-level encryption in
addition to application level encryption.
Bitlocker Drive EncryptionBitlocker Drive Encryption
6
is a feature available on Windows Server 2008 and 2012
that provides disk encryption.
Properly congured disk encryption, when used alongside good security policies that protect relevant accounts, pass-
words, and encryption keys, can help ensure compliance with standards, including HIPAA, PCI-DSS, and FERPA.
6.1.5
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 adefense in depthstrategy.
Hardening MongoDB extends the ideas of least privilege, auditing, and encryption outside of MongoDB. Reducing
risk includes: conguring 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 lesystem required for operation.
6.2
These documents introduce and address concepts and strategies related to security practices in MongoDB deployments.
Authentication(page 282)Mechanisms for verifying user and instance access to MongoDB.
Authorization(page 285)Control access to MongoDB instances using authorization.
2
http://www.vormetric.com/sites/default/les/sb-MongoDB-Letter-2014-0611.pdf
3
https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security_Guide/sect-Security_Guide-
LUKS_Disk_Encryption.html
4
http://www-03.ibm.com/software/products/en/infosphere-guardium-data-encryption
5
http://www.vormetric.com/sites/default/les/sb-MongoDB-Letter-2014-0611.pdf
6
http://technet.microsoft.com/en-us/library/hh831713.aspx
6.2. Security Concepts 281

MongoDB Documentation, Release 2.6.4
Collection-Level Access Control(page 287)Scope privileges to specic collections.
Network Exposure and Security(page 288)Discusses potential security risks related to the network and strategies
for decreasing possible network-based attack vectors for MongoDB.
Security and MongoDB API Interfaces(page 289)Discusses potential risks related to MongoDB's JavaScript,
HTTP and REST interfaces, including strategies to control those risks.
Auditing(page 290)Audit server and client activity formongodandmongosinstances.
Kerberos Authentication(page 291)Kerberos authentication and MongoDB.
6.2.1
Authentication is the process of verifying the identity of a client. When access control, i.e.authorization(page 285),
is enabled, MongoDB requires all clients to authenticate themselves rst in order to determine the access for the client.
Although authentication andauthorization(page 285) are closely connected, authentication is distinct from authoriza-
tion. Authentication veries the identity of a user; authorization determines the veried user's access to resources and
operations.
MongoDB supports a number ofauthentication mechanisms(page 282) that clients can use to verify their identity.
These mechanisms allow MongoDB to integrate into your existing authentication system. SeeAuthentication Mecha-
nisms(page 282) 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(page 284) to their respective replica set or sharded cluster. SeeAuthentication Between
MongoDB Instances(page 284) 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 specic database. Together, the user's name and database serve as a unique identier 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 themongoshell
as a client, you can specify the database for the user with theauthenticationDatabaseoption.
To add and manage user information, MongoDB provides thedb.createUser()method as well as otheruser
management methods. For an example of adding a user to MongoDB, seeAdd a User to a Database(page 344).
MongoDB stores all user information, includingname(page 372),password(page 372), and theuser's
database(page 372), in thesystem.users(page 372) collection in theadmindatabase.
Authentication Mechanisms
MongoDB supports multiple authentication mechanisms. MongoDB's default authentication method is achallenge
and response mechanism (MONGODB-CR)(page 283). MongoDB also supportsx509 certicate authentication
(page 283),LDAP proxy authentication(page 283), andKerberos authentication(page 283).
This section introduces the mechanisms available in MongoDB.
To specify the authentication mechanism to use, seeauthenticationMechanisms .
282 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
MONGODB-CRAuthentication
MONGODB-CRis a challenge-response mechanism that authenticates users through passwords.MONGODB-CRis the
default mechanism.
When you useMONGODB-CRauthentication,MONGODB-CRveries the user against the user'sname(page 372),
password(page 372) anddatabase(page 372). 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.
Usingkey files, you can also useMONGODB-CRauthentication for theinternal member authentication(page 284)
of replica set members and sharded cluster members. The contents of the key les serve as the shared password for
the members. You must store the key le on eachmongodormongosinstance for that replica set or sharded cluster.
The content of the key le is arbitrary but must be the same on allmongodandmongosinstances that connect to
each other.
SeeGenerate a Key File(page 338) for instructions on generating a key le and turning on key le authentication for
members.
x.509 Certicate Authentication
New in version 2.6.
MongoDB supports x.509 certicate authentication for use with a secureSSL connection(page 304).
To authenticate to servers, clients can use x.509 certicates instead of usernames and passwords. SeeClient x.509
Certicate(page 321) for more information.
For membership authentication, members of sharded clusters and replica sets can use x.509 certicates instead of key
les. SeeUse x.509 Certicate for Membership Authentication(page 323) for more information.
Kerberos Authentication
MongoDB Enterprise
7
supports authentication using a Kerberos service. Kerberos is an industry standard authentica-
tion protocol for large client/server systems.
To use MongoDB with Kerberos, you must have a properly congured Kerberos deployment, conguredKerberos
service principals(page 292) for MongoDB, and addedKerberos user principal(page 292) to MongoDB.
SeeKerberos Authentication(page 291) for more information on Kerberos and MongoDB. To congure MongoDB to
use Kerberos authentication, seeCongure MongoDB with Kerberos Authentication on Linux(page 331) andCongure
MongoDB with Kerberos Authentication on Windows(page 334).
LDAP Proxy Authority Authentication
MongoDB Enterprise
8
supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) ser-
vice. SeeAuthenticate Using SASL and LDAP with OpenLDAP(page 329) andAuthenticate Using SASL and LDAP
with ActiveDirectory(page 326).
MongoDB Enterprise for Windows doesnotinclude LDAP support for authentication. However, MongoDB Enterprise
for Linux supports using LDAP authentication with an ActiveDirectory server.
MongoDB doesnotsupport LDAP authentication in mixed sharded cluster deployments that contain both version 2.4
and version 2.6 shards.
7
http://www.mongodb.com/products/mongodb-enterprise
8
http://www.mongodb.com/products/mongodb-enterprise
6.2. Security Concepts 283

MongoDB Documentation, Release 2.6.4
Authentication Behavior
Client Authentication
Clients can authenticate using thechallenge and response(page 283),x.509(page 283),LDAP Proxy(page 283) and
Kerberos(page 283) 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 rst. While clients
can authenticate as multiple users if the users are dened 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.
SeeAuthenticate to a MongoDB Instance or Cluster(page 336) for more information.
Authentication Between MongoDB Instances
You can authenticate members ofreplica setsandsharded clusters. To authenticate members of a single MongoDB
deployment to each other, MongoDB can use thekeyFileandx.509(page 283) mechanisms. UsingkeyFile
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 trafc to reach eachmongodandmongosinstance.
Use your environment's rewall and network routing to ensure that trafconlyfrom clients and other members can
reach yourmongodandmongosinstances. If needed, use virtual private networks (VPNs) to ensure secure connec-
tions over wide area networks (WANs).
Always ensure that:

member.

keyFileon all members to permit authentication.
SeeGenerate a Key File(page 338) for instructions on generating a key le and turning on key le authentication for
members. For an example of using key les for sharded cluster authentication, seeEnable Authentication in a Sharded
Cluster(page 318).
Authentication on Sharded Clusters
In sharded clusters, applications authenticate to directly tomongosinstances, using credentials stored in theadmin
database of thecong 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 themongos.
Changed in version 2.6: Previously, the credentials for authenticating to a database on a cluster resided on theprimary
shard(page 615) for that database.
Some maintenance operations, such ascleanupOrphaned,compact,rs.reconfig(), require direct connec-
tions to specic shards in a sharded cluster. To perform these operations with authentication enabled, you must connect
directly to the shard and authenticate as ashard localadministrative user. To create ashard localadministrative user,
connect directly to the shard and create the user. MongoDB storesshard localusers in theadmindatabase of the shard
itself. Theseshard localusers are completely independent from the users added to the sharded cluster viamongos.
Shard localusers are local to the shard and are inaccessible bymongos. Direct connections to a shard should only be
for shard-specic maintenance and conguration.
284 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Localhost Exception
The localhost exception allows you to enable authorization before creating the rst 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 rst user you create must be
in theadmindatabase with privileges to create other users, such as a user with theuserAdmin(page 363) or
userAdminAnyDatabase (page 368) role. SeeEnable Client Access Control(page 317) andCreate a User Ad-
ministrator(page 343) 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 cong servers
andclients access viamongosinstances.
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, usesetParameterto set the
enableLocalhostAuthBypass parameter to0during startup.
6.2.2
MongoDB employs Role-Based Access Control (RBAC) to govern access to a MongoDB system. A user is granted
one or moreroles(page 285) 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--author
the--keyFileoptions, or if using a conguration le, with thesecurity.authorization or the
security.keyFilesettings.
MongoDB providesbuilt-in roles(page 361), each with a dedicated purpose for a common use case. Examples include
theread(page 362),readWrite(page 362),dbAdmin(page 363), androot(page 368) 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 dened 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 theadmindatabase can include
privileges that apply to all databases or to thecluster(page 374).
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 bothread(page 362)and
readWriteAnyDatabase (page 368) roles on a database, the greater access prevails.
6.2. Security Concepts 285

MongoDB Documentation, Release 2.6.4
Privileges
A privilege consists of a specied resource and the actions permitted on the resource.
A privilegeresource(page 373) is either a database, collection, set of collections, or the cluster. If the cluster, the
afliated actions affect the state of the system rather than a specic database or collection.
Anaction(page 375) is a command or method the user is allowed to perform on the resource. A resource can have
multiple allowed actions. For available actions seePrivilege Actions(page 375).
For example, a privilege that includes theupdate(page 375) 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 theinsert(page 375) action to the privilege.
For privilege syntax, seeadmin.system.roles.privileges (page 370).
Inherited Privileges
A role can include one or more existing roles in its denition, 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 theadmindatabase can inherit
privileges from roles in any database.
User-Dened 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 ofleast privilege. Administrators create and edit roles using therole management commands.
MongoDB scopes a user-dened role to the database in which it is created and uniquely identies the role by the
pairing of its name and its database. MongoDB stores the roles in theadmindatabase'ssystem.roles(page 369)
collection. Do not access this collection directly but instead use therole management commandsto view and edit
custom roles.
Collection-Level Access Control
By creating a role withprivileges(page 286) that are scoped to a specic collection in a particular database, adminis-
trators can implement collection-level access control.
SeeCollection-Level Access Control(page 287) for more information.
Users
MongoDB stores user credentials in the protectedadmin.system.users (page 271). Use theuser management
methodsto view and edit user credentials.
Role Assignment to Users
User administrators create the users that access the system's databases. MongoDB'suser management commandslet
administrators create users and assign them roles.
286 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
MongoDB scopes a user to the database in which the user is created. MongoDB stores all user denitions in theadmin
database, no matter which database the user is scoped to. MongoDB stores users in theadmindatabase'ssystem.users
collection(page 372). Do not access this collection directly but instead use theuser management commands.
The rst role assigned in a database should be eitheruserAdmin(page 363) oruserAdminAnyDatabase
(page 368). This user can then create all other users in the system. SeeCreate a User Administrator(page 343).
Protect the User and Role Collections
MongoDB stores role and user data in the protected admin.system.roles (page 270) and
admin.system.users (page 271) collections, which are only accessible using theuser management meth-
ods.
If you disable access control,do notmodify theadmin.system.roles (page 270) andadmin.system.users
(page 271) collections using normalinsert()andupdate()operations.
Additional Information
See the reference section for documentation of allbuilt-in-roles(page 361) and all availableprivilege actions
(page 375). Also consider the reference for the form of theresource documents(page 373).
To create users see theCreate a User Administrator(page 343) andAdd a User to a Database(page 344) tutorials.
6.2.3
Collection-level access control allows administrators to grant users privileges that are scoped to specic collections.
Administrators can implement collection-level access control throughuser-dened roles(page 286). By creating a role
withprivileges(page 286) that are scoped to a specic collection in a particular database, administrators can provision
users with roles that grant privileges on a collection level.
Privileges and Scope
A privilege consists ofactions(page 375) and theresources(page 373) upon which the actions are permissible; i.e.
the resources dene the scope of the actions for that privilege.
By specifying both the database and the collection in theresource document(page 373) for a privilege, administrator
can limit the privilege actions just to a specic collection in a specic database. Each privilege action in a role can be
scoped to a different collection.
For example, a user dened role can contain the following privileges:
privileges:
{ resource::, collection::,,
{ resource::, collection::
]
The rst privilege scopes its actions to theinventorycollection of theproductsdatabase. The second privilege
scopes its actions to theorderscollection of theproductsdatabase.
Additional Information
For more information on user-dened roles and MongoDB authorization model, seeAuthorization(page 285). For a
tutorial on creating user-dened roles, seeCreate a Role(page 347).
6.2. Security Concepts 287

MongoDB Documentation, Release 2.6.4
6.2.4
By default, MongoDB programs (i.e.mongosandmongod) 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.
Conguration Options
You can limit the network exposure with the followingmongodandmongosconguration options:enabled,
net.http.RESTInterfaceEnabled ,bindIp, andport. You can use aconfiguration file to specify
these settings.
nohttpinterface
Theenabledsetting formongodandmongosinstances disables the home status page.
Changed in version 2.6: Themongodandmongosinstances run with the http interfacedisabledby default.
The status interface is read-only by default, and the default port for the status page is28017. Authentication does not
control or affect access to this interface.
Important:Disable this interface for production deployments. If youenablethis interface, you should only allow
trusted clients to access this port. SeeFirewalls(page 289).
rest
Thenet.http.RESTInterfaceEnabled setting formongodenables a fully interactive administrativeREST
interface, which isdisabledby default. Thenet.http.RESTInterfaceEnabled conguration makes the http
status interface
9
, which is read-only by default, fully interactive. Use thenet.http.RESTInterfaceEnabled
setting with theenabledsetting.
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 asmongod --rest --httpinterface .
Important:Disable this option for production deployments. Ifdoyou leave this interface enabled, you should only
allow trusted clients to access this port.
bind_ip
ThebindIpsetting formongodandmongosinstances limits the network interfaces on which MongoDB programs
will listen for incoming connections. You can also specify a number of interfaces by passingbindIpa comma
separated list of IP addresses. You can use themongod --bind_ipandmongos --bind_ipoption on the
command line at run time to limit the network accessibility of a MongoDB program.
Important:Make sure that yourmongodandmongosinstances 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.
9
Starting in version 2.6, http interface isdisabledby default.
288 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
port
Theportsetting formongodandmongosinstances changes the main port on which themongodormongos
instance listens for connections. The default port is27017. Changing the port does not meaningfully reduce risk or
limit exposure. You may also specify this option on the command line asmongod --portormongos --port.
Settingportalso indirectly sets the port for the HTTP status interface, which is always available on the port numbered
1000greater than the primarymongodport.
Only allow trusted clients to connect to the port for themongodandmongosinstances. SeeFirewalls(page 289).
See alsoSecurity Considerations(page 184) andDefault MongoDB Port(page 380).
Firewalls
Firewalls allow administrators to lter 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 trafc
on a specic port to specic systems, and limiting incoming trafc from untrusted hosts.
On Linux systems, theiptablesinterface provides access to the underlyingnetfilterrewall. On Windows
systems,netshcommand line interface provides access to the underlying Windows Firewall. For additional infor-
mation about rewall conguration, seeCongure Linux iptables Firewall for MongoDB(page 297) andCongure
Windows netsh Firewall for MongoDB(page 300).
For best results and to minimize overall exposure, ensure thatonlytrafc from trusted sources can reachmongodand
mongosinstances and that themongodandmongosinstances can only connect to trusted outputs.
See also:
For MongoDB deployments on Amazon's web services, see the
10
page, which addresses Amazon's
Security Groups and other EC2-specic 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 conguration and implementation, VPNs provide for certicate validation and a choice of encryption
protocols, which requires a rigorous level of authentication and identication 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.
6.2.5
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 themongoShell
The following JavaScript evaluation behaviors of themongoshell represents risk exposures.
10
http://docs.mongodb.org/ecosystem/platforms/amazon-ec2
6.2. Security Concepts 289

MongoDB Documentation, Release 2.6.4
JavaScript Expression or JavaScript File
Themongoprogram can evaluate JavaScript expressions using the command line--evaloption. Also, themongo
program can evaluate a JavaScript le (.js) passed directly to it (e.g.mongo someFile.js).
Because themongoprogram evaluates the JavaScript directly, inputs should only come from trusted sources.
.mongorc.jsFile
If a.mongorc.jsle exists
11
, themongoshell will evaluate a.mongorc.jsle before starting. You can disable
this behavior by passing themongo --norcoption.
HTTP Status Interface
The HTTP status interface provides a web-based interface that includes a variety of operational data, logs, and status
reports regarding themongodormongosinstance. The HTTP interface is always available on the port numbered
1000greater than the primarymongodport. By default, the HTTP interface port is28017, but is indirectly set using
theportoption which allows you to congure the primarymongodport.
Without thenet.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 theenabledrun
time option or the--nohttpinterfacecommand line option. See alsoConguration Options(page 288).
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 adminis-
trative access, and its accessibility represents a vulnerability in a secure environment. The REST interface isdisabled
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 withauthorizationenabled.
See the following documents for instructions on restricting access to the REST API interface:
Congure Linux iptables Firewall for MongoDB(page 297)
Congure Windows netsh Firewall for MongoDB(page 300)
6.2.6
New in version 2.6.
MongoDB Enterprise includes an auditing capability formongodandmongosinstances. 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, thesyslog, a JSON le, or a BSON le. For details on the audit log
messages, seeSystem Event Audit Messages(page 380).
11
On Linux and Unix systems,mongoreads the.mongorc.jsle from$HOME/.mongorc.js(i.e.~/.mongorc.js). On Windows,
mongo.exereads the.mongorc.jsle from%HOME%.mongorc.jsor%HOMEDRIVE%%HOMEPATH% .mongorc.js.
290 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Audit Events and Filter
The auditing system can record the following operations:

SeeEvent Actions, Details, and Results(page 381) for the specic actions recorded.
By default, the auditing system records all these operations; however, you can congure the--auditFilteroption
to restrict the events captured.
SeeCongure System Events Auditing(page 356) to enable and congure auditing for MongoDB Enterprise. To set
up lters, seeFilter Events(page 358).
Audit Guarantee
The auditing system writes every audit event
12
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 modication
to data, MongoDB will always write the audit event to diskbeforewriting to thejournalfor 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 runs with thejournalingenabled.
Warning:MongoDB may lose eventsifthe server terminates before it commits the events to the audit log.
The client may receive conrmation 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 ushes.
6.2.7
New in version 2.4.
Overview
MongoDB Enterprise provides support for Kerberos authentication of MongoDB clients tomongodandmongos.
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.
12
Audit conguration can include alter(page 358) to limit events to audit.
6.2. Security Concepts 291

MongoDB Documentation, Release 2.6.4
Principals belong to administrative units calledrealms. 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 specic 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 conguration of MongoDB for Kerberos support, two kinds of principal names are of interest:user principals
(page 292) andservice principals(page 292).
User PrincipalTo authenticate using Kerberos, you must add the Kerberos user principals to MongoDB to the
$externaldatabase. 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
$externaldatabase.
For examples of adding a user to MongoDB as well as authenticating as that user, seeCongure MongoDB with
Kerberos Authentication on Linux(page 331) andCongure MongoDB with Kerberos Authentication on Windows
(page 334).
See also:
http://docs.mongodb.org/manualreference/command/nav-user-management for general in-
formation regarding creating and managing users in MongoDB.
Service PrincipalEvery MongoDBmongodandmongosinstance (ormongod.exeormongos.exeon Win-
dows) must have an associated service principal. Service principal names have the form:
<service>/<fully qualified domain name>@<KERBEROS REALM>
For MongoDB, the<service>defaults tomongodb. For example, ifm1.example.comis a MongoDB server,
andexample.commaintains theEXAMPLE.COMKerberos realm, thenm1should have the service principal name
mongodb/[email protected] .
To specify a different value for<service>, useserviceNameduring the start up ofmongodormongos(or
mongod.exeormongos.exe).mongoshell or other clients may also specify a different service principal name
usingserviceName.
Service principal names must be reachable over the network using the fully qualied domain name (FQDN) part of its
service principal name.
By default, Kerberos attempts to identify hosts using the/etc/kerb5.confle before using DNS to resolve hosts.
On Windows, if running MongoDB as a service, seeAssign Service Principal Name to MongoDB Windows Service
(page 336).
Linux Keytab Files
Linux systems can store Kerberos authentication keys for aservice principal(page 292) inkeytables. Each Kerber-
izedmongodandmongosinstance running on Linux must have access to a keytab le containing keys for itsservice
principal(page 292).
To keep keytab les secure, use le permissions that restrict access to only the user that runs themongodormongos
process.
292 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Tickets
On Linux, MongoDB clients can use Kerberos'skinitprogram to initialize a credential cache for authenticating the
user principal to servers.
Windows Active Directory
Unlike on Linux systems,mongodandmongosinstances running on Windows do not require access to keytab
les. Instead, themongodandmongosinstances read their server credentials from a credential store specic to the
operating system.
However, from the Windows Active Directory, you can export a keytab le for use on Linux systems. See
13
for more information.
Authenticate With Kerberos
To congure MongoDB for Kerberos support and authenticate, seeCongure MongoDB with Kerberos Authentication
on Linux(page 331) andCongure MongoDB with Kerberos Authentication on Windows(page 334).
Operational Considerations
The HTTP Console
The MongoDB
14
interface does not support Kerberos authentication.
DNS
Each host that runs amongodormongosinstance must have bothAandPTRDNS records to provide forward and
reverse lookup.
WithoutAandPTRDNS records, the host cannot resolve the components of the Kerberos domain or the Key Distri-
bution Center (KDC).
System Time Synchronization
To successfully authenticate, the system time for eachmongodandmongosinstance 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:

15
13
http://technet.microsoft.com/en-us/library/cc753771.aspx
14
http://docs.mongodb.org/ecosystem/tools/http-interfaces/#http-console
15
http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-java-driver/
6.2. Security Concepts 293

MongoDB Documentation, Release 2.6.4

16

17

18
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 theIncorporate Additional Authentication Mechanisms
section inCongure MongoDB with Kerberos Authentication on Linux(page 331) andCongure MongoDB with
Kerberos Authentication on Windows(page 334) for details.
6.3
The following tutorials provide instructions for enabling and using the security features available in MongoDB.
Security Checklist(page 295)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(page 297)Ensure that the underlying network conguration supports a secure operating
environment for MongoDB deployments, and appropriately limits access to MongoDB deployments.
Congure Linux iptables Firewall for MongoDB(page 297)Basic rewall conguration patterns and exam-
ples foriptableson Linux systems.
Congure Windows netsh Firewall for MongoDB(page 300)Basic rewall conguration patterns and exam-
ples fornetshon Windows systems.
Congure mongod and mongos for SSL(page 304)SSL allows MongoDB clients to support encrypted con-
nections tomongodinstances.
Continue reading fromNetwork Security Tutorials(page 297) for more information on running MongoDB in
secure environments.
Security Deployment Tutorials(page 313)These tutorials describe procedures for deploying MongoDB using au-
thentication and authorization.
Access Control Tutorials(page 316)These tutorials describe procedures relevant for the conguration, operation,
and maintenance of MongoDB's access control system.
Enable Client Access Control(page 317)Describes the process for enabling authentication for MongoDB de-
ployments.
Use x.509 Certicates to Authenticate Clients(page 320)Use x.509 for client authentication.
Use x.509 Certicate for Membership Authentication(page 323)Use x.509 for internal member authentica-
tion for replica sets and sharded clusters.
Congure MongoDB with Kerberos Authentication on Linux(page 331)For MongoDB Enterprise Linux,
describes the process to enable Kerberos-based authentication for MongoDB deployments.
Continue reading fromAccess Control Tutorials(page 316) for additional tutorials on conguring MongoDB's
authentication systems.
16
http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-csharp-driver/
17
http://docs.mongodb.org/ecosystem/tutorial/authenticate-with-cpp-driver/
18
http://api.mongodb.org/python/current/examples/authentication.html
294 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Enable Authentication after Creating the User Administrator(page 319)Describes an alternative process for
enabling authentication for MongoDB deployments.
User and Role Management Tutorials(page 342)MongoDB's access control system provides a exible role-based
access control system that you can use to limit access to MongoDB deployments. The tutorials in this section
describe the conguration an setup of the authorization system.
Add a User to a Database(page 344)Create non-administrator users using MongoDB's role-based authentica-
tion system.
Create a Role(page 347)Create custom role.
Modify a User's Access(page 352)Modify the actions available to a user on specic database resources.
View Roles(page 353)View a role's privileges.
Continue reading fromUser and Role Management Tutorials(page 342) for additional tutorials on managing
users and privileges in MongoDB's authorization system.
Congure System Events Auditing(page 356)Enable and congure MongoDB Enterprise system event auditing fea-
ture.
Create a Vulnerability Report(page 359)Report a vulnerability in MongoDB.
6.3.1
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 authentica-
tion 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.
SeeAuthentication(page 282),Enable Client Access Control(page 317), andEnable Authentication in a Sharded
Cluster(page 318).
Congure Role-Based Access Control
Create roles that dene 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 rst, then create additional users. Create a unique MongoDB user for each person and
application that accesses the system.
SeeAuthorization(page 285),Create a Role(page 347),Create a User Administrator(page 343), andAdd a User to
a Database(page 344).
Encrypt Communication
Congure MongoDB to use SSL for all incoming and outgoing connections. Use SSL to encrypt communication
betweenmongodandmongoscomponents of a MongoDB client, as well as between all applications and MongoDB.
SeeCongure mongod and mongos for SSL(page 304).
6.3. Security Tutorials 295

MongoDB Documentation, Release 2.6.4
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 thebindIpsetting, and seeCongure Linux iptables Firewall for MongoDB(page 297) andCongure Windows
netsh Firewall for MongoDB(page 300).
Audit System Activity
Track access and changes to database congurations and data.
19
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.
SeeAuditing(page 290) andCongure System Events Auditing(page 356).
Encrypt and Protect Data
Encrypt MongoDB data on each host using le-system, device, or physical encryption. Protect MongoDB data using
le-system permissions. MongoDB data includes data les, conguration les, auditing logs, and key les.
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.
SeeInstall MongoDB(page 5) for more information on running MongoDB.
Run MongoDB with Secure Conguration 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--noscriptingoption
on the command line.
Use only the MongoDB wire protocol on production deployments. Donotenable the following, all of which enable
the web server interface:enabled,net.http.JSONPEnabled , andnet.http.RESTInterfaceEnabled .
Leave thesedisabled, unless required for backwards compatibility.
Keep input validation enabled. MongoDB enables input validation by default through thewireObjectCheck
setting. This ensures that all documents stored by themongodinstance are validBSON.
Consider Security Standards Compliance
For applications requiring HIPAA or PCI-DSS compliance, please refer to the
ture
20
to learn more about how you can use the key security capabilities to build compliant application infrastructure.
19
http://www.mongodb.com/products/mongodb-enterprise
20
http://info.mongodb.com/rs/mongodb/images/MongoDB_Security_Architecture_WP.pdf
296 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Contact MongoDB for Further Guidance
MongoDB Inc. provides a Security Technical Implementation Guide (STIG) upon request. Please
21
for
more information.
6.3.2
The following tutorials provide information on handling network security for MongoDB.
Congure Linux iptables Firewall for MongoDB(page 297)Basic rewall conguration patterns and examples for
iptableson Linux systems.
Congure Windows netsh Firewall for MongoDB(page 300)Basic rewall conguration patterns and examples for
netshon Windows systems.
Congure mongod and mongos for SSL(page 304)SSL allows MongoDB clients to support encrypted connections
tomongodinstances.
SSL Conguration for Clients(page 307)Congure clients to connect to MongoDB instances that use SSL.
Upgrade a Cluster to Use SSL(page 311)Rolling upgrade process to use SSL.
Congure MongoDB for FIPS(page 311)Congure for Federal Information Processing Standard (FIPS).
Congure LinuxiptablesFirewall for MongoDB
On contemporary Linux systems, theiptablesprogram provides methods for managing the Linux Kernel's
netfilteror network packet ltering capabilities. These rewall 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 rewall congurations foriptablesrewalls on Linux. Use these approaches as a
starting point for your larger networking organization. For a detailed overview of security practices and risk manage-
ment for MongoDB, seeSecurity Concepts(page 281).
See also:
For MongoDB deployments on Amazon's web services, see the
22
page, which addresses Amazon's
Security Groups and other EC2-specic security features.
Overview
Rules iniptablescongurations fall into chains, which describe the process for ltering and processing specic
streams of trafc. 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:
INPUTControls all incoming trafc.
OUTPUTControls all outgoing trafc.
Given thedefault ports(page 288) of all MongoDB processes, you must congure networking rules that permitonly
required communication between your application and the appropriatemongodandmongosinstances.
Be aware that, by default, the default policy ofiptablesis to allow all connections and trafc unless explicitly
disabled. The conguration changes outlined in this document will create rules that explicitly allow trafc from
specic addresses and on specic ports, using a default policy that drops all trafc that is not explicitly allowed. When
21
http://www.mongodb.com/lp/contact/stig-requests
22
http://docs.mongodb.org/ecosystem/platforms/amazon-ec2
6.3. Security Tutorials 297

MongoDB Documentation, Release 2.6.4
you have properly congured youriptablesrules to allow only the trafc that you want to permit, you canChange
Default Policy to DROP(page 300).
Patterns
This section contains a number of patterns and examples for conguringiptablesfor use with MongoDB deploy-
ments. If you have congured different ports using theportconguration setting, you will need to modify the rules
accordingly.
Trafc to and frommongodInstancesThis pattern is applicable to allmongodinstances running as standalone
instances or as part of areplica set.
The goal of this pattern is to explicitly allow trafc to themongodinstance 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 rst rule allows all incoming trafc from<ip-address>on port27017, which allows the application server to
connect to themongodinstance. The second rule, allows outgoing trafc from themongodto 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 as198.51.100.55/32. If you want to permit
a larger block of possible IP addresses you can allow trafc from ahttp://docs.mongodb.org/manual24
using one of the following specications for the<ip-address>, as follows:
10.10.10.10/24
10.10.10.10/255.255.255.0
Trafc to and frommongosInstancesmongosinstances provide query routing forsharded clusters. Clients
connect tomongosinstances, which behave from the client's perspective asmongodinstances. In turn, themongos
connects to allmongodinstances that are components of the sharded cluster.
Use the sameiptablescommand to allow trafc to and from these instances as you would from themongod
instances that are members of the replica set. Take the conguration outlined in theTrafc to and from mongod
Instances(page 298) section as an example.
Trafc to and from a MongoDB Cong ServerCong servers, host thecong databasethat stores metadata
for sharded clusters. Each production cluster has three cong servers, initiated using themongod --configsvr
option.
23
Cong servers listen for connections on port27019. As a result, add the followingiptablesrules to the
cong server to allow incoming and outgoing connection on port27019, for connection to the other cong 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 ofallthemongodthat provide cong servers.
Additionally, cong servers need to allow incoming connections from all of themongosinstances in the clusterand
allmongodinstances in the cluster. Add rules that resemble the following:
23
You also can run a cong server by using theconfigsvrvalue for theclusterRolesetting in a conguration le.
298 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
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 themongosinstances and the shardmongodinstances.
Trafc to and from a MongoDB Shard ServerFor shard servers, running asmongod --shardsvr
24
Because
the default port number is27018when running with theshardsvrvalue for theclusterRolesetting, you must
congure the followingiptablesrules to allow trafc 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>specication with the IP address of allmongod. This allows you to permit incoming
and outgoing trafc between all shards including constituent replica set members, to:
mongodinstances in the shard's replica sets.
mongodinstances in other shards.
25
Furthermore, shards need to be able make outgoing connections to:
mongosinstances.
mongodinstances in the cong servers.
Create a rule that resembles the following, and replace the<ip-address>with the address of the cong servers
and themongosinstances:
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27018 -m state --state ESTABLISHED -j ACCEPT
Provide Access For Monitoring Systems
1. mongostatdiagnostic tool, when running with the--discoverneeds to be able to reach all compo-
nents of a cluster, including the cong servers, the shard servers, and themongosinstances.
2.
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.
Foralldeployments, you should restrict access to this port toonlythe monitoring instance.
Optional
For cong servermongodinstances running with theshardsvrvalue for theclusterRolesetting, 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 cong servermongodinstances running with theconfigsvrvalue for theclusterRolesetting, the
rule would resemble the following:
iptables -A INPUT -s <ip-address> -p tcp --destination-port 28019 -m state --state NEW,ESTABLISHED -j ACCEPT
24
You can also specify the shard server option with theshardsvrvalue for theclusterRolesetting in the conguration le. Shard members
are also often conventional replica sets using the default port.
25
All shards in a cluster need to be able to communicate with all other shards to facilitatechunkand balancing operations.
6.3. Security Tutorials 299

MongoDB Documentation, Release 2.6.4
Change Default Policy toDROP
The default policy foriptableschains is to allow all trafc. After completing alliptablesconguration changes,
youmustchange the default policy toDROPso that all trafc 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 MaintainiptablesConguration
This section contains a number of basic operations for managing and usingiptables. There are various front end
tools that automate some aspects ofiptablesconguration, but at the core alliptablesfront ends provide the
same basic functionality:
Make alliptablesRules PersistentBy default alliptablesrules are only stored in memory. When your
system restarts, your rewall rules will revert to their defaults. When you have tested a rule set and have guaranteed
that it effectively controls trafc 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 theiptablesrules to
the/etc/iptables.conf le:
iptables-save > /etc/iptables.conf
Run the following operation to restore the network rules:
iptables-restore < /etc/iptables.conf
Place this command in yourrc.localle, or in the/etc/network/if-up.d/iptables le with other
similar operations.
List alliptablesRulesTo list all of currently appliediptablesrules, use the following operation at the system
shell.
iptables --L
Flush alliptablesRulesIf you make a conguration mistake when enteringiptablesrules or simply need to
revert to the default rule set, you can use the following operation at the system shell to ush all rules:
iptables --F
If you've already made youriptablesrules persistent, you will need to repeat the appropriate procedure in the
Make all iptables Rules Persistent(page 300) section.
Congure WindowsnetshFirewall for MongoDB
On Windows Server systems, thenetshprogram provides methods for managing theWindows Firewall. These
rewall 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.
300 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
This document outlines basicWindows Firewallcongurations. 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(page 281).
See also:
Windows Firewall
26
documentation from Microsoft.
Overview
Windows Firewallprocesses rules in an ordered determined by rule type, and parsed in the following order:
1.Windows Service Hardening
2.Connection security rules
3.Authenticated Bypass Rules
4.Block Rules
5.Allow Rules
6.Default Rules
By default, the policy inWindows Firewallallows all outbound connections and blocks all incoming connections.
Given thedefault ports(page 288) of all MongoDB processes, you must congure networking rules that permitonly
required communication between your application and the appropriatemongod.exeandmongos.exeinstances.
The conguration changes outlined in this document will create rules which explicitly allow trafc from specic
addresses and on specic ports, using a default policy that drops all trafc that is not explicitly allowed.
You can congure theWindows Firewallwith using thenetshcommand line tool or through a windows application.
On Windows Server 2008 this application isWindows Firewall With Advanced SecurityinAdministrative Tools. On
previous versions of Windows Server, access theWindows Firewallapplication in theSystem and Securitycontrol
panel.
The procedures in this document use thenetshcommand line tool.
Patterns
This section contains a number of patterns and examples for conguringWindows Firewallfor use with MongoDB
deployments. If you have congured different ports using theportconguration setting, you will need to modify the
rules accordingly.
Trafc to and frommongod.exeInstancesThis pattern is applicable to allmongod.exeinstances running as
standalone instances or as part of areplica set. The goal of this pattern is to explicitly allow trafc to themongod.exe
instance from the application server.
netsh advfirewall firewall add rule name="Open mongod port 27017"=in action=allow protocol=TCP localport=27017
This rule allows all incoming trafc to port27017, which allows the application server to connect to the
mongod.exeinstance.
Windows Firewallalso allows enabling network access for an entire application rather than to a specic port, as in the
following example:
26
http://technet.microsoft.com/en-us/network/bb545423.aspx
6.3. Security Tutorials 301

MongoDB Documentation, Release 2.6.4
netsh advfirewall firewall add rule name="Allowing mongod"=in action=allow program=" C:\mongodbin\mongod.exe"
You can allow all access for amongos.exeserver, with the following invocation:
netsh advfirewall firewall add rule name="Allowing mongos"=in action=allow program=" C:\mongodbin\mongos.exe"
Trafc to and frommongos.exeInstancesmongos.exeinstances provide query routing forsharded clusters.
Clients connect tomongos.exeinstances, which behave from the client's perspective asmongod.exeinstances.
In turn, themongos.execonnects to allmongod.exeinstances that are components of the sharded cluster.
Use the sameWindows Firewallcommand to allow trafc to and from these instances as you would from the
mongod.exeinstances that are members of the replica set.
netsh advfirewall firewall add rule name="Open mongod shard port 27018"=in action=allow protocol=TCP localport=27018
Trafc to and from a MongoDB Cong ServerConguration servers, host thecong databasethat stores meta-
data for sharded clusters. Each production cluster has three conguration servers, initiated using themongod
--configsvroption.
27
Conguration servers listen for connections on port27019. As a result, add the fol-
lowingWindows Firewallrules to the cong server to allow incoming and outgoing connection on port27019, for
connection to the other cong servers.
netsh advfirewall firewall add rule name="Open mongod config svr port 27019"=in action=allow protocol=TCP localport=27019
Additionally, cong servers need to allow incoming connections from all of themongos.exeinstances in the cluster
andallmongod.exeinstances in the cluster. Add rules that resemble the following:
netsh advfirewall firewall add rule name="Open mongod config svr inbound"=in action=allow protocol=TCP remoteip=<ip-address> localport=27019
Replace<ip-address>with the addresses of themongos.exeinstances and the shardmongod.exeinstances.
Trafc to and from a MongoDB Shard ServerFor shard servers, running asmongod --shardsvr
28
Because
the default port number is27018when running with theshardsvrvalue for theclusterRolesetting, you must
congure the followingWindows Firewallrules to allow trafc to and from each shard:
netsh advfirewall firewall add rule name="Open mongod shardsvr inbound"=in action=allow protocol=TCP remoteip=<ip-address> localport=27018
netsh advfirewall firewall add rule name="Open mongod shardsvr outbound"=out action=allow protocol=TCP remoteip=<ip-address> localport=27018
Replace the<ip-address>specication with the IP address of allmongod.exeinstances. This allows you to
permit incoming and outgoing trafc between all shards including constituent replica set members to:
mongod.exeinstances in the shard's replica sets.
mongod.exeinstances in other shards.
29
Furthermore, shards need to be able make outgoing connections to:
mongos.exeinstances.
mongod.exeinstances in the cong servers.
Create a rule that resembles the following, and replace the<ip-address>with the address of the cong servers
and themongos.exeinstances:
27
You also can run a cong server by using theconfigsrvvalue for theclusterRolesetting in a conguration le.
28
You can also specify the shard server option with theshardsvrvalue for theclusterRolesetting in the conguration le. Shard members
are also often conventional replica sets using the default port.
29
All shards in a cluster need to be able to communicate with all other shards to facilitatechunkand balancing operations.
302 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
netsh advfirewall firewall add rule name="Open mongod config svr outbound"=out action=allow protocol=TCP remoteip=<ip-address> localport=27018
Provide Access For Monitoring Systems
1. mongostatdiagnostic tool, when running with the--discoverneeds to be able to reach all compo-
nents of a cluster, including the cong servers, the shard servers, and themongos.exeinstances.
2.
netsh advfirewall firewall add rule name="Open mongod HTTP monitoring inbound"=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.
Foralldeployments, you should restrict access to this port toonlythe monitoring instance.
Optional
For cong servermongodinstances running with theshardsvrvalue for theclusterRolesetting, the
rule would resemble the following:
netsh advfirewall firewall add rule name="Open mongos HTTP monitoring inbound"=in action=allow protocol=TCP remoteip=<ip-address> localport=28018
For cong servermongodinstances running with theconfigsvrvalue for theclusterRolesetting, the
rule would resemble the following:
netsh advfirewall firewall add rule name="Open mongod configsvr HTTP monitoring inbound"=in action=allow protocol=TCP remoteip=<ip-address> localport=28019
Manage and MaintainWindows FirewallCongurations
This section contains a number of basic operations for managing and usingnetsh. While you can use the GUI front
ends to manage theWindows Firewall, all core functionality is accessible is accessible fromnetsh.
Delete allWindows FirewallRulesTo delete the rewall rule allowingmongod.exetrafc:
netsh advfirewall firewall delete rule name="Open mongod port 27017"=tcp localport=27017
netsh advfirewall firewall delete rule name="Open mongod shard port 27018"=tcp localport=27018
List AllWindows FirewallRulesTo return a list of allWindows Firewallrules:
netsh advfirewall firewall show rule name=all
ResetWindows FirewallTo reset theWindows Firewallrules:
netsh advfirewall reset
Backup and RestoreWindows FirewallRulesTo simplify administration of larger collection of systems, you can
export or import rewall systems from different servers) rules very easily on Windows:
Export all rewall rules with the following command:
netsh advfirewall export
6.3. Security Tutorials 303

MongoDB Documentation, Release 2.6.4
Replace"C: emp\MongoDBfw.wfw" with a path of your choosing. You can use a command in the following
form to import a le created using this operation:
netsh advfirewall import
Conguremongodandmongosfor SSL
This document helps you to congure MongoDB to support SSL. MongoDB clients can use SSL to encrypt connec-
tions tomongodandmongosinstances.
Note:The
30
doesnotcontain support for SSL. To use SSL, you must either build
MongoDB locally passing the--ssloption tosconsor use
31
.
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, seeUpgrade
a Cluster to Use SSL(page 311).
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. MongoDB Enterprise for Windows includes support for SSL.
See also:
SSL Conguration for Clients(page 307) to learn about SSL support for Python, Java, Ruby, and other clients.
.pemFile
Before you can use SSL, you must have a.pemle containing a public key certicate and its associated private key.
MongoDB can use any valid SSL certicate issued by a certicate authority, or a self-signed certicate. If you use a
self-signed certicate, although the communications channel will be encrypted, there will benovalidation 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 certicate signed by a trusted certicate authority will permit MongoDB drivers to verify
the server's identity.
In general, avoid using self-signed certicates unless the network is trusted.
Additionally, with regards toauthentication among replica set/sharded cluster members(page 284), in order to mini-
mize exposure of the private key and allow hostname validation, it is advisable to use different certicates on different
servers.
Fortestingpurposes, you can generate a self-signed certicate and private key on a Unix system with a command that
resembles the following:
cd
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 certicate with no passphrase that is valid for 365 days. Once you have
the certicate, concatenate the certicate and private key to a.pemle, as in the following example:
cat mongodb-cert.key mongodb-cert.crt > mongodb.pem
See also:
Use x.509 Certicates to Authenticate Clients(page 320)
30
http://www.mongodb.org/downloads
31
http://www.mongodb.com/products/mongodb-enterprise
304 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Set Upmongodandmongoswith SSL Certicate and Key
To use SSL in your MongoDB deployment, include the following run-time options withmongodandmongos:
net.ssl.modeset torequireSSL. This setting restricts each server to use only SSL encrypted connections.
You can also specify either the valueallowSSLorpreferSSLto set up the use of mixed SSL modes on a
port. Seenet.ssl.modefor details.
PEMKeyfilewith the.pemle that contains the SSL certicate and key.
Consider the following syntax formongod:
mongod --sslMode requireSSL --sslPEMKeyFile <pem>
For example, given an SSL certicate located at/etc/ssl/mongodb.pem , conguremongodto use SSL encryp-
tion for all connections with the following command:
mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem
Note:
<pem>with the full path name to the certicate.
<pem>is encrypted, specify the passphrase. SeeSSL Certicate Passphrase
(page 306).
configuration file, as in the following example:
sslMode
sslPEMKeyFile
To connect, tomongodandmongosinstances using SSL, themongoshell and MongoDB tools must include the
--ssloption. SeeSSL Conguration for Clients(page 307) for more information on connecting tomongodand
mongosrunning with SSL.
See also:
Upgrade a Cluster to Use SSL(page 311)
Set Upmongodandmongoswith Certicate Validation
To set upmongodormongosfor SSL encryption using an SSL certicate signed by a certicate authority, include
the following run-time options during startup:
net.ssl.modeset torequireSSL. This setting restricts each server to use only SSL encrypted connections.
You can also specify either the valueallowSSLorpreferSSLto set up the use of mixed SSL modes on a
port. Seenet.ssl.modefor details.
PEMKeyfilewith the name of the.pemle that contains the signed SSL certicate and key.
CAFilewith the name of the.pemle that contains the root certicate chain from the Certicate Authority.
Consider the following syntax formongod:
mongod --sslMode requireSSL --sslPEMKeyFile <pem> --sslCAFile <ca>
For example, given a signed SSL certicate located at/etc/ssl/mongodb.pem and the certicate authority le
at/etc/ssl/ca.pem, you can conguremongodfor SSL encryption as follows:
6.3. Security Tutorials 305

MongoDB Documentation, Release 2.6.4
mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem
Note:
<pem>le and the<ca>le with either the full path name or the relative path name.
<pem>is encrypted, specify the passphrase. SeeSSL Certicate Passphrase(page 306).
configuration file, as in the following example:
sslMode
sslPEMKeyFile
sslCAFile
To connect, tomongodandmongosinstances using SSL, themongotools must include the both the--ssland
--sslPEMKeyFileoption. SeeSSL Conguration for Clients(page 307) for more information on connecting to
mongodandmongosrunning with SSL.
See also:
Upgrade a Cluster to Use SSL(page 311)
Block Revoked Certicates for ClientsTo prevent clients with revoked certicates from connecting, include the
sslCRLFileto specify a.pemle that contains revoked certicates.
For example, the followingmongodwith SSL conguration includes thesslCRLFilesetting:
mongod --sslMode requireSSL --sslCRLFile /etc/ssl/ca-crl.pem --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem
Clients with revoked certicates in the/etc/ssl/ca-crl.pem will not be able to connect to thismongodin-
stance.
Validate Only if a Client Presents a CerticateIn most cases it is important to ensure that clients present valid
certicates. However, if you have clients that cannot present a client certicate, or are transitioning to using a certicate
authority you may only want to validate certicates from clients that present a certicate.
If you want to bypass validation for clients that don't present certicates, include the
weakCertificateValidation run-time option withmongodandmongos. If the client does not present a
certicate, no validation occurs. These connections, though not validated, are still encrypted using SSL.
For example, consider the followingmongodwith an SSL conguration 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--sslandnocerticate or with the option--ssland avalid
certicate. SeeSSL Conguration for Clients(page 307) for more information on SSL connections for clients.
Note:If the client presents a certicate, the certicate must be a valid certicate.
All connections, including those that have not presented certicates are encrypted using SSL.
SSL Certicate Passphrase
The PEM les forPEMKeyfileandClusterFilemay be encrypted. With encrypted PEM les, you must specify
the passphrase at startup with a command-line or a conguration le option or enter the passphrase when prompted.
306 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Changed in version 2.6: In previous versions, you can only specify the passphrase with a command-line or a congu-
ration le option.
To specify the passphrase in clear text on the command line or in a conguration le, use thePEMKeyPassword
and/or theClusterPasswordoption.
To have MongoDB prompt for the passphrase at the start ofmongodormongosand avoid specifying the passphrase
in clear text, omit thePEMKeyPasswordand/or theClusterPasswordoption. 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 runmongodormongosin 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
SeeCongure MongoDB for FIPS(page 311) for more details.
SSL Conguration for Clients
Clients must have support for SSL to work with amongodor amongosinstance 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:
Congure mongod and mongos for SSL(page 304).
mongoShell SSL Conguration
For SSL connections, you must use themongoshell built with SSL support or distributed with MongoDB Enterprise.
To support SSL,mongohas the following settings:
--ssl
--sslPEMKeyFilewith the name of the.pemle that contains the SSL certicate and key.
--sslCAFilewith the name of the.pemle that contains the certicate from the Certicate Authority (CA).
Warning:If themongoshell or any other tool that connects tomongosormongodis run without
--sslCAFile, it will not attempt to validate server certicates. This results in vulnerability to expired
mongodandmongoscerticates as well as to foreign processes posing as validmongodormongos
instances. Ensure that youalwaysspecify the CA le against which server certicates should be validated
in cases where intrusion is a possibility.
--sslPEMKeyPassword option if the client certicate-key le is encrypted.
Connect to MongoDB Instance with SSL EncryptionTo connect to amongodormongosinstance that requires
only a SSL encryption mode(page 305), startmongoshell with--ssl, as in the following:
mongo --ssl
6.3. Security Tutorials 307

MongoDB Documentation, Release 2.6.4
Connect to MongoDB Instance that Requires Client CerticatesTo connect to amongodormongosthat re-
quiresCA-signed client certicates(page 305), start themongoshell with--ssland the--sslPEMKeyFile
option to specify the signed certicate-key le, as in the following:
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem
Connect to MongoDB Instance that Validates when Presented with a CerticateTo connect to amongodor
mongosinstance thatonly requires valid certicates when the client presents a certicate(page 306), startmongo
shell either with the--sslssl andnocerticate or with the--sslssl and avalidsigned certicate.
For example, ifmongodis running with weak certicate validation, both of the followingmongoshell clients can
connect to thatmongod:
mongo --ssl
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem
Important:If the client presents a certicate, the certicate must be valid.
MMS Monitoring Agent
The Monitoring agent will also have to connect via SSL in order to gather its stats. 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
32
for more information about MMS conguration.
PyMongo
Add the ssl=True parameter to a PyMongoMongoClient
33
to create a MongoDB connection to an SSL Mon-
goDB instance:
from MongoClient
c="mongodb.example.net", port=27017, ssl=True)
To connect to a replica set, use the following operation:
from MongoReplicaSetClient
c"mongodb.example.net:27017",
replicaSet="mysetname", ssl=True)
PyMongo also supports an ssl=true option for theMongoDB URI:
mongodb://mongodb.example.net:27017/?ssl=true
For more details, see the
34
.
32
http://mms.mongodb.com/help
33
http://api.mongodb.org/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient
34
http://docs.mongodb.org/ecosystem/drivers/python
308 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Java
Consider the following example SSLApp.java class le:
import *;
import ;
public {
public main(String args[]) throwsException
MongoClientOptions o newMongoClientOptions.Builder()
.socketFactory(SSLSocketFactory.getDefault())
.build();
MongoClient m newMongoClient("localhost",);
DB db.getDB(;
DBCollection c.getCollection(;
System.out.println(.findOne();
}
}
For more details, see the
35
.
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
require
connection new(localhost,,ssl> true)
Replaceconnectionwith the following if you're connecting to a replica set:
connection.new([localhost:27017],
[localhost:27018],
:ssl> true)
Here,mongodinstance run on localhost:27017 and localhost:27018.
For more details, see the
36
.
Node.JS (node-mongodb-native)
In the
37
driver, use the following invocation to connect to amongodormongosinstance via
SSL:
35
http://docs.mongodb.org/ecosystem/drivers/java
36
http://docs.mongodb.org/ecosystem/drivers/ruby
37
https://github.com/mongodb/node-mongodb-native
6.3. Security Tutorials 309

MongoDB Documentation, Release 2.6.4
vardb1 newDb(MONGODB,newServer("127.0.0.1",,
{ auto_reconnect: false, poolSize:4, ssl: true} );
To connect to a replica set via SSL, use the following form:
varreplSet newReplSetServers( [
newServer( RS.host, RS.ports[1], { auto_reconnect: true} ),
newServer( RS.host, RS.ports[0], { auto_reconnect: true} ),
],
{rs_name:RS.name, ssl: true}
);
For more details, see the
38
.
.NET
As of release 1.6, the .NET driver supports SSL connections withmongodandmongosinstances. To connect using
SSL, you must add an option to the connection string, specifyingssl=trueas follows:
varconnectionString =;
varserver = MongoServer.Create(connectionString);
The .NET driver will validate the certicate against the local trusted certicate store, in addition to providing en-
cryption of the server. This behavior may produce issues during testing if the server uses a self-signed certicate. If
you encounter this issue, add thesslverifycertificate=false option to the connection string to prevent the
.NET driver from validating the certicate, as follows:
varconnectionString =;
varserver = MongoServer.Create(connectionString);
For more details, see the
39
.
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 themongoshell. Seemongo Shell SSL
Conguration(page 307).
38
http://docs.mongodb.org/ecosystem/drivers/node-js
39
http://docs.mongodb.org/ecosystem/drivers/csharp
310 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Upgrade a Cluster to Use SSL
Note:The
40
doesnotcontain support for SSL. To use SSL you can either compile
MongoDB with SSL support or use MongoDB Enterprise. SeeCongure mongod and mongos for SSL(page 304) 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 usingonlySSL encryption, use the following rolling upgrade process:
1. --sslModeset toallowSSL. The--sslMode
allowSSLsetting allows the node to accept both SSL and non-SSL incoming connections. Its connections to
other servers do not use SSL. Include otherSSL options(page 304) as well as any other options that are required
for your specic conguration. 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 theconfiguration file, as in the following example:
sslMode
sslPEMKeyFile
sslCAFile
2. SSL Conguration for Clients(page 307).
3. setParametercommand to update thesslModetopreferSSL.
41
WithpreferSSLas itsnet.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(
Upgrade all nodes of the cluster to these settings.
At this point, all connections should be using SSL.
4. setParametercommand to update thesslModetorequireSSL.
1
WithrequireSSLas itsnet.ssl.mode, the node will reject any non-SSL connections. For example:
db.getSiblingDB(admin).runCommand(
5. configuration file with the appropriate SSL settings to ensure
that upon subsequent restarts, the cluster uses SSL.
Congure MongoDB for FIPS
New in version 2.6.
40
http://www.mongodb.org/downloads
41
As an alternative to using thesetParametercommand, you can also restart the nodes with the appropriate SSL options and values.
6.3. Security Tutorials 311

MongoDB Documentation, Release 2.6.4
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 congure MongoDB to run with a
FIPS 140-2 certied library for OpenSSL. Congure FIPS to run by default or as needed from the command line.
Prerequisites
Only the
42
version supports FIPS mode. Download and install
43
to use
FIPS mode.
Your system must have an OpenSSL library congured with the FIPS 140-2 module. At the command line, type
openssl versionto conrm 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 leastopenssl-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 toprelinkdynamic libraries with pre-assigned addresses. This
process modies the OpenSSL libraries, specicallylibcrypto. The OpenSSL FIPS mode will subsequently fail
the signature check performed upon startup to ensurelibcryptohas not been modied since compilation.
To congure the Linux prelink process to not prelinklibcrypto:
sudo bash -c * >>/etc/prelink.conf.d/openssl-prelink.conf"
Procedure
Congure MongoDB to use SSLSeeCongure mongod and mongos for SSL(page 304) for details about cong-
uring OpenSSL.
Runmongodormongosinstance in FIPS modePerform these steps after youCongure mongod and mongos
for SSL(page 304).
Step 1: Change conguration le.To congure yourmongodormongosinstance to use FIPS mode, shut down
the instance and update the conguration le with the following setting:
net:
ssl:
FIPSMode: true
Step 2: Startmongodormongosinstance with conguration le.For example, run this command to start the
mongodinstance with its conguration le:
mongodconfigetc/mongodb.conf
For more information about conguration les, seehttp://docs.mongodb.org/manualreference/configuration-options .
42
http://www.mongodb.com/products/mongodb-enterprise
43
http://www.mongodb.com/products/mongodb-enterprise
312 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Conrm FIPS mode is runningCheck the server log le for a message FIPS is active:
FIPS 140-2 mode activated
6.3.3
The following tutorials provide information in deploying MongoDB using authentication and authorization.
Deploy Replica Set and Congure Authentication and Authorization(page 313)Congure a replica set that has au-
thentication enabled.
Deploy Replica Set and Congure Authentication and Authorization
Overview
Withauthentication(page 282) enabled, MongoDB forces all clients to identify themselves before granting access to
the server.Authorization(page 285), in turn, allows administrators to dene 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 MongoDBreplica set(page 503) that uses the challenge-response au-
thentication mechanism. The tutorial includes creation of a minimal authorization system to support basic operations.
Considerations
AuthenticationIn this procedure, you will congure MongoDB using the default challenge-response authentication
mechanism, using thekeyFileto supply the password forinter-process authentication(page 284). The content of
the key le is the shared secret used for all internal authentication.
All deployments that enforce authorization checking should have oneuser administratoruser 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.
ArchitectureIn a production, deploy each member of the replica set to its own machine and if possible bind to the
standard MongoDB port of27017. Use thebind_ipoption to ensure that MongoDB listens for connections from
applications on congured addresses.
For a geographically distributed replica sets, ensure that the majority of the set'smongodinstances reside in the
primary site.
SeeReplica Set Deployment Architectures(page 516) for more information.
ConnectivityEnsure that network trafc can pass between all members of the set and all clients in the network
securely and efciently. Consider the following:

a single site over the local area network.

MongoDB port and only from within your deployment.
6.3. Security Tutorials 313

MongoDB Documentation, Release 2.6.4
Finally ensure that each member of a replica set is accessible by way of resolvable DNS or hostnames. You should
either congure your DNS names appropriately or set up your systems'/etc/hostsle to reect this conguration.
CongurationSpecify the run time conguration on each system in aconfiguration file stored in
/etc/mongodb.conf or a related location. Create the directory where MongoDB stores data les before de-
ploying MongoDB.
For more information about the run time options used above and other conguration options, see
http://docs.mongodb.org/manualreference/configuration-options .
Procedure
This procedure deploys a replica set in which all members use the same key le.
Step 1: Start one member of the replica set.Thismongodshouldnotenableauth.
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 aroot(page 368) user (siteRootAdmin) that you
will use to complete the remainder of the tutorial:
use admin
db.createUser( {
user:,
pwd:,
roles::, db:
});
db.createUser( {
user:,
pwd:,
roles::, db:
});
Step 3: Stop themongodinstance.
Step 4: Create the key le to be used by each member of the replica set.Create the key le your deployment will
use to authenticate servers to each other.
To generate pseudo-random data to use for akeyfile, issue the followingopensslcommand:
openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile
You may generate a key le using any method you choose. Always ensure that the password stored in the key le is
both long and contains a high amount of entropy. Usingopensslin this manner helps generate such a key.
Step 5: Copy the key le to each member of the replica set.Copy themongodb-keyfileto all hosts where
components of a MongoDB deployment run. Set the permissions of these les to600so that only theownerof the
le can read or write this le to prevent other users on the system from accessing the shared secret.
314 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Step 6: Start each member of the replica set with the appropriate options.For each member, start amongod
and specify the key le and the name of the replica set. Also specify other parameters as needed for your deployment.
For replication-specic parameters, seecli-mongod-replica-setrequired 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 species parameters through the--keyFileand--replSetcommand-line options:
mongodkeyFilemysecretdirectory/mongodb-keyfilereplSet
The following example species parameters through a conguration le:
mongodconfig $HOME/.mongodb/config
In production deployments, you can congure acontrol scriptto manage this process. Control scripts are beyond the
scope of this document.
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 thesiteRootAdminuser. From themongoshell, use the
following operation to authenticate:
use admin
db.auth("siteRootAdmin",);
Step 8: Initiate the replica set.Users.initiate():
rs.initiate()
MongoDB initiates a set that consists of the current member and that uses the default replica set conguration.
Step 9: Verify the initial replica set conguration.Users.conf()to display thereplica set conguration object
(page 594):
rs.conf()
The replica set conguration object resembles the following:
{
"_id",
"version",
"members"
{
"_id",
"host"
}
]
}
Step 10: Add the remaining members to the replica set.Add the remaining members with thers.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 aprimary.
6.3. Security Tutorials 315

MongoDB Documentation, Release 2.6.4
Step 11: Check the status of the replica set.Use thers.status()operation:
rs.status()
Step 12: Create additional users to address operational requirements.You can usebuilt-in roles(page 361) to
create common types of database users, such as thedbOwner(page 363) role to create a database administrator, the
readWrite(page 362) role to create a user who can update data, or theread(page 362) role to create user who
can search data but no more. You also can denecustom roles(page 286).
For example, the following creates a database administrator for theproductsdatabase:
use products
db.createUser(
{
user:,
pwd:,
roles:
[
{
role:,
db:
}
]
}
)
For an overview of roles and privileges, seeAuthorization(page 285). For more information on adding users, seeAdd
a User to a Database(page 344).
6.3.4
The following tutorials provide instructions for MongoDBs authentication and authorization related features.
Enable Client Access Control(page 317)Describes the process for enabling authentication for MongoDB deploy-
ments.
Enable Authentication in a Sharded Cluster(page 318)Control access to a sharded cluster through a key le and
thekeyFilesetting on each of the cluster's components.
Enable Authentication after Creating the User Administrator(page 319)Describes an alternative process for en-
abling authentication for MongoDB deployments.
Use x.509 Certicates to Authenticate Clients(page 320)Use x.509 for client authentication.
Use x.509 Certicate for Membership Authentication(page 323)Use x.509 for internal member authentication for
replica sets and sharded clusters.
Authenticate Using SASL and LDAP with ActiveDirectory(page 326)Describes the process for authentication us-
ing SASL/LDAP with ActiveDirectory.
Authenticate Using SASL and LDAP with OpenLDAP(page 329)Describes the process for authentication using
SASL/LDAP with OpenLDAP.
Congure MongoDB with Kerberos Authentication on Linux(page 331)For MongoDB Enterprise Linux, de-
scribes the process to enable Kerberos-based authentication for MongoDB deployments.
Congure MongoDB with Kerberos Authentication on Windows(page 334)For MongoDB Enterprise for Win-
dows, describes the process to enable Kerberos-based authentication for MongoDB deployments.
316 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Authenticate to a MongoDB Instance or Cluster(page 336)Describes the process for authenticating to MongoDB
systems using themongoshell.
Generate a Key File(page 338)Use key le to allow the components of MongoDB sharded cluster or replica set to
mutually authenticate.
Troubleshoot Kerberos Authentication on Linux(page 338)Steps to troubleshoot Kerberos-based authentication
for MongoDB deployments.
Implement Field Level Redaction(page 340)Describes the process to set up and access document content that can
have different access levels for the same data.
Enable Client Access Control
Overview
Enabling access control on a MongoDB instance restricts access to the instance by requiring that users identify them-
selves when connecting. In this procedure, you enable access control and then create the instance's rst 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 thelocalhost exception
(page 285). In that case, you must use the Enable Authentication after Creating the User Administrator(page 319)
procedure to enable access control.
This procedure uses thelocalhost exception(page 285) to allow you to create the rst user after enabling authentication.
SeeLocalhost Exception(page 285) andAuthentication(page 282) for more information.
Procedure
Step 1: Start the MongoDB instance with authentication enabled.Start themongodormongosinstance with
theauthorizationorkeyFilesetting. Useauthorizationon a standalone instance. UsekeyFileon an
instance in areplica setorsharded cluster.
For example, to start a mongodwith authentication enabled and a key le stored in
http://docs.mongodb.org/manualprivate/var , rst set the following option in themongod`s
conguration le:
security:
keyFile: /private/var/key.pem
Then start themongodand specify the cong le. For example:
mongod --config /etc/mongodb/mongodb.conf
After you enable authentication, only the user administrator can connect to the MongoDB instance. The user admin-
istrator must log in and grant further access to the instance by creating additional users.
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 thelocalhost exception(page 285).
6.3. Security Tutorials 317

MongoDB Documentation, Release 2.6.4
Step 3: Create the system user administrator.Add the user with theuserAdminAnyDatabase (page 368)
role, and only that role.
The following example creates the usersiteUserAdminuser on theadmindatabase:
use admin
db.createUser(
{
user:,
pwd:,
roles:
[
{
role:,
db:
}
]
}
)
After you create the user administrator, thelocalhost exception(page 285) is no longer available.
Step 4: Create additional users.Login in with the user administrator's credentials and create additional users. See
Add a User to a Database(page 344).
Next Steps
If you need to disable access control for any reason, restart the process without theauthorizationorkeyFile
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 eachmongosand eachmongod, including each cong server, and all
members of a shard's replica set.
Authentication requires an authentication mechanism and, in most cases, akey file. The content of the key le
must be the same on all cluster members.
Procedure
Step 1: Create a key le.Create the key le your deployment will use to authenticate servers to each other.
To generate pseudo-random data to use for akeyfile, issue the followingopensslcommand:
openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile
318 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
You may generate a key le using any method you choose. Always ensure that the password stored in the key le is
both long and contains a high amount of entropy. Usingopensslin this manner helps generate such a key.
Step 2: Enable authentication on each component in the cluster.On eachmongosandmongodin the cluster,
including all cong servers and shards, specify the key le using one of the following approaches:
Specify the key le in the conguration le.In the conguration le, set thekeyFileoption to the key le's path
and then start the component, as in the following example:
security:
keyFile: /srv/mongodb/keyfile
Specify the key le at runtime.When starting the component, set the--keyFileoption, which is an option
for bothmongosinstances andmongodinstances. Set the--keyFileto the key le's path. ThekeyFile
setting implies theauthorizationsetting, which means in most cases you do not need to setauthorization
explicitly.
Step 3: Add users.While connected to amongos, add the rst administrative user and then add subsequent users.
SeeCreate a User Administrator(page 343).
Related Documents
Authentication(page 282)
Security(page 279)
Use x.509 Certicate for Membership Authentication(page 323)
Enable Authentication after Creating the User Administrator
Overview
Enabling authentication on a MongoDB instance restricts access to the instance by requiring that users identify them-
selves when connecting. In this procedure, you will create the instance's rst 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, seeEnable Client Access Control(page 317).
Considerations
This document outlines a procedure for enabling authentication for MongoDB instance where you create the rst user
on an existing MongoDB system that does not require authentication before restarting the instance and requiring au-
thentication. You can use thelocalhost exception(page 285) to gain access to a system with no users and authentication
enabled. SeeEnable Client Access Control(page 317) for the description of that procedure.
6.3. Security Tutorials 319

MongoDB Documentation, Release 2.6.4
Procedure
Step 1: Start the MongoDB instance without authentication.Start themongodormongosinstancewithoutthe
authorizationorkeyFilesetting. For example:
mongodportdbpathdata/db1
For details on starting amongodormongos, seeManage mongod Processes(page 207) orDeploy a Sharded Cluster
(page 635).
Step 2: Create the system user administrator.Add the user with theuserAdminAnyDatabase (page 368)
role, and only that role.
The following example creates the usersiteUserAdminuser on theadmindatabase:
use admin
db.createUser(
{
user:,
pwd:,
roles:
[
{
role:,
db:
}
]
}
)
Step 3: Re-start the MongoDB instance with authentication enabled.Re-start themongodormongosinstance
with theauthorizationorkeyFilesetting. Useauthorizationon a standalone instance. UsekeyFile
on an instance in areplica setorsharded cluster.
The following example enables authentication on a standalonemongodusing theauthorizationcommand-line
option:
mongodauthconfigetc/mongodb/mongodb.conf
Step 4: Create additional users.Log in with the user administrator's credentials and create additional users. See
Add a User to a Database(page 344).
Next Steps
If you need to disable authentication for any reason, restart the process without theauthorizationorkeyFile
option.
Use x.509 Certicates to Authenticate Clients
New in version 2.6.
MongoDB supports x.509 certicate authentication for use with a secureSSL connection(page 304). The x.509 client
authentication allowsclients to authenticate to servers with certicates(page 321) rather than with a username and
password.
320 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
To use x.509 authentication for the internal authentication of replica set/sharded cluster members, seeUse x.509
Certicate for Membership Authentication(page 323).
Client x.509 Certicate
The client certicate must have the following properties:

keyUsage = digitalSignature
extendedKeyUsage = clientAuth
DN), must differ from that of a
Member x.509 Certicate(page 323) to prevent client certicates from identifying the client as a cluster member
and granting full permission on the system. Specically, 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).

Congure MongoDB Server
Use Command-line OptionsYou can congure the MongoDB server from the command line, e.g.:
mongod --sslMode requireSSL --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>
Warning:If the--sslCAFileoption and its target le are not specied, x.509 client and member authenti-
cation will not function.mongod, andmongosin sharded systems, will not be able to verify the certicates of
processes connecting to it against the trusted certicate authority (CA) that issued them, breaking the certicate
chain.
As of version 2.6.4,mongodwill not start with x.509 authentication enabled if the CA le is not specied.
Use Conguration FileYou may also specify these options in theconfiguration file.
Starting in MongoDB 2.6, you can specify the conguration for MongoDB inYAML format, e.g.:
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 conguration using the
44
, e.g.:
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 specic conguration.
44
http://docs.mongodb.org/v2.4/reference/conguration
6.3. Security Tutorials 321

MongoDB Documentation, Release 2.6.4
Add x.509 Certicatesubjectas a User
To authenticate with a client certicate, you must rst add the value of thesubjectfrom the client certicate as a
MongoDB user. Each unique x.509 client certicate corresponds to a single MongoDB user; i.e. you cannot use a
single client certicate to authenticate more than one MongoDB user.
1. subjectfrom the client certicate with the following command:
openssl x509 -in <pathToClient PEM> -inform PEM -subject -nameopt RFC2253
The command returns thesubjectstring as well as certicate:
subject==myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry
-----BEGIN CERTIFICATE-----
# ...
-----END CERTIFICATE-----
2. subject, omitting the spaces, from the certicate as a user.
For example, in themongoshell, to add the user with both thereadWriterole in thetestdatabase and the
userAdminAnyDatabase role which is dened only in theadmindatabase:
db.getSiblingDB("$external").runCommand(
{
createUser:,
roles:
{ role:, db:
{ role:, db:
],
writeConcern:::
}
)
In the above example, to add the user with thereadWriterole in thetestdatabase, the role specication
document specied'test'in thedbeld. To adduserAdminAnyDatabase role for the user, the above
example specied'admin'in thedbeld.
Note: Some roles are dened only in theadmindatabase, including:clusterAdmin,
readAnyDatabase, readWriteAnyDatabase , dbAdminAnyDatabase, and
userAdminAnyDatabase. To add a user with these roles, specify'admin'in thedb.
SeeAdd a User to a Database(page 344) for details on adding a user with roles.
Authenticate with a x.509 Certicate
To authenticate with a client certicate, you must rst add a MongoDB user that corresponds to the client certicate.
SeeAdd x.509 Certicate subject as a User(page 322).
To authenticate, use thedb.auth()method in the$externaldatabase, specifying"MONGODB-X509"for the
mechanismeld, and theuser that corresponds to the client certicate(page 322) for theusereld.
For example, if using themongoshell,
1. mongoshell to themongodset up for SSL:
mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>
322 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
2. db.auth()method in the$externaldatabase. For themechanism
eld, specify"MONGODB-X509", and for theusereld, specify the user, or thesubject, that corresponds
to the client certicate.
db.getSiblingDB("$external").auth(
{
mechanism:,
user:
}
)
Use x.509 Certicate for Membership Authentication
New in version 2.6.
MongoDB supports x.509 certicate authentication for use with a secureSSL connection(page 304). Sharded cluster
members and replica set members can use x.509 certicates to verify their membership to the cluster or the replica set
instead of usingkeyles(page 282). The membership authentication is an internal process.
For client authentication with x.509, seeUse x.509 Certicates to Authenticate Clients(page 320).
Member x.509 Certicate
The member certicate, used for internal authentication to verify membership to the sharded cluster or a replica set,
must have the following properties:

a replica set.
DN), found in the member certicate'ssubject, must specify a non-empty value
forat least oneof the following attributes: Organization (O), the Organizational Unit (OU) or the Domain
Component (DC).
O`s), the Organizational Unit attributes (OU`s), and the Domain Components (DC`s)
must match those from the certicates for the other cluster members. To match, the certicate must match all
specications of these attributes, or even the non-specication of these attributes. The order of the attributes
does not matter.
In the following example, the twoDN`s contain matching specications forO,OUas well as the non-specication
of theDCattribute.
CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2
However, the following twoDN`s contain a mismatch for theOUattribute since one contains twoOUspecica-
tions and the other, only one specication.
CN=host1,OU=Dept1,OU=Sales,O=MongoDB
CN=host2,OU=Dept1,O=MongoDB
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 certicates for a cluster could have the following subjects:
subject==<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
subject==<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
subject==<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US
6.3. Security Tutorials 323

MongoDB Documentation, Release 2.6.4
It is possible to use a single x509 certicate for both member authentication andx.509 client authentication(page 320).
To do so, obtain a certicate with bothclientAuthandserverAuth(i.e. TLS Web Client Authentication and
TLS Web Server Authentication) specied as Extended Key Usage (EKU) values, or simply do not specify any
EKU values. Provide this le as the the--sslPEMKeyFileand omit the--sslClusterFileoption described
below.
Congure Replica Set/Sharded Cluster
Use Command-line OptionsTo specify the x.509 certicate for internal cluster member authentication, append
the additional SSL options--clusterAuthModeand--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 specic conguration. 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. SeeSSL Certicate Passphrase(page 306) for details.
Warning:If the--sslCAFileoption and its target le are not specied, x.509 client and member authenti-
cation will not function.mongod, andmongosin sharded systems, will not be able to verify the certicates of
processes connecting to it against the trusted certicate authority (CA) that issued them, breaking the certicate
chain.
As of version 2.6.4,mongodwill not start with x.509 authentication enabled if the CA le is not specied.
Use Conguration FileYou may also specify these options in theconfiguration file.
YAML Formatted Conguration FileStarting in MongoDB 2.6, you can specify the conguration for MongoDB
inYAML format, 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>
Seesecurity.clusterAuthMode ,net.ssl.mode,net.ssl.PEMKeyFile,net.ssl.CAFile, and
net.ssl.clusterFile for more information on the settings.
v2.4 Conguration FileFor backwards compatibility, you can also specify the conguration using the
uration le format
45
, as in the following example:
sslMode
sslPEMKeyFile
sslCAFile
clusterAuthMode
sslClusterFile
45
http://docs.mongodb.org/v2.4/reference/conguration
324 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Upgrade from Keyle Authentication to x.509 Authentication
To upgrade clusters that are currently using keyle authentication to x.509 authentication, use a rolling upgrade pro-
cess.
Clusters Currently Using SSLFor clusters using SSL and keyle authentication, to upgrade to x.509 cluster au-
thentication, use the following rolling upgrade process:
1. --clusterAuthModeset tosendKeyFileand
the option--sslClusterFileset to the appropriate path of the node's certicate. Include otherSSL options
(page 304) as well as any other options that are required for your specic conguration. 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 keyle to authenticate itself as a member. However, each
node can now accept either a keyle or an x.509 certicate from other members to authenticate those members.
Upgrade all nodes of the cluster to this setting.
2. setParametercommand to update the
clusterAuthModetosendX509.
46
For example,
db.getSiblingDB(admin).runCommand(
With this setting, each node uses its x.509 certicate, specied with the--sslClusterFileoption in the
previous step, to authenticate itself as a member. However, each node continues to accept either a keyle or an
x.509 certicate from other members to authenticate those members. Upgrade all nodes of the cluster to this
setting.
3.
setParametercommand to update theclusterAuthModetox509to only use the x.509 certicate for
authentication.
1
For example:
db.getSiblingDB(admin).runCommand(
4. configuration file with the appropriate x.509 settings to ensure
that upon subsequent restarts, the cluster uses x.509 authentication.
See--clusterAuthModefor the various modes and their descriptions.
Clusters Currently Not Using SSLFor clusters using keyle authentication but not SSL, to upgrade to x.509
authentication, use the following rolling upgrade process:
1. --sslModeset toallowSSL, the option
--clusterAuthMode set tosendKeyFileand the option--sslClusterFileset to the appropri-
ate path of the node's certicate. Include otherSSL options(page 304) as well as any other options that are
required for your specic conguration. 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 keyle to authen-
ticate itself as a member. However, each node can now accept either a keyle or an x.509 certicate from other
members to authenticate those members.
46
As an alternative to using thesetParametercommand, you can also restart the nodes with the appropriate SSL and x509 options and
values.
6.3. Security Tutorials 325

MongoDB Documentation, Release 2.6.4
Upgrade all nodes of the cluster to these settings.
2. setParametercommand to update the
sslModetopreferSSLand theclusterAuthModetosendX509.
1
For example:
db.getSiblingDB(admin).runCommand(, clusterAuthMode:
With thesslModeset topreferSSL, the node accepts both SSL and non-SSL incoming connections, and its
outgoing connections use SSL.
With theclusterAuthModeset tosendX509, each node uses its x.509 certicate, specied with the
--sslClusterFileoption in the previous step, to authenticate itself as a member. However, each node
continues to accept either a keyle or an x.509 certicate from other members to authenticate those members.
Upgrade all nodes of the cluster to these settings.
3.
setParametercommand to update thesslModetorequireSSLand theclusterAuthModetox509.
1
For example:
db.getSiblingDB(admin).runCommand(, clusterAuthMode:
With thesslModeset torequireSSL, the node only uses SSL connections.
With theclusterAuthModeset tox509, the node only uses the x.509 certicate for authentication.
4. configuration file with the appropriate SSL and x.509 settings
to ensure that upon subsequent restarts, the cluster uses x.509 authentication.
See--clusterAuthModefor the various modes and their descriptions.
Authenticate Using SASL and LDAP with ActiveDirectory
MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to congure
a MongoDB cluster to authenticate users by proxying authentication requests to a specied Lightweight Directory
Access Protocol (LDAP) service.
Considerations
MongoDB Enterprise for Windows doesnotinclude LDAP support for authentication. However, MongoDB Enterprise
for Linux supports using LDAP authentication with an ActiveDirectory server.
MongoDB doesnotsupport LDAP authentication in mixed sharded cluster deployments that contain both version 2.4
and version 2.6 shards. SeeUpgrade MongoDB to 2.6(page 751) for upgrade instructions.
Use secure encrypted or trusted connections between clients and the server, as well as betweensaslauthdand the
LDAP server. The LDAP server uses theSASL PLAINmechanism, sending and receiving data inplain text. You
should use only a trusted channel such as a VPN, a connection encrypted with SSL, or a trusted wired network.
Conguresaslauthd
LDAP support for user authentication requires proper conguration of thesaslauthddaemon process as well as
the MongoDB server.
326 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Step 1: Specify the mechanism. On systems that congure saslauthd with the
/etc/sysconfig/saslauthd le, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon
Linux AMI, set the mechanismMECHtoldap:
MECH=ldap
On systems that conguresaslauthdwith the/etc/default/saslauthd le, such as Ubuntu, set the
MECHANISMSoption toldap:
MECHANISMS="ldap"
Step 2: Adjust caching behavior.On certain Linux distributions,saslauthdstarts with the caching of authenti-
cation credentialsenabled. Until restarted or until the cache expires,saslauthdwill not contact the LDAP server
to re-authenticate users in its authentication cache. This allowssaslauthdto 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
47
ofsaslauthd.
Step 3: Congure LDAP Options with ActiveDirectory.If thesaslauthd.confle does not exist, create it.
Thesaslauthd.confle usually resides in the/etcfolder. If specifying a different le path, see the
48
ofsaslauthd.
To use with ActiveDirectory, startsaslauthdwith the following conguration options set in the
saslauthd.confle:
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 onsaslauthdconguration, see.
Step 4: Test thesaslauthdconguration.Usetestsaslauthdutility to test thesaslauthdconguration.
For example:
testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux
Congure MongoDB
Step 1: Add user to MongoDB for authentication.Add the user to the$externaldatabase in MongoDB. To
specify the user's privileges, assignroles(page 285) to the user.
For example, the following adds a user with read-only access to therecordsdatabase.
db.getSiblingDB("$external").createUser(
{
user : <username>,
roles:, db:
}
)
47
http://www.linuxcommand.org/man_pages/saslauthd8.html
48
http://www.linuxcommand.org/man_pages/saslauthd8.html
6.3. Security Tutorials 327

MongoDB Documentation, Release 2.6.4
Add additional principals as needed. For more information about creating and managing users, see
http://docs.mongodb.org/manualreference/command/nav-user-management .
Step 2: Congure MongoDB server.To congure the MongoDB server to use thesaslauthdinstance for proxy
authentication, start themongodwith the following options:
--auth,
authenticationMechanisms parameter set toPLAIN, and
saslauthdPathparameter set to the path to the Unix-domain Socket of thesaslauthdinstance.
Congure the MongoDB server using either the command line option--setParameteror theconfiguration
file. Specify additional congurations as appropriate for your conguration.
If you use theauthorizationoption to enforce authentication, you will need privileges to create a user.
Use specicsaslauthdsocket path.For socket path of/<some>/<path>/saslauthd , set the
saslauthdPathto/<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 aconfiguration file, specify the following parameters in the le:
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 thesaslauthdPathto
the empty string"", as in the following command line example:
mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN
Or if using aconfiguration file, specify the following parameters in the le:
auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN
Step 3: Authenticate the user in themongoshell.To perform the authentication in themongoshell, use the
db.auth()method in the$externaldatabase.
Specify the value"PLAIN"in themechanismeld, the user and password in theuserandpwdelds respectively,
and the valuefalsein thedigestPasswordeld. YoumustspecifyfalsefordigestPasswordsince the
server must receive an undigested password to forward on tosaslauthd, as in the following example:
db.getSiblingDB("$external").auth(
{
mechanism:,
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.
328 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Authenticate Using SASL and LDAP with OpenLDAP
MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to congure
a MongoDB cluster to authenticate users by proxying authentication requests to a specied Lightweight Directory
Access Protocol (LDAP) service.
Considerations
MongoDB Enterprise for Windows doesnotinclude LDAP support for authentication. However, MongoDB Enterprise
for Linux supports using LDAP authentication with an ActiveDirectory server.
MongoDB doesnotsupport LDAP authentication in mixed sharded cluster deployments that contain both version 2.4
and version 2.6 shards. SeeUpgrade MongoDB to 2.6(page 751) for upgrade instructions.
Use secure encrypted or trusted connections between clients and the server, as well as betweensaslauthdand the
LDAP server. The LDAP server uses theSASL PLAINmechanism, sending and receiving data inplain text. You
should use only a trusted channel such as a VPN, a connection encrypted with SSL, or a trusted wired network.
Conguresaslauthd
LDAP support for user authentication requires proper conguration of thesaslauthddaemon process as well as
the MongoDB server.
Step 1: Specify the mechanism. On systems that congure saslauthd with the
/etc/sysconfig/saslauthd le, such as Red Hat Enterprise Linux, Fedora, CentOS, and Amazon
Linux AMI, set the mechanismMECHtoldap:
MECH=ldap
On systems that conguresaslauthdwith the/etc/default/saslauthd le, such as Ubuntu, set the
MECHANISMSoption toldap:
MECHANISMS="ldap"
Step 2: Adjust caching behavior.On certain Linux distributions,saslauthdstarts with the caching of authenti-
cation credentialsenabled. Until restarted or until the cache expires,saslauthdwill not contact the LDAP server
to re-authenticate users in its authentication cache. This allowssaslauthdto 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
49
ofsaslauthd.
Step 3: Congure LDAP Options with OpenLDAP.If thesaslauthd.confle does not exist, create it. The
saslauthd.confle usually resides in the/etcfolder. If specifying a different le path, see the
50
of
saslauthd.
To connect to an OpenLDAP server, update thesaslauthd.confle with the following conguration options:
ldap_servers: <ldap uri>
ldap_search_base: <search base>
ldap_filter: <filter>
49
http://www.linuxcommand.org/man_pages/saslauthd8.html
50
http://www.linuxcommand.org/man_pages/saslauthd8.html
6.3. Security Tutorials 329

MongoDB Documentation, Release 2.6.4
Theldap_serversspecies the uri of the LDAP server used for authentication. In general, for OpenLDAP installed
on the local machine, you can specify the valueldap://localhost:389 or if using LDAP over SSL, you can
specify the valueldaps://localhost:636 .
Theldap_search_basespecies distinguished name to which the search is relative. The search includes the base
or objects below.
Theldap_filterspecies the search lter.
The values for these conguration options should correspond to the values specic for your test. For example, to lter
on email, specifyldap_filter: (mail=%n) instead.
OpenLDAP Example A samplesaslauthd.confle 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 conguration, create users with auidattribute (login name) and place under the
Usersorganizational unit (ou) under the domain components (dc)exampleandcom.
For more information onsaslauthdconguration, see.
Step 4: Test thesaslauthdconguration.Usetestsaslauthdutility to test thesaslauthdconguration.
For example:
testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux
Congure MongoDB
Step 1: Add user to MongoDB for authentication.Add the user to the$externaldatabase in MongoDB. To
specify the user's privileges, assignroles(page 285) to the user.
For example, the following adds a user with read-only access to therecordsdatabase.
db.getSiblingDB("$external").createUser(
{
user : <username>,
roles:, db:
}
)
Add additional principals as needed. For more information about creating and managing users, see
http://docs.mongodb.org/manualreference/command/nav-user-management .
Step 2: Congure MongoDB server.To congure the MongoDB server to use thesaslauthdinstance for proxy
authentication, start themongodwith the following options:
--auth,
authenticationMechanisms parameter set toPLAIN, and
saslauthdPathparameter set to the path to the Unix-domain Socket of thesaslauthdinstance.
Congure the MongoDB server using either the command line option--setParameteror theconfiguration
file. Specify additional congurations as appropriate for your conguration.
If you use theauthorizationoption to enforce authentication, you will need privileges to create a user.
330 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Use specicsaslauthdsocket path.For socket path of/<some>/<path>/saslauthd , set the
saslauthdPathto/<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 aconfiguration file, specify the following parameters in the le:
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 thesaslauthdPathto
the empty string"", as in the following command line example:
mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN
Or if using aconfiguration file, specify the following parameters in the le:
auth=true
setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
setParameter=authenticationMechanisms=PLAIN
Step 3: Authenticate the user in themongoshell.To perform the authentication in themongoshell, use the
db.auth()method in the$externaldatabase.
Specify the value"PLAIN"in themechanismeld, the user and password in theuserandpwdelds respectively,
and the valuefalsein thedigestPasswordeld. YoumustspecifyfalsefordigestPasswordsince the
server must receive an undigested password to forward on tosaslauthd, as in the following example:
db.getSiblingDB("$external").auth(
{
mechanism:,
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.
Congure MongoDB with Kerberos Authentication on Linux
New in version 2.4.
Overview
MongoDB Enterprise supports authentication using aKerberos service(page 291). Kerberos is an industry standard
authentication protocol for large client/server system.
Prerequisites
Setting up and conguring a Kerberos deployment is beyond the scope of this document. This tutorial assumes
you have have congured aKerberos service principal(page 292) for eachmongodandmongosinstance in your
6.3. Security Tutorials 331

MongoDB Documentation, Release 2.6.4
MongoDB deployment, and you have a validkeytab le(page 292) for for eachmongodandmongosinstance.
To verify MongoDB Enterprise binaries:
mongod --version
In the output from this command, look for the stringmodules: subscription ormodules: enterprise
to conrm your system has MongoDB Enterprise.
Procedure
The following procedure outlines the steps to add a Kerberos user principal to MongoDB, congure a standalone
mongodinstance for Kerberos support, and connect using themongoshell and authenticate the user principal.
Step 1: Startmongodwithout Kerberos.For the initial addition of Kerberos users, startmongodwithout Kerberos
support.
If a Kerberos user is already in MongoDB and has theprivileges required to create a user, you can startmongodwith
Kerberos support.
Step 2: Connect tomongod.Connect via themongoshell to themongodinstance. Ifmongodhas--auth
enabled, ensure you connect with theprivileges required to create a user.
Step 3: Add Kerberos Principal(s) to MongoDB.Add a Kerberos principal,<username>@<KERBEROS
REALM>or<username>/<instance>@<KERBEROS REALM> , to MongoDB in the$externaldatabase.
Specify the Kerberos realm in all uppercase. The$externaldatabase allowsmongodto consult an external source
(e.g. Kerberos) to authenticate. To specify the user's privileges, assignroles(page 285) to the user.
The following example adds the Kerberos principalapplication/[email protected] with read-only
access to therecordsdatabase:
use $external
db.createUser(
{
user:,
roles::, db:
}
)
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
http://docs.mongodb.org/manualreference/command/nav-user-management .
Step 4: Startmongodwith Kerberos support.To startmongodwith Kerberos support, set the environmental
variableKRB5_KTNAMEto the path of the keytab le and themongodparameterauthenticationMechanisms
toGSSAPIin the following form:
env=<path to keytab file> \
mongod\
--setParameter=GSSAPI
<additional mongod options>
For example, the following starts a standalonemongodinstance with Kerberos support:
332 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
env=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --auth \
--setParameter=GSSAPI \
--dbpath /opt/mongodb/data
The path to yourmongodas well as yourkeytab le(page 292) may differ. Modify or include additionalmongod
options as required for your conguration. Thekeytab le(page 292) must be only accessible to the owner of the
mongodprocess.
With the ofcial.debor.rpmpackages, you can set theKRB5_KTNAMEin a environment settings le. See
KRB5_KTNAME(page 333) for details.
Step 5: Connectmongoshell tomongodand authenticate.Connect themongoshell client as the Kerberos prin-
cipalapplication/[email protected] . Before connecting, you must have used Kerberos'skinit
program to get credentials forapplication/[email protected] .
You can connect and authenticate from the command line.
mongo --authenticationMechanism=GSSAPI --authenticationDatabase=$external \
--username application/[email protected]
Or, alternatively, you can rst connectmongoto themongod, and then from themongoshell, use thedb.auth()
method to authenticate in the$externaldatabase.
use $external
db.auth( { mechanism:, user:
Additional Considerations
KRB5_KTNAME If you installed MongoDB Enterprise using one of the ofcial.debor.rpmpackages, and you
use the included init/upstart scripts to control themongodinstance, you can set theKR5_KTNAMEvariable in the
default environment settings le instead of setting the variable each time.
For.rpmpackages, the default environment settings le is/etc/sysconfig/mongod .
For.debpackages, the le is/etc/default/mongodb .
Set theKRB5_KTNAMEvalue in a line that resembles the following:
exportKRB5_KTNAME="<path to keytab>"
Conguremongosfor KerberosTo startmongoswith Kerberos support, set the environmen-
tal variableKRB5_KTNAMEto the path of itskeytab le(page 292) and themongosparameter
authenticationMechanisms toGSSAPIin the following form:
env=<path to keytab file> \
mongos\
--setParameter=GSSAPI \
<additional mongos options>
For example, the following starts amongosinstance with Kerberos support:
env=/opt/mongodb/mongos.keytab \
mongos\
--setParameter=GSSAPI \
--configdb shard0.example.net, shard1.example.net,shard2.example.net \
--keyFile /opt/mongodb/mongos.keyfile
6.3. Security Tutorials 333

MongoDB Documentation, Release 2.6.4
The path to yourmongosas well as yourkeytab le(page 292) may differ. Thekeytab le(page 292) must be only
accessible to the owner of themongosprocess.
Modify or include any additionalmongosoptions as required for your conguration. For example, instead of us-
ing--keyFilefor internal authentication of sharded cluster members, you can usex.509 member authentication
(page 323) instead.
Use a Cong FileTo conguremongodormongosfor Kerberos support using aconfiguration file,
specify theauthenticationMechanisms setting in the conguration le:
setParameter=authenticationMechanisms=GSSAPI
Modify or include any additionalmongodoptions as required for your conguration.
For example, ifhttp://docs.mongodb.org/manualopt/mongodb/mongod.conf contains the follow-
ing conguration settings for a standalonemongod:
auth
setParameter=authenticationMechanisms=GSSAPI
dbpath=/opt/mongodb/data
To startmongodwith Kerberos support, use the following form:
env=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --config /opt/mongodb/mongod.conf
The path to yourmongod,keytab le(page 292), and conguration le may differ. Thekeytab le(page 292) must
be only accessible to the owner of themongodprocess.
Troubleshoot Kerberos Setup for MongoDBIf you encounter problems when startingmongodormongoswith
Kerberos authentication, seeTroubleshoot Kerberos Authentication on Linux(page 338).
Incorporate Additional Authentication MechanismsKerberos 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 mecha-
nisms, as follows:
--setParameter=GSSAPI,MONGODB-CR
Only add the other mechanisms if in use. This parameter setting does not affect MongoDB's internal authentication of
cluster members.
Congure MongoDB with Kerberos Authentication on Windows
New in version 2.6.
Overview
MongoDB Enterprise supports authentication using aKerberos service(page 291). 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.
334 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Prerequisites
Setting up and conguring a Kerberos deployment is beyond the scope of this document. This tutorial assumes have
congured aKerberos service principal(page 292) for eachmongod.exeandmongos.exeinstance.
Procedures
Step 1: Startmongod.exewithout Kerberos.For the initial addition of Kerberos users, startmongod.exe
without Kerberos support.
If a Kerberos user is already in MongoDB and has theprivileges required to create a user, you can startmongod.exe
with Kerberos support.
Step 2: Connect tomongod.Connect via themongo.exeshell to themongod.exeinstance. Ifmongod.exe
has--authenabled, ensure you connect with theprivileges required to create a user.
Step 3: Add Kerberos Principal(s) to MongoDB.Add a Kerberos principal,<username>@<KERBEROS
REALM>, to MongoDB in the$externaldatabase. Specify the Kerberos realm in all uppercase. The$external
database allowsmongod.exeto consult an external source (e.g. Kerberos) to authenticate. To specify the user's
privileges, assignroles(page 285) to the user.
The following example adds the Kerberos [email protected] with read-only access to the
recordsdatabase:
use $external
db.createUser(
{
user:,
roles::, db:
}
)
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
http://docs.mongodb.org/manualreference/command/nav-user-management .
Step 4: Startmongod.exewith Kerberos support.You must startmongod.exeas theservice principal ac-
count(page 336).
To startmongod.exewith Kerberos support, set themongod.exeparameterauthenticationMechanisms
toGSSAPI:
mongod.exe --setParameter=GSSAPI <additional mongod.exe options>
For example, the following starts a standalonemongod.exeinstance with Kerberos support:
mongod.exe --auth --setParameter=GSSAPI
Modify or include additionalmongod.exeoptions as required for your conguration.
Step 5: Connectmongo.exeshell tomongod.exeand authenticate.Connect themongo.exeshell client as
the Kerberos [email protected] .
You can connect and authenticate from the command line.
6.3. Security Tutorials 335

MongoDB Documentation, Release 2.6.4
mongo.exe --authenticationMechanism=GSSAPI --authenticationDatabase=$external \
--username [email protected]
Or, alternatively, you can rst connectmongo.exeto themongod.exe, and then from themongo.exeshell, use
thedb.auth()method to authenticate in the$externaldatabase.
use $external
db.auth( { mechanism:, user:
Additional Considerations
Conguremongos.exefor KerberosTo startmongos.exewith Kerberos support, set themongos.exepa-
rameterauthenticationMechanisms toGSSAPI. You must startmongos.exeas theservice principal ac-
count(page 336).:
mongos.exe --setParameter=GSSAPI <additional mongos options>
For example, the following starts amongosinstance with Kerberos support:
mongos.exe --setParameter=GSSAPI --configdb shard0.example.net, shard1.example.net,shard2.example.net --keyFile C: \<path>\mongos.keyfile
Modify or include any additionalmongos.exeoptions as required for your conguration. For example, instead of
using--keyFilefor for internal authentication of sharded cluster members, you can usex.509 member authentica-
tion(page 323) instead.
Assign Service Principal Name to MongoDB Windows ServiceUsesetspn.exeto assign the service principal
name (SPN) to the account running themongod.exeand themongos.exeservice:
setspn.exe -A <service>/<fully qualified domain name> <service account name>
For example, ifmongod.exeruns as a service namedmongodbontestserver.mongodb.com with the ser-
vice account namemongodtest, assign the SPN as follows:
setspn.exe -A mongodb/testserver.mongodb.com mongodtest
Incorporate Additional Authentication MechanismsKerberos 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 mecha-
nisms, as follows:
--setParameter=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 runningmongodormongosinstance, 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:
336 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
mongodormongosinstance, or
authenticatecommand or thedb.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
Step 1: Specify your credentials when starting themongoinstance.When usingmongoto connect to amongod
ormongos, enter yourusername,password, andauthenticationDatabase . For example:
mongousernamepasswordauthenticationDatabase
Step 2: Close the session when your work is complete.To close an authenticated session, use thelogoutcom-
mand.:
db.runCommand( { logout:
Authenticate After Connecting to MongoDB
Step 1: Connect to a MongoDB instance.Connect to amongodormongosinstance.
Step 2: Switch to the database to which to authenticate.
usedatabase>
Step 3: Authenticate.Use either theauthenticatecommand or thedb.auth()method to provide your
username and password to the database. For example:
db.auth(,
Step 4: Close the session when your work is complete.To close an authenticated session, use thelogoutcom-
mand.:
db.runCommand( { logout:
6.3. Security Tutorials 337

MongoDB Documentation, Release 2.6.4
Generate a Key File
Overview
This section describes how to generate a key le to store authentication information. After generating a key le,
specify the key le using thekeyFileoption when starting amongodormongosinstance.
A key's length must be between 6 and 1024 characters and may only contain characters in the base64 set. The key
le must not have group or world permissions on UNIX systems. Key le permissions are not checked on Windows
systems.
MongoDB strips whitespace characters (e.g.x0d,x09, andx20) for cross-platform convenience. As a result, the
following operations produce identical keys:
echo
echo
echo
echo
Procedure
Step 1: Create a key le.Create the key le your deployment will use to authenticate servers to each other.
To generate pseudo-random data to use for akeyfile, issue the followingopensslcommand:
openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile
You may generate a key le using any method you choose. Always ensure that the password stored in the key le is
both long and contains a high amount of entropy. Usingopensslin this manner helps generate such a key.
Step 2: Specify the key le when starting a MongoDB instance.Specify the path to the key le with thekeyFile
option.
Troubleshoot Kerberos Authentication on Linux
New in version 2.4.
Kerberos Conguration Checklist
If you have difculty startingmongodormongoswithKerberos(page 291) on Linux systems, ensure that:
mongodand themongosbinaries are from MongoDB Enterprise.
To verify MongoDB Enterprise binaries:
mongod --version
In the output from this command, look for the stringmodules: subscription ormodules:
enterpriseto conrm your system has MongoDB Enterprise.

51
. MongoDB Enterprise does not support Kerberos authentication over the
HTTP Console interface.
51
http://docs.mongodb.org/ecosystem/tools/http-interface/#http-console
338 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
keytab le(page 292) matches the SPN for the
mongodormongosinstance, or themongodor themongosinstance use the--setParameter
saslHostName=<host name> to match the name in the keytab le.
mongodormongosinstance is a resolvable, fully
qualied domain for this host. You can test the system hostname resolution with thehostname -fcommand
at the system prompt.
mongodormongosinstance has both theAandPTRDNS records to provide forward
and reverse lookup. The records allow the host to resolve the components of the Kerberos infrastructure.
mongodinstance ormongosmust
be able to resolve each other using DNS. By default, Kerberos attempts to resolve hosts using the content of the
/etc/kerb5.confbefore using DNS to resolve hosts.
mongodor themongosinstances and the Kerberos infras-
tructure 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 bothmongodandmongo(or another client)
with the environment variableKRB5_TRACEset to different les to produce more verbose logging of the Kerberos
process to help further troubleshooting. For example, the following starts a standalonemongodwithKRB5_TRACE
set:
env=/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=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 reects insufcient credentials or a malicious attempt to authenticate.
If you receive this error, ensure that you are using the correct credentials and the correct fully qualied domain
name when connecting to the host.
GSSAPI error acquiring credentials. This error occurs during the start of themongodormongos
and reects improper conguration of the system hostname or a missing or incorrectly congured keytab le.
If you encounter this problem, consider the items in theKerberos Conguration Checklist(page 338), in partic-
ular, whether the SPN in thekeytab le(page 292) matches the SPN for themongodormongosinstance.
To determine whether the SPNs match:
1.
klist -k <keytab>
Replace<keytab>with the path to your keytab le.
2.
6.3. Security Tutorials 339

MongoDB Documentation, Release 2.6.4
hostname -f
Ensure that this name matches the name in the keytab le, or startmongodormongoswith the
--setParameter saslHostName=<hostname> .
See also:
Kerberos Authentication(page 291)
Congure MongoDB with Kerberos Authentication on Linux(page 331)
Congure MongoDB with Kerberos Authentication on Windows(page 334)
Implement Field Level Redaction
The$redactpipeline operator restricts the contents of the documents based on information stored in the documents
themselves.
Figure 6.1: Diagram of security architecture with middleware and redaction.
To store the access criteria data, add a eld to the documents and subdocuments. To allow for multiple combinations
of access levels for the same data, consider setting the access eld 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$redactstage in thedb.collection.aggregate() operation to restrict contents of the
result set based on the access required to view the data.
For more information on the$redactpipeline operator, including its syntax and associated system variables as well
as additional examples, see$redact.
340 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Procedure
For example, aforecastscollection contains documents of the following form where thetagseld determines
the access levels required to view the data:
{
_id:,
title:,
tags:
year:,
subsections:
{
subtitle:,
tags:,
content:
},
{
subtitle:,
tags:
content:
},
{
subtitle:,
tags:,
content:
text:,
tags:], [,,
}
}
]
}
For each document, thetagseld 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 year2014for this user, include a$redactstage 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"
}
}
6.3. Security Tutorials 341

MongoDB Documentation, Release 2.6.4
}
]
)
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
6.3.5
The following tutorials provide instructions on how to enable authentication and limit access for users with privilege
roles.
Create a User Administrator(page 343)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(page 344)Create non-administrator users using MongoDB's role-based authentication
system.
Create an Administrative User with Unrestricted Access(page 346)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(page 347)Create custom role.
Assign a User a Role(page 349)Assign a user a role. A role grants the user a dened set of privileges. A user can
have multiple roles.
Verify User Privileges(page 350)View a user's current privileges.
Modify a User's Access(page 352)Modify the actions available to a user on specic database resources.
View Roles(page 353)View a role's privileges.
Change a User's Password(page 354)Only user administrators can edit credentials. This tutorial describes the pro-
cess for editing an existing user's password.
Change Your Password and Custom Data(page 355)Users with sufcient access can change their own passwords
and modify the optionalcustom dataassociated with their user credential.
342 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
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 rst user. Then let
this user create all other users.
To provide user administrators, MongoDB hasuserAdmin(page 363) anduserAdminAnyDatabase (page 368)
roles, which grant access toactions(page 375) that support user and role management. Following the policy ofleast
privilegeuserAdmin(page 363) anduserAdminAnyDatabase (page 368) confer no additional privileges.
Carefully control access to these roles. A user with either of these roles can grantitselfunlimited additional privileges.
Specically, a user with theuserAdmin(page 363) role can grant itself any privilege in the database. A user assigned
either theuserAdmin(page 363) role on theadmindatabase or theuserAdminAnyDatabase (page 368) can
grant itself any privilegein the system.
Prerequisites
Required AccessYou must have thecreateUser(page 376)action(page 375) on a database to create a new user
on that database.
You must have thegrantRole(page 376)action(page 375) on a role's database to grant the role to another user.
If you have theuserAdmin(page 363) oruserAdminAnyDatabase (page 368) role, you have those actions.
First User RestrictionsIf your MongoDB deployment has no users, youmustconnect tomongodusing thelocal-
host exception(page 285) or use the--noauthoption when startingmongodto gain full access the system. Once
you have access, you can skip toCreating the system user administratorin 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, youmustrestartmongodwith the--noauthoption.
Procedure
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongosas a user
with the privileges required in thePrerequisites(page 343) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
6.3. Security Tutorials 343

MongoDB Documentation, Release 2.6.4
Step 3: Create the system user administrator.Add the user with theuserAdminAnyDatabase (page 368)
role, and only that role.
The following example creates the usersiteUserAdminuser on theadmindatabase:
use admin
db.createUser(
{
user:,
pwd:,
roles:
[
{
role:,
db:
}
]
}
)
Step 4: 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 specic database by way of theuserAdmin(page 363) role.
The following example creates the userrecordsUserAdminon therecordsdatabase:
use products
db.createUser(
{
user:,
pwd:,
roles:
[
{
role:,
db:
}
]
}
)
Related Documents
Authentication(page 282)
Security Introduction(page 279)
Enable Client Access Control(page 317)
Access Control Tutorials(page 316)
Add a User to a Database
Changed in version 2.6.
344 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Overview
Each application and user of a MongoDB system should map to a distinct application or administrator. Thisaccess
isolationfacilitates access revocation and ongoing user maintenance. At the same time users should have only the
minimal set of privileges required to ensure a system ofleast privilege.
To create a user, you must dene the user's credentials and assign that userroles(page 285). 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 seeSecurity Introduction(page 279).
Considerations
For users that authenticate using external mechanisms,
52
you do not need to provide credentials when creating users.
For all users, select the roles that have the exact requiredprivileges(page 286). If the correct roles do not exist,create
roles(page 347).
You can create a user without assigning roles, choosing instead to assign the roles later. To do so, create the user with
an emptyroles(page 372) array.
When adding a user to multiple databases, use unique username-and-password combinations for each database, see
Password Hashing Insecurity(page 385) for more information.
Prerequisites
To create a user on a system that usesauthentication(page 282), you must authenticate as a user administrator. If you
have not yet created a user administrator, do so as described inCreate a User Administrator(page 343).
Required AccessYou must have thecreateUser(page 376)action(page 375) on a database to create a new user
on that database.
You must have thegrantRole(page 376)action(page 375) on a role's database to grant the role to another user.
If you have theuserAdmin(page 363) oruserAdminAnyDatabase (page 368) role, you have those actions.
First User RestrictionsIf your MongoDB deployment has no users, youmustconnect tomongodusing thelocal-
host exception(page 285) or use the--noauthoption when startingmongodto gain full access the system. Once
you have access, you can skip toCreating the system user administratorin 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, youmustrestartmongodwith the--noauthoption.
Procedures
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongoswith the
privileges required in thePrerequisites(page 345) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
52
Congure MongoDB with Kerberos Authentication on Linux(page 331),Authenticate Using SASL and LDAP with OpenLDAP(page 329),
Authenticate Using SASL and LDAP with ActiveDirectory(page 326), and x.509 certicates provide external authentication mechanisms.
6.3. Security Tutorials 345

MongoDB Documentation, Release 2.6.4
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 3: Create the new user.Create the user in the database to which the user will belong. Pass a well formed user
document to thedb.createUser()method.
The following operation creates a user in thereportingdatabase with the specied name, password, and roles.
use reporting
db.createUser(
{
user:,
pwd:,
roles:
{ role:, db:
{ role:, db:
{ role:, db:
]
}
)
To authenticate thereportsUser, you must authenticate the user in thereportingdatabase.
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
thesesuper users, you can create users with access to all databaseresources(page 373) andactions(page 375).
For many deployments, you may be able to avoid havinganyusers with unrestricted access by having an administrative
user with thecreateUser(page 376) andgrantRole(page 376) actions granted as needed to support operations.
If users truly need unrestricted access to a MongoDB deployment, MongoDB provides abuilt-in role(page 361) named
root(page 368) that grants the combined privileges of all built-in roles. This document describes how to create an
administrative user with theroot(page 368) role.
For descriptions of the access each built-in role provides, see the section onbuilt-in roles(page 361).
Prerequisites
Required AccessYou must have thecreateUser(page 376)action(page 375) on a database to create a new user
on that database.
You must have thegrantRole(page 376)action(page 375) on a role's database to grant the role to another user.
If you have theuserAdmin(page 363) oruserAdminAnyDatabase (page 368) role, you have those actions.
346 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
First User RestrictionsIf your MongoDB deployment has no users, youmustconnect tomongodusing thelocal-
host exception(page 285) or use the--noauthoption when startingmongodto gain full access the system. Once
you have access, you can skip toCreating the system user administratorin 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, youmustrestartmongodwith the--noauthoption.
Procedure
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongosas a user
with the privileges required in thePrerequisites(page 346) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 3: Create the administrative user.In theadmindatabase, create a new user using thedb.createUser()
method. Give the user the built-inroot(page 368) role.
For example:
use admin
db.createUser(
{
user:,
pwd:,
roles:
}
)
Authenticate against theadmindatabase to test the new user account. Usedb.auth()while using theadmin
database or use themongoshell with the--authenticationDatabase option.
Create a Role
Overview
Roles grant users access to MongoDB resources. By default, MongoDB provides a number ofbuilt-in roles(page 361)
that administrators may use to control access to a MongoDB system. However, if these roles cannot describe the
desired privilege set of a particular user type in a deployment, you can dene a new, customized role.
6.3. Security Tutorials 347

MongoDB Documentation, Release 2.6.4
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 theadmindatabase can include privileges that apply to all databases or to thecluster
(page 374) and can inherit privileges from roles in other databases.
The combination of the database name and the role name uniquely denes a role in MongoDB.
Prerequisites
You must have thecreateRole(page 375)action(page 375) on a database to create a role on that database.
You must have thegrantRole(page 376)action(page 375) on the database that a privilege targets in order to
grant that privilege to a role. If the privilege targets multiple databases or theclusterresource , you must have the
grantRole(page 376) action on theadmindatabase.
You must have thegrantRole(page 376)action(page 375) on a role's database to grant the role to another role.
To view a role's information, you must be explicitly granted the role or must have theviewRole(page 376)action
(page 375) on the role's database.
Procedure
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongoswith the
privileges required in thePrerequisites(page 348) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 3: Dene the privileges to grant to the role.Decide whichresources(page 373) to grant access to and which
actions(page 375) to grant on each resource.
When creating the role, you will enter the resource-action pairings as documents in theprivilegesarray, as in the
following example:
{ db:, collection:
Step 4: Check whether an existing role provides the privileges.If an existing role contains the exact set of
privileges(page 286), the new role caninherit(page 286) those privileges.
To view the privileges provided by existing roles, use therolesInfocommand, as in the following:
db.runCommand( { rolesInfo:, showPrivileges:
348 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Step 5: Create the role.To create the role, use thecreateRolecommand. Specify privileges in the
privilegesarray and inherited roles in therolesarray.
The following example creates themyClusterwideAdmin role in theadmindatabase:
use admin
db.createRole(
{
role:,
privileges:
[
{ resource:: true}, actions:
{ resource::, collection::,,
{ resource::, collection::
{ resource::, collection::
],
roles:
[
{ role:, db:
],
writeConcern:::
}
)
The operation denesmyClusterwideAdmin role's privileges in theprivilegesarray. In therolesarray,
myClusterwideAdmin inherits privileges from theadmindatabase'sreadrole.
Assign a User a Role
Changed in version 2.6.
Overview
A role provides a user privileges to perform a set ofactions(page 375) on aresource(page 373). A user can have
multiple roles.
In MongoDB systems withauthorizationenforced, you must grant a user a role for the user to access a database
resource. To assign a role, rst determine the privileges the user needs and then determine the role that grants those
privileges.
For an overview of roles and privileges, seeAuthorization(page 285). For descriptions of the access each built-in role
provides, see the section onbuilt-in roles(page 361).
Prerequisites
You must have thegrantRole(page 376)action(page 375) 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 theviewRole(page 376)action
(page 375) on the role's database.
Procedure
Step 1: Connect with the privilege to grant roles.Connect to themongodormongoseither through thelocalhost
exception(page 285) or as a user with the privileges required in thePrerequisites(page 349) section.
6.3. Security Tutorials 349

MongoDB Documentation, Release 2.6.4
The following example operation connects to the MongoDB instance as a user namedroleManager:
mongoportu roleManagerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 3: Identify the user's roles and privileges.To display the roles and privileges of the user to be modied, use
thedb.getUser()anddb.getRole()methods, as described inVerify User Privileges(page 350).
To display the privileges granted bysiteRole01on the current database, issue:
db.getRole(, { showPrivileges: true} )
Step 4: Identify the privileges to grant or revoke.Determine which role contains the privilegesand only those
privileges. If such a role does not exist, then to grant the privileges will requirecreating a new role(page 347) with
the specic set of privileges. To revoke a subset of privileges provided by an existing role: revoke the original role,
create a new role(page 347) that contains the privilegesto keep, and then grant that role to the user.
Step 5: Grant a role to a user.Grant the user the role using thedb.grantRolesToUser() method.
For example:
use admin
db.grantRolesToUser(
"accountAdmin01",
[
{
role:, db:
},
{
role:, db:"admin"
}
]
)
Verify User Privileges
Overview
A user's privileges determine the access the user has to MongoDBresources(page 373) and theactions(page 375)
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, seeAuthorization(page 285).
350 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Prerequisites
To view a role's information, you must be explicitly granted the role or must have theviewRole(page 376)action
(page 375) on the role's database.
Procedure
Step 1: Identify the user's roles.Use theusersInfocommand ordb.getUser()method to display user
information. Theroles(page 372) array species the user's roles.
For example, to view roles foraccountUser01on theaccountsdatabase, issue the following:
use accounts
db.getUser("accountUser01")
Theroles(page 372) array displays all roles foraccountUser01:
"roles"
{
"role",
"db"
},
{
"role",
"db"
}
]
Step 2: Identify the privileges granted by the roles.For a given role, use therolesInfocommand or
db.getRole()method, and include theshowPrivilegesparameter. The resulting role document displays
both privileges granted directly and roles from which this role inherits privileges.
For example, to view the privileges granted bysiteRole01on therecordsdatabase, use the following operation,
which returns a document with aprivileges(page 370) array:
use records
db.getRole(, { showPrivileges: true} )
The returned document includes theroles(page 370) andprivileges(page 370) arrays:
"roles"
{
"role",
"db"
}
],
"privileges"
{
"resource"
"db",
"collection"
},
"actions"
"find",
"insert",
"update"
]
6.3. Security Tutorials 351

MongoDB Documentation, Release 2.6.4
}
]
To view the privileges granted by theread(page 362) role, usedb.getRole()again with the appropriate param-
eters.
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 ofleast privilege.
To change a user's access, rst determine the privileges the user needs and then determine the roles that grants those
privileges. Grant and revoke roles using the method:db.grantRolesToUser()anddb.revokeRolesFromUser
methods.
For an overview of roles and privileges, seeAuthorization(page 285). For descriptions of the access each built-in role
provides, see the section onbuilt-in roles(page 361).
Prerequisites
You must have thegrantRole(page 376)action(page 375) on a database to grant a role on that database.
You must have therevokeRole(page 376)action(page 375) 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 theviewRole(page 376)action
(page 375) on the role's database.
Procedure
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongoseither through
thelocalhost exception(page 285) or as a user with the privileges required in thePrerequisites(page 352) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
352 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Step 3: Identify the user's roles and privileges.To display the roles and privileges of the user to be modied, use
thedb.getUser()anddb.getRole()methods, as described inVerify User Privileges(page 350).
To display the privileges granted bysiteRole01on the current database, issue:
db.getRole(, { showPrivileges: true} )
Step 4: Identify the privileges to grant or revoke.Determine which role contains the privilegesand only those
privileges. If such a role does not exist, then to grant the privileges will requirecreating a new role(page 347) with
the specic set of privileges. To revoke a subset of privileges provided by an existing role: revoke the original role,
create a new role(page 347) that contains the privilegesto keep, and then grant that role to the user.
Step 5: Modify the user's access.
Revoke a RoleRevoke a role with thedb.revokeRolesFromUser() method. Access revocations apply as
soon as the user tries to run a command. On amongosrevocations are instant on themongoson which the command
ran, but there is up to a 10-minute delay before the user cache is updated on the othermongosinstances in the cluster.
The following example operation removes thereadWrite(page 362) role on theaccountsdatabase from the
accountUser01user's existing roles:
use accounts
db.revokeRolesFromUser(
"accountUser01",
[
{ role:, db:
]
)
Grant a RoleGrant a role using thedb.grantRolesToUser() method. For example, the following operation
grants theaccountUser01user theread(page 362) role on therecordsdatabase:
use accounts
db.grantRolesToUser(
"accountUser01",
[
{ role:, db:
]
)
View Roles
Overview
Arole(page 285) 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 theadmin.system.roles (page 270) collection in the
admindatabase.
Prerequisites
To view a role's information, you must be explicitly granted the role or must have theviewRole(page 376)action
(page 375) on the role's database.
6.3. Security Tutorials 353

MongoDB Documentation, Release 2.6.4
Procedures
The following procedures use therolesInfocommand. You also can use the methodsdb.getRole()(singular)
anddb.getRoles().
View a Role in the Current DatabaseIf the role is in the current database, you can refer to the role by name, as for
the roledataEntryon the current database:
db.runCommand({ rolesInfo:
View a Role in a Different DatabaseIf the role is in a different database, specify the role as a document. Use the
following form:
{ role:, db:
To view the customappWriterrole in theordersdatabase, issue the following command from themongoshell:
db.runCommand({ rolesInfo::, db:
View Multiple RolesTo view information for multiple roles, specify each role as a document or string in an array.
To view the customappWriterandclientWriterroles in theordersdatabase, as well as thedataEntry
role on the current database, use the following command from themongoshell:
db.runCommand( { rolesInfo::, db:
{ role:, db:
"dataEntry"
} )
View All Custom RolesTo view the all custom roles, queryadmin.system.roles(page 369) collection directly, for
example:
dbadmin)
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
opensslprogram to generate unique strings for use in passwords, as in the following command:
openssl rand -base64 48
Prerequisites
You must have thechangeAnyPasswordaction(page 375) on a database to modify the password of any user on
that database.
354 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
You must have thechangeOwnPassword (page 375)action(page 375) on your database to change your own
password.
Procedure
Step 1: Connect to MongoDB with the appropriate privileges.Connect to themongodormongoswith the
privileges required in thePrerequisites(page 354) section.
The following example operation connects to MongoDB as an authenticated user namedmanager:
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.Use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 3: Change the password. Pass the user's username and the new password to the
db.changeUserPassword() method.
The following operation changes thereportinguser's password toSOh3TbYhxuLiW8ypJPxmt1oOfL :
db.changeUserPassword("reporting",)
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(page 373) stores
optional user information.
Considerations
To generate a strong password for use in this procedure, you can use theopensslutility'srandcommand. For
example, issueopenssl randwith the following options to create a base64-encoded string of 48 pseudo-random
bytes:
openssl rand -base64 48
6.3. Security Tutorials 355

MongoDB Documentation, Release 2.6.4
Prerequisites
To modify your own password or custom data, you must have thechangeOwnPassword (page 375) and
changeOwnCustomData (page 375)actions(page 375) respectively on theclusterresource.
Procedure
Step 1: Connect with the appropriate privileges.Connect to themongodormongoswith your username and
current password.
For example, the following operation connects to MongoDB as an authenticated user namedmanager.
mongoportu managerpauthenticationDatabase admin
Step 2: Verify your privileges.To check that you have the privileges specied in thePrerequisites(page 356)
section, use theusersInfocommand with theshowPrivilegesoption.
The following example operation checks privileges for a user connected asmanager:
db.runCommand(
{
usersInfo:"manager",
showPrivileges: true
}
)
The resultingusersdocument displays the privileges granted tomanager.
Step 2: View your custom data.Connect to themongodormongoswith your username and current password.
For example, the following operation returns information for themanageruser:
db.runCommand( { usersInfo:
Step 3: Change your password and custom data.Pass your username, new password, and new custom data to the
updateUsercommand.
For example, the following operation changes a user's password toKNlZmiaNUp0Band custom data to{ title:
"Senior Manager" }:
db.runCommand(
{ updateUser:,
pwd:,
customData::
}
)
6.3.6
New in version 2.6.
MongoDB Enterprise supportsauditing(page 290) of various operations. A complete auditing solution must involve
allmongodserver andmongosrouter processes.
356 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
The audit facility can write audit events to the console, thesyslog(option is unavailable on Windows), a JSON le,
or a BSON le. For details on the audited operations and the audit log messages, seeSystem Event Audit Messages
(page 380).
Enable and Congure 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
syslogfor 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 theconfiguration file:
dbpath=data/db
auditDestination=syslog
Output to Console
To enable auditing and print the audit events to standard output (i.e.stdout), specifyconsolefor the
--auditDestination setting. For example:
mongod --dbpath data/db --auditDestination console
You may also specify these options in theconfiguration file:
dbpath=data/db
auditDestination=console
Output to JSON File
To enable auditing and print audit events to a le in JSON format, specifyfilefor the--auditDestination set-
ting,JSONfor the--auditFormatsetting, and the output lename 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 le with the relative path name ofdata/db/auditLog.json :
mongod --dbpath data/db --auditDestination file --auditFormat JSON --auditPath data/db/auditLog.json
The audit le rotates at the same time as the server log le.
You may also specify these options in theconfiguration file:
dbpath=data/db
auditDestination=file
auditFormat=JSON
auditPath=data/db/auditLog.json
6.3. Security Tutorials 357

MongoDB Documentation, Release 2.6.4
Note:Printing audit events to a le in JSON format degrades server performance more than printing to a le in BSON
format.
Output to BSON File
To enable auditing and print audit events to a le in BSON binary format, specifyfilefor the
--auditDestination setting,BSONfor the--auditFormatsetting, and the output lename for the
--auditPath. The--auditPathoption accepts either full path name or relative path name. For ex-
ample, the following enables auditing and records audit events to a BSON le 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 le rotates at the same time as the server log le.
You may also specify these options in theconfiguration file:
dbpath=data/db
auditDestination=file
auditFormat=BSON
auditPath=data/db/auditLog.bson
To view the contents of the le, pass the le to the MongoDB utilitybsondump. 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 allauditable operations(page 381). The audit feature has an--auditFilter
option to determine which events to record. The--auditFilteroption takes a document of the form:
{ atype:expression>
The<expression>is aquery condition expressionto match onvarious actions(page 381) .
Filter for a Single Operation Type
For example, to audit only thecreateCollection (page 375) action, use the lter{ atype:
"createCollection" } :
Tip
To specify the lter as a command-line option, enclose the lter document in single quotes to pass the document as a
string.
mongoddbpath data/dbauditDestination fileauditFilterauditFormat JSONauditPath data/db/auditLog.json
Filter for Multiple Operation Types
To match on multiple operations, use the$inoperator in the<expression>as in the following:
358 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Tip
To specify the lter as a command-line option, enclose the lter document in single quotes to pass the document as a
string.
mongoddbpath data/dbauditDestination fileauditFilterauditFormat JSONauditPath data/db/auditLog.json
Filter on Authentication Operations on a Single Database
For authentication operations, you can also specify a specic database with theparam.dbeld:
{ atype:expression>,:database>
For example, to audit onlyauthenticateoperations that occur against thetestdatabase, use the lter{
atype: "authenticate", "param.db": "test" } :
Tip
To specify the lter as a command-line option, enclose the lter document in single quotes to pass the document as a
string.
mongoddbpath data/dbauthauditDestination fileauditFilterauditFormat JSONauditPath data/db/auditLog.json
To lter on allauthenticateoperations across databases, use the lter{ atype: "authenticate" } .
6.3.7
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 ling a ticket in the
53
project in JIRA. MongoDB, Inc responds to
vulnerability notications within 48 hours.
Create the Report in JIRA
Submit a ticket in the
54
project at: <http://jira.mongodb.org/browse>. The ticket number will become the
reference identication for the issue for its lifetime. You can use this identier 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:

Common Vulnerabilityinformation, if applicable, including:

53
https://jira.mongodb.org/browse/SECURITY
54
https://jira.mongodb.org/browse/SECURITY
6.3. Security Tutorials 359

MongoDB Documentation, Release 2.6.4
Send the Report via Email
While JIRA is the preferred reporting method, you may also report vulnerabilities via email to
[email protected]
55
.
You may encrypt email using MongoDB's public key at.
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
56
project.
Evaluation of a Vulnerability Report
MongoDB, Inc. validates all submitted vulnerabilities and uses Jira to track all communications regarding a vulner-
ability, including requests for clarication or additional information. If needed, MongoDB representatives set up a
conference call to exchange information regarding the vulnerability.
Disclosure
MongoDB, Inc. requests that you donotpublicly disclose any information regarding the vulnerability or exploit the
issue until it has had the opportunity to analyze the vulnerability, to respond to the notication, 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.
6.4
6.4.1 mongoShell
Name Description
db.auth() Authenticates a user to a database.
55
[email protected]
56
https://jira.mongodb.org/browse/SECURITY
360 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
User Management Methods
Name Description
db.addUser() Deprecated. Adds a user to a database, and allows administrators to congure the
user's privileges.
db.changeUserPassword()Changes an existing user's password.
db.createUser() Creates a new user.
db.dropAllUsers() Deletes all users associated with a database.
db.dropUser() Removes a single user.
db.getUser() Returns information about the specied user.
db.getUsers() Returns information about all users associated with a database.
db.grantRolesToUser() Grants a role and its privileges to a user.
db.removeUser() Deprecated. Removes a user from a database.
db.revokeRolesFromUser()Removes a role from a user.
db.updateUser() Updates user data.
Role Management Methods
Name Description
db.createRole() Creates a role and species its privileges.
db.dropAllRoles() Deletes all user-dened roles associated with a database.
db.dropRole() Deletes a user-dened role.
db.getRole() Returns information for the specied role.
db.getRoles() Returns information for all the user-dened roles in a database.
db.grantPrivilegesToRole() Assigns privileges to a user-dened role.
db.grantRolesToRole() Species roles from which a user-dened role inherits privileges.
db.revokePrivilegesFromRole() Removes the specied privileges from a user-dened role.
db.revokeRolesFromRole() Removes a role from a user.
db.updateRole() Updates a user-dened role.
6.4.2
Built-In Roles(page 361)Reference on MongoDB provided roles and corresponding access.
system.roles Collection(page 369)Describes the content of the collection that stores user-dened roles.
system.users Collection(page 372)Describes the content of the collection that stores users' credentials and role as-
signments.
Resource Document(page 373)Describes the resource document for roles.
Privilege Actions(page 375)List of the actions available for privileges.
Default MongoDB Port(page 380)List of default ports used by MongoDB.
System Event Audit Messages(page 380)Reference on system event audit messages.
Built-In Roles
MongoDB grants access to data and commands throughrole-based authorization(page 285) and provides built-in
roles that provide the different levels of access commonly needed in a database system. You can additionally create
user-dened roles(page 286).
A role grants privileges to perform sets ofactions(page 375) on denedresources(page 373). A given role applies to
the database on which it is dened and can grant access down to a collection level of granularity.
6.4. Security Reference 361

MongoDB Documentation, Release 2.6.4
Each of MongoDB's built-in roles denes access at the database level for allnon-system collections in the role's
database and at the collection level for allsystem collections(page 270).
MongoDB provides the built-indatabase user(page 362) anddatabase administration(page 363) roles onevery
database. MongoDB provides all other built-in roles only on theadmindatabase.
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 therolesInfocommand with theshowPrivilegesandshowBuiltinRoleselds both set
totrue.
Database User Roles
Every database includes the following client roles:
read
Provides the ability to read data on allnon-system collections and on the following system collections:
system.indexes(page 271),system.js(page 271), andsystem.namespaces (page 271) collec-
tions. The role provides read access by granting the followingactions(page 375):
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
readWrite
Provides all the privileges of theread(page 362) role plus ability to modify data on allnon-system collections
and thesystem.js(page 271) collection. The role provides the following actions on those collections:
collStats(page 379)
convertToCapped(page 378)
createCollection(page 375)
dbHash(page 379)
dbStats(page 379)
dropCollection(page 376)
createIndex(page 375)
dropIndex(page 378)
emptycapped(page 376)
find(page 375)
insert(page 375)
killCursors(page 376)
remove(page 375)
renameCollectionSameDB (page 378)
update(page 375)
362 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Database Administration Roles
Every database includes the following database administration roles:
dbAdmin
Provides the followingactions(page 375) on the database'ssystem.indexes (page 271),
system.namespaces(page 271), andsystem.profile(page 271) collections:
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
dropCollection(page 376) onsystem.profile(page 271)only
Provides the following actions on allnon-system collections. This roledoes notinclude full read access on
non-system collections:
collMod(page 378)
collStats(page 379)
compact(page 378)
convertToCapped(page 378)
createCollection(page 375)
createIndex(page 375)
dbStats(page 379)
dropCollection(page 376)
dropDatabase(page 378)
dropIndex(page 378)
enableProfiler(page 376)
indexStats(page 379)
reIndex(page 378)
renameCollectionSameDB (page 378)
repairDatabase(page 378)
storageDetails(page 377)
validate(page 379)
dbOwner
The database owner can perform any administrative action on the database. This role combines the privileges
granted by thereadWrite(page 362),dbAdmin(page 363) anduserAdmin(page 363) roles.
userAdmin
Provides the ability to create and modify roles and users on the current database. This role also indirectly
providessuperuser(page 368) access to either the database or, if scoped to theadmindatabase, the cluster.
TheuserAdmin(page 363) role allows users to grant any user any privilege, including themselves.
TheuserAdmin(page 363) role explicitly provides the following actions:
6.4. Security Reference 363

MongoDB Documentation, Release 2.6.4
changeCustomData(page 375)
changePassword(page 375)
createRole(page 375)
createUser(page 376)
dropRole(page 376)
dropUser(page 376)
grantRole(page 376)
revokeRole(page 376)
viewRole(page 376)
viewUser(page 376)
Cluster Administration Roles
Theadmindatabase includes the following roles for administering the whole system rather than just a single database.
These roles include but are not limited toreplica setandsharded clusteradministrative functions.
clusterAdmin
Provides the greatest cluster-management access. This role combines the privileges granted by the
clusterManager(page 364),clusterMonitor(page 365), andhostManager(page 366) roles. Ad-
ditionally, the role provides thedropDatabase(page 378) action.
clusterManager
Provides management and monitoring actions on the cluster. A user with this role can access theconfigand
localdatabases, which are used in sharding and replication, respectively.
Provides the following actions on the cluster as a whole:
addShard(page 377)
applicationMessage (page 378)
cleanupOrphaned(page 376)
flushRouterConfig(page 377)
listShards(page 377)
removeShard(page 377)
replSetConfigure(page 377)
replSetGetStatus(page 377)
replSetStateChange (page 377)
resync(page 377)
Provides the following actions onalldatabases in the cluster:
enableSharding(page 377)
moveChunk(page 377)
splitChunk(page 378)
splitVector(page 378)
On theconfigdatabase, provides the following actions on thesettings(page 683) collection:
364 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
insert(page 375)
remove(page 375)
update(page 375)
On theconfigdatabase, provides the following actions on all conguration collections and on the
system.indexes(page 271),system.js(page 271), andsystem.namespaces (page 271) collec-
tions:
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
On thelocaldatabase, provides the following actions on thereplset(page 600) collection:
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
clusterMonitor
Provides read-only access to monitoring tools, such as the
57
monitoring
agent.
Provides the following actions on the cluster as a whole:
connPoolStats(page 379)
cursorInfo(page 379)
getCmdLineOpts(page 379)
getLog(page 379)
getParameter(page 378)
getShardMap(page 377)
hostInfo(page 378)
inprog(page 376)
listDatabases(page 379)
listShards(page 377)
netstat(page 379)
replSetGetStatus(page 377)
serverStatus(page 379)
shardingState(page 377)
top(page 379)
57
http://mms.mongodb.com/help/
6.4. Security Reference 365

MongoDB Documentation, Release 2.6.4
Provides the following actions onalldatabases in the cluster:
collStats(page 379)
dbStats(page 379)
getShardVersion(page 377)
Provides thefind(page 375) action on allsystem.profile(page 271) collections in the cluster.
Provides the following actions on theconfigdatabase's conguration collections andsystem.indexes
(page 271),system.js(page 271), andsystem.namespaces(page 271) collections:
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
hostManager
Provides the ability to monitor and manage servers.
Provides the following actions on the cluster as a whole:
applicationMessage (page 378)
closeAllDatabases(page 378)
connPoolSync(page 378)
cpuProfiler(page 376)
diagLogging(page 379)
flushRouterConfig(page 377)
fsync(page 378)
invalidateUserCache (page 376)
killop(page 376)
logRotate(page 378)
resync(page 377)
setParameter(page 379)
shutdown(page 379)
touch(page 379)
unlock(page 376)
Provides the following actions onalldatabases in the cluster:
killCursors(page 376)
repairDatabase(page 378)
366 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Backup and Restoration Roles
Theadmindatabase includes the following roles for backing up and restoring data:
backup
Provides minimal privileges needed for backing up data. This role provides sufcient privileges to use the
MongoDB Management Service (MMS)
58
backup agent, or to usemongodumpto back up an entiremongod
instance.
Provides the followingactions(page 375) on themms.backupcollection in theadmindatabase:
insert(page 375)
update(page 375)
Provides thelistDatabases(page 379) action on the cluster as a whole.
Provides thefind(page 375) action on the following:
allnon-system collections in the cluster
all the following system collections in the cluster:system.indexes (page 271),
system.namespaces(page 271), andsystem.js(page 271)
theadmin.system.users (page 271) andadmin.system.roles (page 270) collections
legacysystem.userscollections from versions of MongoDB prior to 2.6
restore
Provides minimal privileges needed for restoring data from backups. This role provides sufcient privileges to
use themongorestoretool to restore an entiremongodinstance.
Provides the following actions on allnon-system collections andsystem.js(page 271) collections in the
cluster; on theadmin.system.users (page 271) andadmin.system.roles (page 270) collections in
theadmindatabase; and on legacysystem.userscollections from versions of MongoDB prior to 2.6:
collMod(page 378)
createCollection(page 375)
createIndex(page 375)
dropCollection(page 376)
insert(page 375)
Provides the followingadditionalactions onadmin.system.users (page 271) and legacy
system.userscollections:
find(page 375)
remove(page 375)
update(page 375)
Provides thefind(page 375) action on all thesystem.namespaces(page 271) collections in the cluster.
Although,restore(page 367) includes the ability to modify the documents in theadmin.system.users
(page 271) collection using normal modication operations,onlymodify these data using theuser management
methods.
58
http://mms.mongodb.com/help/
6.4. Security Reference 367

MongoDB Documentation, Release 2.6.4
All-Database Roles
Theadmindatabase provides the following roles that apply to all databases in amongodinstance and are roughly
equivalent to their single-database equivalents:
readAnyDatabase
Provides the same read-only permissions asread(page 362), except it applies toalldatabases in the cluster.
The role also provides thelistDatabases(page 379) action on the cluster as a whole.
readWriteAnyDatabase
Provides the same read and write permissions asreadWrite(page 362), except it applies toalldatabases in
the cluster. The role also provides thelistDatabases(page 379) action on the cluster as a whole.
userAdminAnyDatabase
Provides the same access to user administration operations asuserAdmin(page 363), except it applies toall
databases in the cluster. The role also provides the following actions on the cluster as a whole:
authSchemaUpgrade(page 376)
invalidateUserCache (page 376)
listDatabases(page 379)
The role also provides the following actions on theadmin.system.users (page 271) and
admin.system.roles (page 270) collections on theadmindatabase, and on legacysystem.users
collections from versions of MongoDB prior to 2.6:
collStats(page 379)
dbHash(page 379)
dbStats(page 379)
find(page 375)
killCursors(page 376)
planCacheRead(page 376)
TheuserAdminAnyDatabase (page 368) role does not restrict the permissions that a user can grant. As
a result,userAdminAnyDatabase (page 368) users can grant themselves privileges in excess of their cur-
rent privileges and even can grant themselvesall privileges, even though the role does not explicitly authorize
privileges beyond user administration. This role is effectively a MongoDB systemsuperuser(page 368).
dbAdminAnyDatabase
Provides the same access to database administration operations asdbAdmin(page 363), except it applies to
alldatabases in the cluster. The role also provides thelistDatabases(page 379) 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 assignthemselvesany privilege on any database:
dbOwner(page 363) role, when scoped to theadmindatabase
userAdmin(page 363) role, when scoped to theadmindatabase
userAdminAnyDatabase (page 368) role
The following role provides full privileges on all resources:
368 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
root
Provides access to the operations and all the resources of thereadWriteAnyDatabase (page 368),
dbAdminAnyDatabase (page 368),userAdminAnyDatabase (page 368) andclusterAdmin
(page 364) rolescombined.
root(page 368) doesnotinclude the ability to insert data directly into thesystem.users(page 271) and
system.roles(page 270) collections in theadmindatabase. Therefore,root(page 368) is not suitable for
restoring data that have these collections withmongorestore. To perform these kinds of restore operations,
provision users with therestore(page 367) role.
Internal Role
__system
MongoDB assigns this role to user objects that represent cluster members, such as replica set members and
mongosinstances. The role entitles its holder to take any action against any object in the database.
Do notassign this role to user objects representing applications or human administrators, other than in excep-
tional circumstances.
If you need access to all actions on all resources, for example to run theevalorapplyOpscommands, do
not assign this role. Instead,create a user-dened rolethat grantsanyAction(page 380) onanyResource
(page 375) and ensure that only the users who needs access to these operations has this access.
system.rolesCollection
New in version 2.6.
Thesystem.rolescollection in theadmindatabase stores the user-dened roles. To create and manage these
user-dened roles, MongoDB providesrole management commands.
system.rolesSchema
The documents in thesystem.rolescollection have the following schema:
{
_id:system-defined id>,
role:,
db:,
privileges:
[
{
resource:resource>
actions:, ... ]
},
...
],
roles:
[
{ role:, db:
...
]
}
Asystem.rolesdocument has the following elds:
6.4. Security Reference 369

MongoDB Documentation, Release 2.6.4
admin.system.roles.role
Therole(page 369) eld is a string that species the name of the role.
admin.system.roles.db
Thedb(page 370) eld is a string that species the database to which the role belongs. MongoDB uniquely
identies each role by the pairing of its name (i.e.role(page 369)) and its database.
admin.system.roles.privileges
Theprivileges(page 370) array contains the privilege documents that dene theprivileges(page 286) for
the role.
A privilege document has the following syntax:
{
resource:resource>
actions:, ... ]
}
Each privilege document has the following elds:
admin.system.roles.privileges[n]. resource
A document that species the resources upon which the privilegeactions(page 370) apply. The docu-
ment has one of the following form:
{ db:database>, collection:collection>
or
{ cluster true}
SeeResource Document(page 373) for more details.
admin.system.roles.privileges[n]. actions
An array of actions permitted on the resource. For a list of actions, seePrivilege Actions(page 375).
admin.system.roles.roles
Theroles(page 370) array contains role documents that specify the roles from which this roleinherits
(page 286) privileges.
A role document has the following syntax:
{ role:, db:
A role document has the following elds:
admin.system.roles.roles[n]. role
The name of the role. A role can be abuilt-in role(page 361) provided by MongoDB or auser-dened
role(page 286).
admin.system.roles.roles[n]. db
The name of the database where the role is dened.
Examples
Consider the following sample documents found insystem.rolescollection of theadmindatabase.
A User-Dened Role Species PrivilegesThe following is a sample document for a user-dened roleappUser
dened for themyAppdatabase:
370 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
{
_id:,
role:,
db:,
privileges:
{ resource:::
actions:,,,
{ resource::, collection:
actions:
{ resource::, collection:
actions:,,,
{ resource::, collection:
actions:
{ resource::, collection:
actions:
],
roles:
}
Theprivilegesarray lists the ve privileges that theappUserrole species:
"find","createCollection","dbStats","collStats") on
all the collections in themyAppdatabaseexcludingits system collections. SeeSpecify a Database as Resource
(page 373).
additionalactions on specic collections,logsanddata, in themyApp
database. SeeSpecify a Collection of a Database as Resource(page 373).
system collections(page 270) in themyAppdatabase. While
the rst privilege gives database-wide permission for thefindaction, the action does not apply tomyApp`s
system collections. To give access to a system collection, a privilege must explicitly specify the collection. See
Resource Document(page 373).
As indicated by the emptyrolesarray,appUserinherits no additional privileges from other roles.
User-Dened Role Inherits from Other RolesThe following is a sample document for a user-dened role
appAdmindened for themyAppdatabase: The document shows that theappAdminrole species privileges
as well as inherits privileges from other roles:
{
_id:,
role:,
db:,
privileges:
{
resource::, collection:
actions:,,,,
}
],
roles:
{ role:, db:
]
}
Theprivilegesarray lists the privileges that theappAdminrole species. This role has a single privilege that
permits its actions ("insert","dbStats","collStats","compact","repairDatabase") on all the
collections in themyAppdatabaseexcludingits system collections. SeeSpecify a Database as Resource(page 373).
6.4. Security Reference 371

MongoDB Documentation, Release 2.6.4
Therolesarray lists the roles, identied by the role names and databases, from which the roleappAdmininherits
privileges.
system.usersCollection
Changed in version 2.6.
Thesystem.userscollection in theadmindatabase stores userauthentication(page 282) andauthorization
(page 285) information. To manage data in this collection, MongoDB providesuser management commands.
system.usersSchema
The documents in thesystem.userscollection have the following schema:
{
_id:system defined id>,
user:,
db:,
credentials:authentication credentials>
roles:
{ role:, db:
...
],
customData:custom information>
}
Eachsystem.usersdocument has the following elds:
admin.system.users.user
Theuser(page 372) eld is a string that identies the user. A user exists in the context of a single logical
database but can have access to other databases through roles specied in theroles(page 372) array.
admin.system.users.db
Thedb(page 372) eld species 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 theroles(page 372)
array.
admin.system.users.credentials
Thecredentials(page 372) eld contains the user's authentication information. For users with externally
stored authentication credentials, such as users that useKerberos(page 331) or x.509 certicates for authentica-
tion, thesystem.usersdocument for that user does not contain thecredentials(page 372) eld.
admin.system.users.roles
Theroles(page 372) array contains role documents that specify the roles granted to the user. The array
contains bothbuilt-in roles(page 361) anduser-dened role(page 286).
A role document has the following syntax:
{ role:, db:
A role document has the following elds:
admin.system.users.roles[n]. role
The name of a role. A role can be abuilt-in role(page 361) provided by MongoDB or acustom user-dened
role(page 286).
admin.system.users.roles[n]. db
The name of the database where role is dened.
372 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
When specifying a role using therole managementoruser managementcommands, 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
ThecustomData(page 373) eld contains optional custom information about the user.
Example
Consider the following document in thesystem.userscollection:
{
_id:,
user:,
db:,
credentials:"<hashed password>"
roles
{ role:, db:
{ role:, db:
{ role:, db:
],
customData::
}
The document shows that a userKariis associated with thehomedatabase.Karihas theread(page 362) role
in thehomedatabase, thereadWrite(page 362) role in thetestdatabase, and theappUserrole in themyApp
database.
Resource Document
The resource document species the resources upon which a privilege permitsactions.
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 ResourceIf the resource document species both thedbancollection
elds as non-empty strings, the resource is the specied collection in the specied database. For example, the following
document species a resource of theinventorycollection in theproductsdatabase:
{ db:, collection:
For a user-dened role scoped for a non-admindatabase, the resource specication for its privileges must specify the
same database as the role. User-dened roles scoped for theadmindatabase can specify other databases.
Specify a Database as ResourceIf only thecollectioneld is an empty string (""), the resource is the specied
database, excluding thesystem collections(page 270). For example, the following resource document species the
resource of thetestdatabase, excluding the system collections:
{ db:, collection:
6.4. Security Reference 373

MongoDB Documentation, Release 2.6.4
For a user-dened role scoped for a non-admindatabase, the resource specication for its privileges must specify the
same database as the role. User-dened roles scoped for theadmindatabase 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:, collection:
System collections include but are not limited to the following:
<database>.system.profile (page 271)
<database>.system.namespaces (page 271)
<database>.system.indexes (page 271)
<database>.system.js (page 271)
local.system.replset (page 600)
system.users Collection(page 372) in theadmindatabase
system.roles Collection(page 369) in theadmindatabase
Specify Collections Across Databases as ResourceIf only thedbeld is an empty string (""), the resource is all
collections with the specied name across all databases. For example, the following document species the resource
of all theaccountscollections across all the databases:
{ db:, collection:
For user-dened roles, only roles scoped for theadmindatabase can have this resource specication for their privi-
leges.
Specify All Non-System Collections in All DatabasesIf both thedbandcollectionelds are empty strings
(""), the resource is all collections, excluding thesystem collections(page 270), in all the databases:
{ db:, collection:
For user-dened roles, only roles scoped for theadmindatabase can have this resource specication for their privi-
leges.
Cluster Resource
To specify the cluster as the resource, use the following syntax:
{ cluster true}
Use theclusterresource for actions that affect the state of the system rather than act on specic set of databases
or collections. Examples of such actions areshutdown,replSetReconfig, andaddShard. For example, the
following document grants the actionshutdownon thecluster.
{ resource: true}, actions:
For user-dened roles, only roles scoped for theadmindatabase can have this resource specication for their privi-
leges.
374 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
anyResource
The internal resourceanyResourcegives access to every resource in the system and is intended for internal use.
Do notuse this resource, other than in exceptional circumstances. The syntax for this resource is{ anyResource:
true }.
Privilege Actions
New in version 2.6.
Privilege actions dene the operations a user can perform on aresource(page 373). A MongoDBprivilege(page 286)
comprises aresource(page 373) and the permitted actions. This page lists available actions grouped by common
purpose.
MongoDB provides built-in roles with pre-dened pairings of resources and permitted actions. For lists of the actions
granted, seeBuilt-In Roles(page 361). To dene custom roles, seeCreate a Role(page 347).
Query and Write Actions
find
User can perform thedb.collection.find() method. Apply this action to database or collection re-
sources.
insert
User can perform theinsertcommand. Apply this action to database or collection resources.
remove
User can perform thedb.collection.remove() method. Apply this action to database or collection
resources.
update
User can perform theupdatecommand. 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 thedb.createCollection() method. Apply this action to database or collection re-
sources.
createIndex
Provides access to thedb.collection.createIndex() method and thecreateIndexescommand.
Apply this action to database or collection resources.
6.4. Security Reference 375

MongoDB Documentation, Release 2.6.4
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 thedb.collection.drop() method. Apply this action to database or collection re-
sources.
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 theemptycappedcommand. Apply this action to database or collection resources.
enableProfiler
User can perform thedb.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 thedb.fsyncUnlock()method. Apply this action to theclusterresource.
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 theauthSchemaUpgradecommand. Apply this action to theclusterresource.
cleanupOrphaned
User can perform thecleanupOrphanedcommand. Apply this action to theclusterresource.
cpuProfiler
User can enable and use the CPU proler. Apply this action to theclusterresource.
inprog
User can use thedb.currentOp()method to return pending and active operations. Apply this action to the
clusterresource.
invalidateUserCache
Provides access to theinvalidateUserCache command. Apply this action to theclusterresource.
killop
User can perform thedb.killOp()method. Apply this action to theclusterresource.
376 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
planCacheRead
User can perform theplanCacheListPlans andplanCacheListQueryShapes commands and the
PlanCache.getPlansByQuery() andPlanCache.listQueryShapes() methods. Apply this ac-
tion 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 thestorageDetailscommand. Apply this action to database or collection resources.
Replication Actions
appendOplogNote
User can append notes to the oplog. Apply this action to theclusterresource.
replSetConfigure
User can congure a replica set. Apply this action to theclusterresource.
replSetGetStatus
User can perform thereplSetGetStatuscommand. Apply this action to theclusterresource.
replSetHeartbeat
User can perform thereplSetHeartbeatcommand. Apply this action to theclusterresource.
replSetStateChange
User can change the state of a replica set through thereplSetFreeze,replSetMaintenance,
replSetStepDown, andreplSetSyncFromcommands. Apply this action to theclusterresource.
resync
User can perform theresynccommand. Apply this action to theclusterresource.
Sharding Actions
addShard
User can perform theaddShardcommand. Apply this action to theclusterresource.
enableSharding
User can enable sharding on a database using theenableShardingcommand and can shard a collection
using theshardCollectioncommand. Apply this action to database or collection resources.
flushRouterConfig
User can perform theflushRouterConfigcommand. Apply this action to theclusterresource.
getShardMap
User can perform thegetShardMapcommand. Apply this action to theclusterresource.
getShardVersion
User can perform thegetShardVersioncommand. Apply this action to database resources.
listShards
User can perform thelistShardscommand. Apply this action to theclusterresource.
moveChunk
User can perform themoveChunkcommand. Apply this action to theclusterresource.
removeShard
User can perform theremoveShardcommand. Apply this action to theclusterresource.
6.4. Security Reference 377

MongoDB Documentation, Release 2.6.4
shardingState
User can perform theshardingStatecommand. Apply this action to theclusterresource.
splitChunk
User can perform thesplitChunkcommand. Apply this action to database or collection resources.
splitVector
User can perform thesplitVectorcommand. Apply this action to database or collection resources.
Server Administration Actions
applicationMessage
User can perform thelogApplicationMessage command. Apply this action to theclusterresource.
closeAllDatabases
User can perform thecloseAllDatabasescommand. Apply this action to theclusterresource.
collMod
User can perform thecollModcommand. Apply this action to database or collection resources.
compact
User can perform thecompactcommand. Apply this action to database or collection resources.
connPoolSync
User can perform theconnPoolSynccommand. Apply this action to theclusterresource.
convertToCapped
User can perform theconvertToCappedcommand. Apply this action to database or collection resources.
dropDatabase
User can perform thedropDatabasecommand. Apply this action to database resources.
dropIndex
User can perform thedropIndexescommand. Apply this action to database or collection resources.
fsync
User can perform thefsynccommand. Apply this action to theclusterresource.
getParameter
User can perform thegetParametercommand. Apply this action to theclusterresource.
hostInfo
Provides information about the server the MongoDB instance runs on. Apply this action to thecluster
resource.
logRotate
User can perform thelogRotatecommand. Apply this action to theclusterresource.
reIndex
User can perform thereIndexcommand. Apply this action to database or collection resources.
renameCollectionSameDB
Allows the user to rename collections on the current database using therenameCollectioncommand.
Apply this action to database resources.
Additionally, the user must eitherhavefind(page 375) on the source collection ornot havefind(page 375)
on the destination collection.
If a collection with the new name already exists, the user must also have thedropCollection(page 376)
action on the destination collection.
378 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
repairDatabase
User can perform therepairDatabasecommand. Apply this action to database resources.
setParameter
User can perform thesetParametercommand. Apply this action to theclusterresource.
shutdown
User can perform theshutdowncommand. Apply this action to theclusterresource.
touch
User can perform thetouchcommand. Apply this action to theclusterresource.
Diagnostic Actions
collStats
User can perform thecollStatscommand. Apply this action to database or collection resources.
connPoolStats
User can perform theconnPoolStatsandshardConnPoolStats commands. Apply this action to the
clusterresource.
cursorInfo
User can perform thecursorInfocommand. Apply this action to theclusterresource.
dbHash
User can perform thedbHashcommand. Apply this action to database or collection resources.
dbStats
User can perform thedbStatscommand. Apply this action to database resources.
diagLogging
User can perform thediagLoggingcommand. Apply this action to theclusterresource.
getCmdLineOpts
User can perform thegetCmdLineOptscommand. Apply this action to theclusterresource.
getLog
User can perform thegetLogcommand. Apply this action to theclusterresource.
indexStats
User can perform theindexStatscommand. Apply this action to database or collection resources.
listDatabases
User can perform thelistDatabasescommand. Apply this action to theclusterresource.
netstat
User can perform thenetstatcommand. Apply this action to theclusterresource.
serverStatus
User can perform theserverStatuscommand. Apply this action to theclusterresource.
validate
User can perform thevalidatecommand. Apply this action to database or collection resources.
top
User can perform thetopcommand. Apply this action to theclusterresource.
6.4. Security Reference 379

MongoDB Documentation, Release 2.6.4
Internal Actions
anyAction
Allows any action on a resource.Do notassign this action except for exceptional circumstances.
internal
Allows internal actions.Do notassign 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 formongodandmongosinstances. You can change this port withportor
--port.
27018 The default port when running with--shardsvrruntime operation or theshardsvrvalue for the
clusterRolesetting in a conguration le.
27019 The default port when running with--configsvrruntime operation or theconfigsvrvalue for
theclusterRolesetting in a conguration le.
28017 The default port for the web status page. The web status page is always accessible at a port number
that is1000greater than the port determined byport.
System Event Audit Messages
Note:Theaudit system(page 290) is available only in
59
.
Theevent auditing feature(page 290) can record events in JSON format. 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> }, ... ],
params: <document>,
result: <int>
}
eld String atypeAction type. SeeEvent Actions, Details, and Results(page 381).
eld document tsDocument that contains the date and UTC time of the event, in ISO 8601 format.
eld document localDocument that contains the localipaddress and theportnumber of the running
instance.
eld document remoteDocument that contains the remoteipaddress and theportnumber of the
incoming connection associated with the event.
eld array usersArray of user identication 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
usereld for the username and adbeld for the authentication database for that user.
59
http://www.mongodb.com/products/mongodb-enterprise
380 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
eld document paramsSpecic details for the event. SeeEvent Actions, Details, and Results
(page 381).
eld integer resultError code. SeeEvent Actions, Details, and Results(page 381).
Event Actions, Details, and Results
The following table lists for eachatypeor action type, the associatedparamsdetails and theresultvalues, if
any.
atype params result Notes
authenticate
{
user:user name>,
db:database>,
mechanism:mechanism>
}
0- Success
18- Authentication Failed
authCheck
{
command:name>,
ns:database>.<collection>,
args:command object>
}
0- Success
13- Unauthorized to per-
form the operation.
The auditing system logs
only authorizationfailures.
nseld is optional.
argseld may be
redacted.
createCollection
(page 375) { ns:database>.<collection>
0- Success
createDatabase
{ ns:database>
0- Success
createIndex(page 375)
{
ns:database>.<collection>,
indexName:index name>,
indexSpec:full index specification>
}
0- Success
renameCollection
{
old: <database>.<collection>,
new: <database>.<collection>
}
0- Success
dropCollection
(page 376) { ns:database>.<collection>
0- Success
dropDatabase
(page 378) { ns:database>
0- Success
Continued on next page
6.4. Security Reference 381

MongoDB Documentation, Release 2.6.4
Table 6.1 continued from previous page
atype params result Notes
dropIndex(page 378)
{
ns:database>.<collection>,
indexName:index name>
}
0- Success
createUser(page 376)
{
user:user name>,
db:database>,
customData:document>,
roles:role1>, ... ]
}
0- Success customDataeld is op-
tional.
dropUser(page 376)
{
user:user name>,
db:database>
}
0- Success
dropAllUsersFromDatabase
{ db:database>
0- Success
updateUser
{
user:user name>,
db:database>,
passwordChanged: boolean>,
customData:document>,
roles:role1>, ... ]
}
0- Success customDataeld is op-
tional.
grantRolesToUser
{
user:user name>,
db:database>,
roles:role1>, ... ]
}
0- Success Therolesarray contains
role documents. Seerole
Document(page 384).
revokeRolesFromUser
{
user:user name>,
db:database>,
roles:role1>, ... ]
}
0- Success Therolesarray contains
role documents. Seerole
Document(page 384).
Continued on next page
382 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
Table 6.1 continued from previous page
atype params result Notes
createRole(page 375)
{
role:role name>,
db:database>,
roles:role1>, ... ],
privileges:privilege1>, ... ]
}
0- Success Eitherrolesor the
privilegeseld can be
optional.
Therolesarray contains
role documents. Seerole
Document(page 384).
Theprivilegesarray
contains privilege doc-
uments. See privilege
Document(page 384).
updateRole
{
role:role name>,
db:database>,
roles:role1>, ... ],
privileges:privilege1>, ... ]
}
0- Success Eitherrolesor the
privilegeseld can be
optional.
Therolesarray contains
role documents. Seerole
Document(page 384).
Theprivilegesarray
contains privilege doc-
uments. See privilege
Document(page 384).
dropRole(page 376)
{
role:role name>,
db:database>
}
0- Success
dropAllRolesFromDatabase
{ db:database>
0- Success
grantRolesToRole
{
role:role name>,
db:database>,
roles:role1>, ... ]
}
0- Success Therolesarray contains
role documents. Seerole
Document(page 384).
revokeRolesFromRole
{
role:role name>,
db:database>,
roles:role1>, ... ]
}
0- Success Therolesarray contains
role documents. Seerole
Document(page 384).
grantPrivilegesToRole
{
role:role name>,
db:database>,
privileges:privilege1>, ... ]
}
0- Success Theprivilegesarray
contains privilege doc-
uments. See privilege
Document(page 384).
Continued on next page
6.4. Security Reference 383

MongoDB Documentation, Release 2.6.4
Table 6.1 continued from previous page
atype params result Notes
revokePrivilegesFromRole
{
role:role name>,
db:database name>,
privileges:privilege1>, ... ]
}
0- Success Theprivilegesarray
contains privilege doc-
uments. See privilege
Document(page 384).
replSetReconfig
{
old: <configuration>,
new: <configuration>
}
0- Success
enableSharding
(page 377) { ns:database>
0- Success
shardCollection
{
ns:database>.<collection>,
key:shard key pattern>,
options:: boolean>
}
0- Success
addShard(page 377)
{
shard:shard name>,
connectionString:hostname>:<port>,
maxSize:maxSize>
}
0- Success When a shard is
a replica set, the
connectionString
includes the replica set
name and can include other
members of the replica set.
removeShard(page 377)
{ shard:shard name>
0- Success
shutdown(page 379)
{ }
0- Success Indicates commencement
of database shutdown.
applicationMessage
(page 378) { msg:custom message string>
0- Success See
logApplicationMessage .
Additional Information
roleDocumentThe<role>document in therolesarray has the following form:
{
role:role name>,
db:database>
}
privilegeDocumentThe<privilege>document in theprivilegearray has the following form:
384 Chapter 6. Security

MongoDB Documentation, Release 2.6.4
{
resource:resource>
actions:action>, ... ]
}
SeeResource Document(page 373) for details on the resource document. For a list of actions, seePrivilege Actions
(page 375).
6.4.3
Security Release Notes(page 385)Security vulnerability for password.
Security Release Notes
Access tosystem.usersCollection
Changed in version 2.4.
In 2.4, only users with theuserAdminrole have access to thesystem.userscollection.
In version 2.2 and earlier, the read-write users of a database all have access to thesystem.userscollection, which
contains the user names and user password hashes.
60
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.
60
Read-only users do not have access to thesystem.userscollection.
6.4. Security Reference 385

MongoDB Documentation, Release 2.6.4
386 Chapter 6. Security

CHAPTER7
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: theaggregation pipeline(page 391), themap-reduce function
(page 394), andsingle purpose aggregation methods and commands(page 395).
Aggregation Introduction(page 387)A high-level introduction to aggregation.
Aggregation Concepts(page 391)Introduces the use and operation of the data aggregation modalities available in
MongoDB.
Aggregation Pipeline(page 391)The aggregation pipeline is a framework for performing aggregation tasks,
modeled on the concept of data processing pipelines. Using this framework, MongoDB passes the doc-
uments of a single collection through a pipeline. The pipeline transforms the documents into aggregated
results, and is accessed through theaggregatedatabase command.
Map-Reduce(page 394)Map-reduce is a generic multi-phase data aggregation modality for processing quan-
tities of data. MongoDB provides map-reduce with themapReducedatabase command.
Single Purpose Aggregation Operations(page 395)MongoDB provides a collection of specic data aggrega-
tion operations to support a number of common data aggregation functions. These operations include
returning counts of documents, distinct values of a eld, and simple grouping operations.
Aggregation Mechanics(page 398)Details internal optimization operations, limits, support for sharded col-
lections, and concurrency concerns.
Aggregation Examples(page 403)Examples and tutorials for data aggregation operations in MongoDB.
Aggregation Reference(page 419)References for all aggregation operations material for all data aggregation meth-
ods in MongoDB.
7.1
Aggregationsare 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
mongodinstance simplies application code and limits resource requirements.
Like queries, aggregation operations in MongoDB usecollectionsof documents as an input and return results in the
form of one or more documents.
387

MongoDB Documentation, Release 2.6.4
7.1.1
Aggregation Pipelines
MongoDB 2.2 introduced a newaggregation framework(page 391), 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 provideltersthat operate like queries anddocument transformationsthat modify the
form of the output document.
Other pipeline operations provide tools for grouping and sorting documents by specic eld or elds as well as tools
for aggregating the contents of arrays, including arrays of documents. In addition, pipeline stages can useoperators
for tasks such as calculating the average or concatenating a string.
The pipeline provides efcient data aggregation using native operations within MongoDB, and is the preferred method
for data aggregation in MongoDB.
Figure 7.1: Diagram of the annotated aggregation pipeline operation. The aggregation pipeline has two stages:
$matchand$group.
Map-Reduce
MongoDB also providesmap-reduce(page 394) operations to perform aggregation. In general, map-reduce operations
have two phases: amapstage that processes each document andemitsone or more objects for each input document,
388 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
andreducephase that combines the output of the map operation. Optionally, map-reduce can have analizestage to
make nal modications 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 optionalnalize
operation. While the custom JavaScript provide great exibility compared to the aggregation pipeline, in general, map-
reduce is less efcient and more complex than the aggregation pipeline.
Note:Starting in MongoDB 2.4, certainmongoshell functions and properties are inaccessible in map-reduce op-
erations. 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.
Figure 7.2: Diagram of the annotated map-reduce operation.
Single Purpose Aggregation Operations
For a number of commonsingle purpose aggregation operations(page 395), MongoDB provides special purpose
database commands. These common aggregation operations are: returning a count of matching documents, returning
the distinct values for a eld, and grouping data based on the values of a eld. All of these operations aggregate
documents from a single collection. While these operations provide simple access to common aggregation processes,
they lack the exibility and capabilities of the aggregation pipeline and map-reduce.
7.1. Aggregation Introduction 389

MongoDB Documentation, Release 2.6.4
Figure 7.3: Diagram of the annotated distinct operation.
390 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
7.1.2
Both the aggregation pipeline and map-reduce can operate on asharded collection(page 607). Map-reduce operations
can also output to a sharded collection. SeeAggregation Pipeline and Sharded Collections(page 401) andMap-Reduce
and Sharded Collections(page 402) for details.
The aggregation pipeline can use indexes to improve its performance during some of its stages. In addition, the aggre-
gation pipeline has an internal optimization phase. SeePipeline Operators and Indexes(page 393) andAggregation
Pipeline Optimization(page 398) for details.
For a feature comparison of the aggregation pipeline, map-reduce, and the special group functionality, seeAggregation
Commands Comparison(page 424).
7.2
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 specic to each approach. See
also thechart(page 424) that compares the approaches.
Aggregation Pipeline(page 391)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 theaggregatedatabase command.
Map-Reduce(page 394)Map-reduce is a generic multi-phase data aggregation modality for processing quantities of
data. MongoDB provides map-reduce with themapReducedatabase command.
Single Purpose Aggregation Operations(page 395)MongoDB provides a collection of specic data aggregation op-
erations to support a number of common data aggregation functions. These operations include returning counts
of documents, distinct values of a eld, and simple grouping operations.
Aggregation Mechanics(page 398)Details internal optimization operations, limits, support for sharded collections,
and concurrency concerns.
7.2.1
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 tomap-reduceand 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. SeeAggregation Pipeline Limits(page 401)
for details on limits and restrictions on the aggregation pipeline.
Pipeline
The MongoDB aggregation pipeline consists ofstages. 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 lter out documents. Pipeline stages can appear multiple times in the pipeline.
MongoDB provides thedb.collection.aggregate() method in themongoshell and theaggregatecom-
mand for aggregation pipeline. Seeaggregation-pipeline-operator-referencefor the available stages.
7.2. Aggregation Concepts 391

MongoDB Documentation, Release 2.6.4
Figure 7.4: Diagram of the annotated aggregation pipeline operation. The aggregation pipeline has two stages:
$matchand$group.
392 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
For example usage of the aggregation pipeline, considerAggregation with User Preference Data(page 407) and
Aggregation with the Zip Code Data Set(page 404).
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 adocument(page 158) structure and can contain otherexpression
(page 420).
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:
accumulatorexpressions.
The accumulators, used with the$grouppipeline operator, maintain their state (e.g. totals, maximums, minimums,
and related data) as documents progress through the pipeline.
For more information on expressions, seeExpressions(page 420).
Aggregation Pipeline Behavior
In MongoDB, theaggregatecommand operates on a single collection, logically passing theentirecollection 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$matchand$sortpipeline operators can take advantage of an index when they occur at thebeginningof the
pipeline.
New in version 2.4: The$geoNearpipeline operator takes advantage of a geospatial index. When using$geoNear,
the$geoNearpipeline operation must appear as the rst 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,
$matchoperations use suitable indexes to scan only the matching documents in a collection.
Placing a$matchpipeline stage followed by a$sortstage at the start of the pipeline is logically equivalent to a
single query with a sort and can use an index. When possible, place$matchoperators 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, seeAggregation Pipeline Optimization(page 398).
The aggregation pipeline supports operations on sharded collections. SeeAggregation Pipeline and Sharded Collec-
tions(page 401).
7.2. Aggregation Concepts 393

MongoDB Documentation, Release 2.6.4
7.2.2
Map-reduce is a data processing paradigm for condensing large volumes of data into usefulaggregatedresults. For
map-reduce operations, MongoDB provides themapReducedatabase command.
Consider the following map-reduce operation:
Figure 7.5: Diagram of the annotated map-reduce operation.
In this map-reduce operation, MongoDB applies themapphase 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 thereducephase, 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 analizefunction to further
condense or process the results of the aggregation.
All map-reduce functions in MongoDB are JavaScript and run within themongodprocess. Map-reduce operations
take the documents of a singlecollectionas theinputand can perform any arbitrary sorting and limiting before
beginning the map stage.mapReducecan 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, theAggregation Pipeline(page 391) provides better performance and more
coherent interface. However, map-reduce operations provide some exibility that is not presently available in the
aggregation pipeline.
394 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
Map-Reduce JavaScript Functions
In MongoDB, map-reduce operations use custom JavaScript functions tomap, or associate, values to a key. If a key
has multiple values mapped to it, the operationreducesthe values for the key to a single object.
The use of custom JavaScript functions provide exibility 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 nal modications 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. SeemapReduceandPerform Incremental
Map-Reduce(page 413) for details and examples.
When returning the results of a map reduce operationinline, the result documents must be within theBSON
Document Sizelimit, which is currently 16 megabytes. For additional information on limits and restrictions on
map-reduce operations, see thehttp://docs.mongodb.org/manualreference/command/mapReduce
reference page.
MongoDB supports map-reduce operations onsharded collections(page 607). Map-reduce operations can also output
the results to a sharded collection. SeeMap-Reduce and Sharded Collections(page 402).
7.2.3
Aggregation refers to a broad class of data manipulation operations that compute a result based on an inputanda spe-
cic procedure. MongoDB provides a number of aggregation operations that perform specic aggregation operations
on a set of data.
Although limited in scope, particularly compared to theaggregation pipeline(page 391) andmap-reduce(page 394),
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. Thecountcommand as well as the
count()andcursor.count()methods provide access to counts in themongoshell.
Example
Given a collection namedrecordswithonlythe following documents:
{ a:, b:
{ a:, b:
{ a:, b:
{ a:, b:
The following operation would count all documents in the collection and return the number4:
db.records.count()
The following operation will count only the documents where the value of the eldais1and return3:
db.records.count( { a:
7.2. Aggregation Concepts 395

MongoDB Documentation, Release 2.6.4
Distinct
Thedistinctoperation takes a number of documents that match a query and returns all of the unique values for a eld
in the matching documents. Thedistinctcommand anddb.collection.distinct() method provide this
operation in themongoshell. Consider the following examples of a distinct operation:
Figure 7.6: Diagram of the annotated distinct operation.
Example
Given a collection namedrecordswithonlythe following documents:
{ a:, b:
{ a:, b:
{ a:, b:
{ a:, b:
{ a:, b:
396 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
{ a:, b:
Consider the followingdb.collection.distinct() operation which returns the distinct values of the eldb:
db.records.distinct(
The results of this operation would resemble:
[,,,
Group
Thegroupoperation takes a number of documents that match a query, and then collects groups of documents based
on the value of a eld or elds. It returns an array of documents with computed results for each group of documents.
Access the grouping functionality via thegroupcommand or thedb.collection.group() method in the
mongoshell.
Warning:groupdoes not support data in sharded collections. In addition, the results of thegroupoperation
must be no larger than 16 megabytes.
Consider the following group operation:
Example
Given a collection namedrecordswith the following documents:
{ a:, count:
{ a:, count:
{ a:, count:
{ a:, count:
{ a:, count:
{ a:, count:
{ a:, count:
Consider the followinggroupoperation which groups documents by the elda, whereais less than3, and sums the
eldcountfor each group:
db.records.group( {
key::
cond:::
reduce: function(cur, result) { result.count
initial::
} )
The results of this group operation would resemble the following:
[
{ a:, count:
{ a:, count:
]
See also:
The$groupfor related functionality in theaggregation pipeline(page 391).
7.2. Aggregation Concepts 397

MongoDB Documentation, Release 2.6.4
7.2.4
This section describes behaviors and limitations for the various aggregation modalities.
Aggregation Pipeline Optimization(page 398)Details the internal optimization of certain pipeline sequence.
Aggregation Pipeline Limits(page 401)Presents limitations on aggregation pipeline operations.
Aggregation Pipeline and Sharded Collections(page 401)Mechanics of aggregation pipeline operations on sharded
collections.
Map-Reduce and Sharded Collections(page 402)Mechanics of map-reduce operation with sharded collections.
Map Reduce Concurrency(page 403)Details the locks taken during map-reduce operations.
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 theexplainoption 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 elds in the documents to obtain the results.
If so, the pipeline will only use those required elds, reducing the amount of data passing through the pipeline.
Pipeline Sequence Optimization
$sort+$matchSequence OptimizationWhen you have a sequence with$sortfollowed by a$match, the
$matchmoves before the$sortto minimize the number of objects to sort. For example, if the pipeline consists of
the following stages:
{ $sort:1
{ $match::
During the optimization phase, the optimizer transforms the sequence to the following:
{ $match::
{ $sort:1
$skip+$limitSequence OptimizationWhen you have a sequence with$skipfollowed by a$limit, the
$limitmoves before the$skip. With the reordering, the$limitvalue increases by the$skipamount.
For example, if the pipeline consists of the following stages:
{ $skip:
{ $limit:
During the optimization phase, the optimizer transforms the sequence to the following:
{ $limit:
{ $skip:
398 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
This optimization allows for more opportunities for$sort + $limit Coalescence(page 399), such as with$sort+
$skip+$limitsequences. See$sort + $limit Coalescence(page 399) for details on the coalescence and$sort +
$skip + $limit Sequence(page 400) for an example.
For aggregation operations onsharded collections(page 401), this optimization reduces the results returned from each
shard.
$redact+$matchSequence OptimizationWhen possible, when the pipeline has the$redactstage immedi-
ately followed by the$matchstage, the aggregation can sometimes add a portion of the$matchstage before the
$redactstage. If the added$matchstage 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. SeePipeline Operators and Indexes
(page 393) for more information.
For example, if the pipeline consists of the following stages:
{ $redact:: if::,:, else:
{ $match::, category::
The optimizer can add the same$matchstage before the$redactstage:
{ $match::
{ $redact:: if::,:, else:
{ $match::, category::
Pipeline Coalescence Optimization
When possible, the optimization phase coalesces a pipeline stage into its predecessor. Generally, coalescence occurs
afterany sequence reordering optimization.
$sort+$limitCoalescenceWhen a$sortimmediately precedes a$limit, the optimizer can coalesce the
$limitinto the$sort. This allows the sort operation to only maintain the topnresults as it progresses, where
nis the specied limit, and MongoDB only needs to storenitems in memory
1
. Seesort-and-memoryfor more
information.
$limit+$limitCoalescenceWhen a$limitimmediately follows another$limit, the two stages can
coalesce into a single$limitwhere the limit amount is thesmallerof the two initial limit amounts. For example, a
pipeline contains the following sequence:
{ $limit:
{ $limit:
Then the second$limitstage can coalesce into the rst$limitstage and result in a single$limitstage where
the limit amount10is the minimum of the two initial limits100and10.
{ $limit:
$skip+$skipCoalescenceWhen a$skipimmediately follows another$skip, the two stages can coalesce
into a single$skipwhere the skip amount is thesumof the two initial skip amounts. For example, a pipeline contains
the following sequence:
{ $skip:
{ $skip:
1
The optimization will still apply whenallowDiskUseistrueand thenitems exceed theaggregation memory limit(page 401).
7.2. Aggregation Concepts 399

MongoDB Documentation, Release 2.6.4
Then the second$skipstage can coalesce into the rst$skipstage and result in a single$skipstage where the
skip amount7is the sum of the two initial limits5and2.
{ $skip:
$match+$matchCoalescenceWhen a$matchimmediately follows another$match, the two stages can
coalesce into a single$matchcombining the conditions with an$and. For example, a pipeline contains the following
sequence:
{ $match::
{ $match::
Then the second$matchstage can coalesce into the rst$matchstage and result in a single$matchstage
{ $match::
Examples
The following examples are some sequences that can take advantage of both sequence reordering and coalescence.
Generally, coalescence occursafterany sequence reordering optimization.
$sort+$skip+$limitSequenceA pipeline contains a sequence of$sortfollowed by a$skipfollowed
by a$limit:
{ $sort:1
{ $skip:
{ $limit:
First, the optimizer performs the$skip + $limit Sequence Optimization(page 398) to transforms the sequence to the
following:
{ $sort:1
{ $limit:
{ $skip:
The$skip + $limit Sequence Optimization(page 398) increases the$limitamount with the reordering. See$skip +
$limit Sequence Optimization(page 398) for details.
The reordered sequence now has$sortimmediately preceding the$limit, and the pipeline can coalesce the two
stages to decrease memory usage during the sort operation. See$sort + $limit Coalescence(page 399) for more
information.
$limit+$skip+$limit+$skipSequenceA pipeline contains a sequence of alternating$limitand
$skipstages:
{ $limit:
{ $skip:
{ $limit:
{ $skip:
The$skip + $limit Sequence Optimization(page 398) reverses the position of the{ $skip: 5 }and{ $limit:
10 }stages and increases the limit amount:
400 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
{ $limit:
{ $limit:},
{ $skip:
{ $skip:
The optimizer then coalesces the two$limitstages into a single$limitstage and the two$skipstages into a
single$skipstage. The resulting sequence is the following:
{ $limit:
{ $skip:
See$limit + $limit Coalescence(page 399) and$skip + $skip Coalescence(page 399) for details.
See also:
explainoption in thedb.collection.aggregate()
Aggregation Pipeline Limits
Aggregation operations with theaggregatecommand have the following limitations.
Result Size Restrictions
If theaggregatecommand returns a single document that contains the complete result set, the command will
produce an error if the result set exceeds theBSON Document Size limit, which is currently 16 megabytes. To
manage result sets that exceed this limit, theaggregatecommand can return result sets ofany sizeif the command
return a cursor or store the results to a collection.
Changed in version 2.6: Theaggregatecommand can return results as a cursor or store the results in a collection,
which are not subject to the size limit. Thedb.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 theallowDiskUseoption to enable aggregation pipeline stages to
write data to temporary les.
See also:
sort-memory-limitandgroup-memory-limit.
Aggregation Pipeline and Sharded Collections
The aggregation pipeline supports operations onshardedcollections. This section describes behaviors specic to the
aggregation pipeline(page 391) and sharded collections.
Behavior
Changed in version 2.6.
7.2. Aggregation Concepts 401

MongoDB Documentation, Release 2.6.4
When operating on a sharded collection, the aggregation pipeline is split into two parts. The rst pipeline runs on each
shard, or if an early$matchcan 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 theprimary shard(page 615). The primary
shard merges the cursors from the other shards and runs the second pipeline on these results. The primary shard
forwards the nal results to themongos. In previous versions, the second pipeline would run on themongos.
2
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 theexplainoption in thedb.collection.aggregate() method.
Optimizations are subject to change between releases.
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 ofmapReducespecic to sharded collections.
Sharded Collection as Input
When using sharded collection as the input for a map-reduce operation,mongoswill automatically dispatch the map-
reduce job to each shard in parallel. There is no special option required.mongoswill wait for jobs on all shards to
nish.
Sharded Collection as Output
Changed in version 2.2.
If theouteld formapReducehas theshardedvalue, MongoDB shards the output collection using the_ideld
as the shard key.
To output to a sharded collection:
_ideld.

operation to create the initialchunksdistributed among the shards.
mongosdispatches, 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 nal
reduce/nalize, and write locally to the output collection.
Note:

currency issues.
In MongoDB 2.0:
2
Until all shards upgrade to v2.6, the second pipeline runs on themongosif any shards are still running v2.4.
402 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
mongosretrieves the results from each shard, performs a merge sort to order the results, and proceeds to the
reduce/nalize phase as needed.mongosthen writes the result to the output collection in sharded mode.

are granular and balanced.
Important:For best results, only use the sharded output options formapReducein 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
mapfunction, executions of thereducefunction, writes to a temporary collection during processing, and writes to
the output collection.
During the operation, map-reduce takes the following locks:

merge,replace,reduce) take a write lock. This
write lock isglobal, and blocks all operations on themongodinstance.
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,finalizefunctions)
executed in a single thread.
Note:The nal write lock during post-processing makes the results appear atomically. However, output actions
mergeandreducemay take minutes to process. For themergeandreduce, thenonAtomicag is available,
which releases the lock between writing each output document. thedb.collection.mapReduce() reference
for more information.
7.3
This document provides the practical examples that display the capabilities ofaggregation(page 391).
Aggregation with the Zip Code Data Set(page 404)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(page 407)Use the pipeline to sort, normalize, and sum data on a collection
of user data.
Map-Reduce Examples(page 411)Dene map-reduce operations that select ranges, group data, and calculate sums
and averages.
Perform Incremental Map-Reduce(page 413)Run a map-reduce operations over one collection and output results
to another collection.
Troubleshoot the Map Function(page 415)Steps to troubleshoot themapfunction.
Troubleshoot the Reduce Function(page 416)Steps to troubleshoot thereducefunction.
7.3. Aggregation Examples 403

MongoDB Documentation, Release 2.6.4
7.3.1
The examples in this document use thezipcodecollection. This collection is available at:
dia.mongodb.org/zips.json
3
. Usemongoimportto load this data set into yourmongodinstance.
Data Model
Each document in thezipcodecollection has the following form:
{
"_id":,
"city":,
"state":,
"pop":,
"loc":
-74.016323,
40.710537
]
}
The_ideld holds the zip code as a string.
Thecityeld 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.
Thestateeld holds the two letter state abbreviation.
Thepopeld holds the population.
Theloceld holds the location as a latitude longitude pair.
All of the following examples use theaggregate()helper in themongoshell.aggregate()provides a wrapper
around theaggregatedatabase command. See the documentation for yourdriverfor a more idiomatic interface
for data aggregation operations.
Return States with Populations above 10 Million
To return all states with a population greater than 10 million, use the following aggregation operation:
db.zipcodes.aggregate( { $group
{ _id,
totalPop
{ $match *1000*1000
Aggregations operations using theaggregate()helper process all documents in thezipcodescollection.
aggregate()connects a number ofpipeline(page 391) operators, which dene the aggregation process.
In this example, the pipeline passes all documents in thezipcodescollection through the following steps:
$groupoperator collects all documents and creates documents for each state.
These new per-state documents have one eld in addition to the_ideld:totalPopwhich is a generated
eld using the$sumoperation to calculate the total value of allpopelds in the source documents.
After the$groupoperation the documents in the pipeline resemble the following:
3
http://media.mongodb.org/zips.json
404 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
{
"_id",
"totalPop"
}
$matchoperation lters these documents so that the only documents that remain are those where the value
oftotalPopis greater than or equal to 10 million.
The$matchoperation does not alter the documents, which have the same format as the documents output by
$group.
The equivalentSQLfor this operation is:
SELECT ,SUM(pop)AStotalPop
FROMzipcodes
GROUP
HAVINGtotalPop=10 *1000*1000)
Return Average City Population by State
To return the average populations for cities in each state, use the following aggregation operation:
db.zipcodes.aggregate( [
{ $group, city
{ $group, avgCityPop
] )
Aggregations operations using theaggregate()helper process all documents in thezipcodescollection.
aggregate()connects a number ofpipeline(page 391) operators that dene the aggregation process.
In this example, the pipeline passes all documents in thezipcodescollection through the following steps:
$groupoperator collects all documents and creates new documents for every combination of thecityand
stateelds in the source document. 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.
After this stage in the pipeline, the documents resemble the following:
{
"_id"
"state",
"city"
},
"pop"
}
$groupoperator collects documents by thestateeld and use the$avgexpression to compute
a value for theavgCityPopeld.
The nal output of this aggregation operation is:
{
"_id",
"avgCityPop"
},
Return Largest and Smallest Cities by State
To return the smallest and largest cities by population for each state, use the following aggregation operation:
7.3. Aggregation Examples 405

MongoDB Documentation, Release 2.6.4
db.zipcodes.aggregate( { $group:
{ _id::, city:
pop::
{ $sort::
{ $group:
{ _id,
biggestCity::
biggestPop::
smallestCity::
smallestPop::
// the following $project is optional, and
// modifies the output format.
{ $project:
{ _id:,
state:,
biggestCity::, pop:
smallestCity::, pop:
Aggregation operations using theaggregate()helper process all documents in thezipcodescollection.
aggregate()combines a number ofpipeline(page 391) operators that dene the aggregation process.
All documents from thezipcodescollection pass into the pipeline, which consists of the following steps:
$groupoperator collects all documents and creates new documents for every combination of thecityand
stateelds in the source documents.
By specifying the value of_idas a sub-document that contains both elds, the operation preserves thestate
eld for use later in the pipeline. The documents produced by this stage of the pipeline have a second eld,
pop, which uses the$sumoperator to provide the total of thepopelds in the source document.
At this stage in the pipeline, the documents resemble the following:
{
"_id"
"state",
"city"
},
"pop"
}
$sortoperator orders the documents in the pipeline based on the value of thepopeld from largest to smallest.
This operation does not alter the documents.
$groupoperator collects the documents in the pipeline by thestateeld, which is a eld inside
the nested_iddocument.
Within each per-state document this$groupoperator species four elds: Using the$lastexpression, the
$groupoperator creates thebiggestcityandbiggestpopelds that store the city with the largest pop-
ulation and that population. Using the$firstexpression, the$groupoperator creates thesmallestcity
andsmallestpopelds that store the city with the smallest population and that population.
The documents, at this stage in the pipeline resemble the following:
{
"_id",
"biggestCity",
"biggestPop",
"smallestCity",
406 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
"smallestPop"
}
$project, which renames the_ideld tostateand moves thebiggestCity,
biggestPop,smallestCity, andsmallestPopintobiggestCityandsmallestCitysub-
documents.
The output of this aggregation operation is:
{
"state",
"biggestCity"
"name",
"pop"
},
"smallestCity"
"name",
"pop"
}
}
7.3.2
Data Model
Consider a hypothetical sports club with a database that contains auserscollection that tracks the user's join dates,
sport preferences, and stores these data in documents that resemble the following:
{
_id,
joined"2011-03-02"),
likes"golf",]
}
{
_id,
joined"2012-07-02"),
likes"tennis",,]
}
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 theuserscollection. You might do this to normalize user names for processing.
db.users.aggregate(
[
{ $project:{$toUpper:"$_id"} , _id:0
{ $sort
]
)
All documents from theuserscollection pass through the pipeline, which consists of the following operations:
$projectoperator:
creates a new eld calledname.
7.3. Aggregation Examples 407

MongoDB Documentation, Release 2.6.4
converts the value of the_idto upper case, with the$toUpperoperator. Then the$projectcreates
a new eld, namednameto hold this value.
suppresses theideld.$projectwill pass the_ideld by default, unless explicitly suppressed.
$sortoperator orders the results by thenameeld.
The results of the aggregation would resemble the following:
{
"name"
},
{
"name"
},
{
"name"
}
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
name,
_id
}
},
{ $sort
]
)
The pipeline passes all documents in theuserscollection through the following operations:
$projectoperator:
Creates two new elds:month_joinedandname.
Suppresses theidfrom the results. Theaggregate()method includes the_id, unless explicitly
suppressed.
$monthoperator converts the values of thejoinedeld to integer representations of the month. Then
the$projectoperator assigns those values to themonth_joinedeld.
$sortoperator sorts the results by themonth_joinedeld.
The operation returns results that resemble the following:
{
"month_joined",
"name"
},
{
"month_joined",
"name"
},
408 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
{
"month_joined",
"name"
}
{
"month_joined",
"name"
}
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
{ $group:"$month_joined"} , number
{ $sort
]
)
The pipeline passes all documents in theuserscollection through the following operations:
$projectoperator creates a new eld calledmonth_joined.
$monthoperator converts the values of thejoinedeld to integer representations of the month. Then
the$projectoperator assigns the values to themonth_joinedeld.
$groupoperator collects all documents with a givenmonth_joinedvalue and counts how many docu-
ments there are for that value. Specically, for each unique value,$groupcreates a new per-month document
with two elds:
_id, which contains a nested document with themonth_joinedeld and its value.
number, which is a generated eld. The$sumoperator increments this eld by 1 for every document
containing the givenmonth_joinedvalue.
$sortoperator sorts the documents created by$groupaccording to the contents of themonth_joined
eld.
The result of this aggregation operation would resemble the following:
{
"_id"
"month_joined"
},
"number"
},
{
"_id"
"month_joined"
},
"number"
},
{
"_id"
"month_joined"
},
7.3. Aggregation Examples 409

MongoDB Documentation, Release 2.6.4
"number"
}
Return the Five Most Common Likes
The following aggregation collects top ve most liked activities in the data set. This type of analysis could help
inform planning and future development.
db.users.aggregate(
[
{ $unwind
{ $group
{ $sort1
{ $limit
]
)
The pipeline begins with all documents in theuserscollection, and passes these documents through the following
operations:
$unwindoperator separates each value in thelikesarray, and creates a new version of the source
document for every element in the array.
Example
Given the following document from theuserscollection:
{
_id,
joined"2011-03-02"),
likes"golf",]
}
The$unwindoperator would create the following documents:
{
_id,
joined"2011-03-02"),
likes
}
{
_id,
joined"2011-03-02"),
likes
}
$groupoperator collects all documents the same value for thelikeseld and counts each grouping.
With this information,$groupcreates a new document with two elds:
_id, which contains thelikesvalue.
number, which is a generated eld. The$sumoperator increments this eld by 1 for every document
containing the givenlikesvalue.
$sortoperator sorts these documents by thenumbereld in reverse order.
$limitoperator only includes the rst 5 result documents.
The results of aggregation would resemble the following:
410 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
{
"_id",
"number"
},
{
"_id",
"number"
},
{
"_id",
"number"
},
{
"_id",
"number"
},
{
"_id",
"number"
}
7.3.3
In themongoshell, thedb.collection.mapReduce() method is a wrapper around themapReducecommand.
The following examples use thedb.collection.mapReduce() method:
Consider the following map-reduce operations on a collectionordersthat contains documents of the following
prototype:
{
_id:"50a8240b927d5d8b5891743c"),
cust_id:,
ord_date: newDate("Oct 04, 2012"),
status:,
price:,
items::, qty:, price:
{ sku:, qty:, price:
}
Return the Total Price Per Customer
Perform the map-reduce operation on theorderscollection to group by thecust_id, and calculate the sum of the
pricefor eachcust_id:
1.
thisrefers to the document that the map-reduce operation is processing.
priceto thecust_idfor each document and emits thecust_idandprice
pair.
varmapFunction1 function() {
emit(this.cust_id,this.price);
};
2. keyCustIdandvaluesPrices:
7.3. Aggregation Examples 411

MongoDB Documentation, Release 2.6.4
valuesPricesis an array whose elements are thepricevalues emitted by the map function and
grouped bykeyCustId.
valuesPricearray to the sum of its elements.
varreduceFunction1 function(keyCustId, valuesPrices) {
returnArray.sum(valuesPrices);
};
3. orderscollection using themapFunction1map function
and thereduceFunction1reduce function.
db.orders.mapReduce(
mapFunction1,
reduceFunction1,
{ out:
)
This operation outputs the results to a collection namedmap_reduce_example. If the
map_reduce_example collection already exists, the operation will replace the contents with the re-
sults 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 theorderscollection for all documents that have
anord_datevalue greater than01/01/2012. The operation groups by theitem.skueld, and calculates the
number of orders and the total quantity ordered for eachsku. The operation concludes by calculating the average
quantity per order for eachskuvalue:
1.
thisrefers to the document that the map-reduce operation is processing.
skuwith a new objectvaluethat contains thecountof1
and the itemqtyfor the order and emits theskuandvaluepair.
varmapFunction2 function() {
for(varidx; idx this.items.length; idx++) {
varkey this.items[idx].sku;
varvalue
count:,
qty: this.items[idx].qty
};
emit(key, value);
}
};
2. keySKUandcountObjVals:
countObjValsis an array whose elements are the objects mapped to the groupedkeySKUvalues
passed by map function to the reducer function.
countObjValsarray to a single objectreducedValuethat contains the
countand theqtyelds.
reducedVal, thecounteld contains the sum of thecountelds from the individual array ele-
ments, and theqtyeld contains the sum of theqtyelds from the individual array elements.
varreduceFunction2 function(keySKU, countObjVals) {
reducedVal:, qty:
412 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
for(varidx; idx++) {
reducedVal.count
reducedVal.qty
}
returnreducedVal;
};
3. keyandreducedVal. The function modies the
reducedValobject to add a computed eld namedavgand returns the modied object:
varfinalizeFunction2 function(key, reducedVal) {
reducedVal.avg/reducedVal.count;
returnreducedVal;
};
4. orderscollection using themapFunction2,
reduceFunction2, andfinalizeFunction2functions.
db.orders.mapReduce( mapFunction2,
reduceFunction2,
{
out::
query::
{ $gt: newDate(01/01/2012) }
},
finalize:
}
)
This operation uses thequeryeld to select only those documents withord_dategreater thannew
Date(01/01/2012). Then it output the results to a collectionmap_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.
7.3.4
Map-reduce operations can handle complex aggregation tasks. To perform map-reduce operations, MongoDB provides
themapReducecommand and, in themongoshell, thedb.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:
1.
2.
queryparameter that species conditions that matchonlythe new documents.
outparameter that species thereduceaction to merge the new results into the existing output
collection.
Consider the following example where you schedule a map-reduce operation on asessionscollection to run at the
end of each day.
7.3. Aggregation Examples 413

MongoDB Documentation, Release 2.6.4
Data Setup
Thesessionscollection contains documents that log users' sessions each day, for example:
db.sessions.save( { userid:, ts:2011-11-03 14:17:00), length:
db.sessions.save( { userid:, ts:2011-11-03 14:23:00), length:
db.sessions.save( { userid:, ts:2011-11-03 15:02:00), length:
db.sessions.save( { userid:, ts:2011-11-03 16:45:00), length:
db.sessions.save( { userid:, ts:2011-11-04 11:05:00), length:
db.sessions.save( { userid:, ts:2011-11-04 13:14:00), length:
db.sessions.save( { userid:, ts:2011-11-04 17:00:00), length:
db.sessions.save( { userid:, ts:2011-11-04 15:37:00), length:
Initial Map-Reduce of Current Collection
Run the rst map-reduce operation as follows:
1. useridto an object that contains the eldsuserid,total_time,
count, andavg_time:
varmapFunction function() {
varkey this.userid;
varvalue
userid: this.userid,
total_time: this.length,
count:,
avg_time:
};
emit( key, value );
};
2. keyandvaluesto calculate the total time and
the count. Thekeycorresponds to theuserid, and thevaluesis an array whose elements corresponds to
the individual objects mapped to theuseridin themapFunction.
varreduceFunction function(key, values) {
varreducedObject
userid:
total_time:,
count:0,
avg_time:0
};
values.forEach( function(value) {
reducedObject.total_time
reducedObject.count
}
);
returnreducedObject;
};
3. keyandreducedValue. The function modies the
reducedValuedocument to add another eldaverageand returns the modied document.
414 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
varfinalizeFunction function(key, reducedValue) {
if(reducedValue.count)
reducedValue.avg_time
returnreducedValue;
};
4. sessioncollection using themapFunction, thereduceFunction, and the
finalizeFunctionfunctions. Output the results to a collectionsession_stat. If thesession_stat
collection already exists, the operation will replace the contents:
db.sessions.mapReduce( mapFunction,
reduceFunction,
{
out:,
finalize:
}
)
Subsequent Incremental Map-Reduce
Later, as thesessionscollection grows, you can run additional map-reduce operations. For example, add new
documents to thesessionscollection:
db.sessions.save( { userid:, ts:2011-11-05 14:17:00), length:
db.sessions.save( { userid:, ts:2011-11-05 14:23:00), length:
db.sessions.save( { userid:, ts:2011-11-05 15:02:00), length:
db.sessions.save( { userid:, ts:2011-11-05 16:45:00), length:
At the end of the day, perform incremental map-reduce on thesessionscollection, but use thequeryeld to select
only the new documents. Output the results to the collectionsession_stat, butreducethe contents with the
results of the incremental map-reduce:
db.sessions.mapReduce( mapFunction,
reduceFunction,
{
query:::2011-11-05 00:00:00) } },
out::
finalize:
}
);
7.3.5
Themapfunction is a JavaScript function that associates or maps a value with a key and emits the key and value
pair during amap-reduce(page 394) operation.
To verify thekeyandvaluepairs emitted by themapfunction, write your ownemitfunction.
Consider a collectionordersthat contains documents of the following prototype:
{
_id:"50a8240b927d5d8b5891743c"),
cust_id:,
ord_date: newDate("Oct 04, 2012"),
7.3. Aggregation Examples 415

MongoDB Documentation, Release 2.6.4
status:,
price:,
items::, qty:, price:
{ sku:, qty:, price:
}
1. mapfunction that maps thepriceto thecust_idfor each document and emits thecust_idand
pricepair:
varmap function() {
emit(this.cust_id,this.price);
};
2. emitfunction to print the key and value:
varemit function(key, value) {
print("emit");
print("key: "
}
3. mapfunction with a single document from theorderscollection:
varmyDoc:"50a8240b927d5d8b5891743c") } );
map.apply(myDoc);
4.
emit
key::250
5. mapfunction with multiple documents from theorderscollection:
varmyCursor:
while(myCursor.hasNext()) {
vardoc
print ("document _id= "
map.apply(doc);
print();
}
6.
See also:
Themapfunction must meet various requirements. For a list of all the requirements for themapfunction, see
mapReduce, or themongoshell helper methoddb.collection.mapReduce() .
7.3.6
Thereducefunction is a JavaScript function that reduces to a single object all the values associated with a par-
ticular key during amap-reduce(page 394) operation. Thereducefunction must meet various requirements. This
tutorial helps verify that thereducefunction meets the following criteria:
reducefunction must return an object whosetypemust beidenticalto the type of thevalueemitted by
themapfunction.
valuesArrayshould not affect the output of thereducefunction.
reducefunction must beidempotent.
416 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
For a list of all the requirements for thereducefunction, seemapReduce, or themongoshell helper method
db.collection.mapReduce() .
Conrm Output Type
You can test that thereducefunction returns a value that is the same type as the value emitted from themapfunction.
1. reduceFunction1 function that takes the argumentskeyCustIdandvaluesPrices.
valuesPricesis an array of integers:
varreduceFunction1 function(keyCustId, valuesPrices) {
returnArray.sum(valuesPrices);
};
2.
varmyTestValues,,
3. reduceFunction1withmyTestValues:
reduceFunction1(myKey, myTestValues);
4. reduceFunction1returned an integer:
20
5. reduceFunction2function that takes the argumentskeySKUandvaluesCountObjects.
valuesCountObjects is an array of documents that contain two eldscountandqty:
varreduceFunction2 function(keySKU, valuesCountObjects) {
reducedValue:, qty:
for(varidx; idx++) {
reducedValue.count
reducedValue.qty
}
returnreducedValue;
};
6.
varmyTestObjects
{ count:, qty:
{ count:, qty:
{ count:, qty:
];
7. reduceFunction2withmyTestObjects:
reduceFunction2(myKey, myTestObjects);
8. reduceFunction2returned a document with exactly thecountand theqtyeld:
{,
7.3. Aggregation Examples 417

MongoDB Documentation, Release 2.6.4
Ensure Insensitivity to the Order of Mapped Values
Thereducefunction takes akeyand avaluesarray as its argument. You can test that the result of thereduce
function does not depend on the order of the elements in thevaluesarray.
1. values1array and a samplevalues2array that only differ in the order of the array elements:
varvalues1
{ count:, qty:
{ count:, qty:
{ count:, qty:
];
varvalues2
{ count:, qty:
{ count:, qty:
{ count:, qty:
];
2. reduceFunction2function that takes the argumentskeySKUandvaluesCountObjects.
valuesCountObjects is an array of documents that contain two eldscountandqty:
varreduceFunction2 function(keySKU, valuesCountObjects) {
reducedValue:, qty:
for(varidx; idx++) {
reducedValue.count
reducedValue.qty
}
returnreducedValue;
};
3. reduceFunction2rst withvalues1and then withvalues2:
reduceFunction2(myKey, values1);
reduceFunction2(myKey, values2);
4. reduceFunction2returned the same result:
{,
Ensure Reduce Function Idempotence
Because the map-reduce operation may call areducemultiple times for the same key, and won't call areducefor
single instances of a key in the working set, thereducefunction must return a value of the same type as the value
emitted from themapfunction. You can test that thereducefunction process reduced values without affecting the
nalvalue.
1. reduceFunction2function that takes the argumentskeySKUandvaluesCountObjects.
valuesCountObjects is an array of documents that contain two eldscountandqty:
varreduceFunction2 function(keySKU, valuesCountObjects) {
reducedValue:, qty:
for(varidx; idx++) {
reducedValue.count
reducedValue.qty
}
418 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
returnreducedValue;
};
2.
varmyKey;
3. valuesIdempotentarray that contains an element that is a call to thereduceFunction2
function:
varvaluesIdempotent
{ count:, qty:
{ count:, qty:
reduceFunction2(myKey, [ { count:3, qty:
];
4. values1array that combines the values passed toreduceFunction2:
varvalues1
{ count:, qty:
{ count:, qty:
{ count:, qty:
];
5. reduceFunction2rst withmyKeyandvaluesIdempotentand then withmyKeyand
values1:
reduceFunction2(myKey, valuesIdempotent);
reduceFunction2(myKey, values1);
6. reduceFunction2returned the same result:
{,
7.4
Aggregation Pipeline Quick Reference(page 420)Quick reference card for aggregation pipeline.
http://docs.mongodb.org/manualreference/operator/aggregation Aggregation pipeline op-
erations have a collection of operators available to dene and manipulate documents in pipeline stages.
Aggregation Commands Comparison(page 424)A comparison ofgroup,mapReduceandaggregatethat ex-
plores the strengths and limitations of each aggregation modality.
SQL to Aggregation Mapping Chart(page 426)An overview common aggregation operations in SQL and Mon-
goDB using the aggregation pipeline and operators in MongoDB and common SQL statements.
Aggregation Interfaces(page 428)The data aggregation interfaces document the invocation format and output for
MongoDB's aggregation commands and methods.
Variables in Aggregation Expressions(page 428)Use of variables in aggregation pipeline expressions.
7.4. Aggregation Reference 419

MongoDB Documentation, Release 2.6.4
7.4.1
Stages
Pipeline stages appear in an array. Documents pass through the stages in sequence. All except the$outand
$geoNearstages can appear multiple times in a pipeline.
db.collection.aggregate( [ {stage>
Name Description
$geoNearReturns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the
functionality of$match,$sort, and$limitfor geospatial data. The output documents include an
additional distance eld and can include a location identier eld.
$groupGroups input documents by a specied identier expression and applies the accumulator expression(s),
if specied, to each group. Consumes all input documents and outputs one document per each distinct
group. The output documents only contain the identier eld and, if specied, accumulated elds.
$limitPasses the rstndocuments unmodied to the pipeline wherenis the specied limit. For each input
document, outputs either one document (for the rstndocuments) or zero documents (after the rstn
documents).
$matchFilters the document stream to allow only matching documents to pass unmodied into the next
pipeline stage.$matchuses standard MongoDB queries. For each input document, outputs either one
document (a match) or zero documents (no match).
$out Writes the resulting documents of the aggregation pipeline to a collection. To use the$outstage, it
must be the last stage in the pipeline.
$projectReshapes each document in the stream, such as by adding new elds or removing existing elds. For
each input document, outputs one document.
$redactReshapes each document in the stream by restricting the content for each document based on
information stored in the documents themselves. Incorporates the functionality of$projectand
$match. Can be used to implement eld level redaction. For each input document, outputs either one
or zero document.
$skipSkips the rstndocuments wherenis the specied skip number and passes the remaining documents
unmodied to the pipeline. For each input document, outputs either zero documents (for the rstn
documents) or one document (if after the rstndocuments).
$sortReorders the document stream by a specied sort key. Only the order changes; the documents remain
unmodied. For each input document, outputs one document.
$unwindDeconstructs an array eld from the input documents to output a document foreachelement. Each
output document replaces the array with an element value. For each input document, outputsn
documents wherenis the number of array elements and can be zero for an empty array.
Expressions
Expressions can includeeld paths and system variables(page 420),literals(page 421),expression objects(page 421),
andexpression operators(page 421). Expressions can be nested.
Field Path and System Variables
Aggregation expressions useeld pathto access elds in the input documents. To specify a eld path, use a string that
prexes with a dollar sign$the eld name or the dotted eld name, if the eld is in embedded document. For example,
"$user"to specify the eld path for theusereld or"$user.name"to specify the eld path to"user.name"
eld.
"$<field>"is equivalent to"$$CURRENT.<field>" where theCURRENT(page 429) is a system variable that
defaults to the root of the current object in the most stages, unless stated otherwise in specic stages.CURRENT
420 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
(page 429) can be rebound.
Along with theCURRENT(page 429) system variable, othersystem variables(page 428) are also available for use in
expressions. To use user-dened variables, use$letand$mapexpressions. To access variables in expressions, use
a string that prexes 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 eld
and numeric/boolean literals inexpression objects(page 421) as projection ags. To avoid parsing literals, use the
$literalexpression.
Expression Objects
Expression objects have the following form:
{field1>:expression1>, ... }
If the expressions are numeric or boolean literals, MongoDB treats the literals as projection ags (e.g.1ortrueto
include the eld), valid only in the$projectstage. To avoid treating numeric or boolean literals as projection ags,
use the$literalexpression 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$literalexpression
or keep the outer array that designates the argument list.
Boolean ExpressionsBoolean expressions evaluates its argument expressions as booleans and return a boolean as
the result.
In addition to thefalseboolean value, Boolean expression evaluates asfalsethe following:null,0, and
undefinedvalues. The Boolean expression evaluates all other values astrue, including non-zero numeric values
and arrays.
Name Description
$and Returnstrueonly whenallits expressions evaluate totrue. Accepts any number of argument
expressions.
$not Returns the boolean value that is the opposite of its argument expression. Accepts a single argument
expression.
$or Returnstruewhenanyof its expressions evaluates totrue. Accepts any number of argument
expressions.
7.4. Aggregation Reference 421

MongoDB Documentation, Release 2.6.4
Set ExpressionsSet 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 lters out duplicates in the result to output an array that contains only
unique entries. The order of the elements in the output array is unspecied.
If a set contains a nested array element, the set expression doesnotdescend into the nested array but evaluates the
array at top-level.
Name Description
$allElementsTrueReturnstrueifnoelement of a set evaluates tofalse, otherwise, returnsfalse. Accepts a
single argument expression.
$anyElementTrueReturnstrueifanyelements of a set evaluate totrue; otherwise, returnsfalse. Accepts a
single argument expression.
$setDifferenceReturns a set with elements that appear in the rst set but not in the second set; i.e. performs a
relative complement
6
of the second set relative to the rst. Accepts exactly two argument
expressions.
$setEqualsReturnstrueif the input sets have the same distinct elements. Accepts two or more argument
expressions.
$setIntersectionReturns a set with elements that appear inallof the input sets. Accepts any number of argument
expressions.
$setIsSubsetReturnstrueif all elements of the rst set appear in the second set, including when the rst set
equals the second set; i.e. not a
7
. Accepts exactly two argument expressions.
$setUnion Returns a set with elements that appear inanyof the input sets. Accepts any number of argument
expressions.
Comparison ExpressionsComparison expressions return a boolean except for$cmpwhich returns a number.
The comparison expressions take two argument expressions and compare both value and type, using thespecied
BSON comparison order(page 168) for values of different types.
NameDescription
$cmpReturns:0if the two values are equivalent,1if the rst value is greater than the second, and-1if the
rst value is less than the second.
$eq Returnstrueif the values are equivalent.
$gt Returnstrueif the rst value is greater than the second.
$gteReturnstrueif the rst value is greater than or equal to the second.
$lt Returnstrueif the rst value is less than the second.
$lteReturnstrueif the rst value is less than or equal to the second.
$ne Returnstrueif the values arenotequivalent.
Arithmetic ExpressionsArithmetic expressions perform mathematic operations on numbers. Some arithmetic ex-
pressions can also support date arithmetic.
4
http://en.wikipedia.org/wiki/Complement_(set_theory)
5
http://en.wikipedia.org/wiki/Subset
6
http://en.wikipedia.org/wiki/Complement_(set_theory)
7
http://en.wikipedia.org/wiki/Subset
422 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
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.
$divideReturns the result of dividing the rst number by the second. Accepts two argument expressions.
$mod Returns the remainder of the rst number divided by the second. Accepts two argument expressions.
$multiplyMultiplies numbers to return the product. Accepts any number of argument expressions.
$subtractReturns the result of subtracting the second value from the rst. 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 rst as it is not meaningful to subtract a
date from a number.
String ExpressionsString expressions, with the exception of$concat, only have a well-dened behavior for
strings of ASCII characters.
$concatbehavior is well-dened regardless of the characters used.
Name Description
$concatConcatenates any number of strings.
$strcasecmpPerforms case-insensitive string comparison and returns:0if two strings are equivalent,1if the rst
string is greater than the second, and-1if the rst string is less than the second.
$substrReturns a substring of a string, starting at a specied index position up to a specied length. Accepts
three expressions as arguments: the rst argument must resolve to a string, and the second and third
arguments must resolve to integers.
$toLowerConverts a string to lowercase. Accepts a single argument expression.
$toUpperConverts a string to uppercase. Accepts a single argument expression.
Text Search Expressions
Name Description
$metaAccess text search metadata.
Array Expressions
Name Description
$sizeReturns the number of elements in the array. Accepts a single expression as argument.
Variable Expressions
NameDescription
$letDenes variables for use within the scope of a subexpression and returns the result of the subexpression.
Accepts named parameters.
$mapApplies a subexpression to each element of an array and returns the array of resulting values in order.
Accepts named parameters.
Literal Expressions
Name Description
$literalReturn a value without parsing. Use for values that the aggregation pipeline may interpret as an
expression. For example, use a$literalexpression to a string that starts with a$to avoid parsing as
a eld path.
7.4. Aggregation Reference 423

MongoDB Documentation, Release 2.6.4
Date Expressions
Name Description
$dayOfMonthReturns the day of the month for a date as a number between 1 and 31.
$dayOfWeekReturns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday).
$dayOfYearReturns the day of the year for a date as a number between 1 and 366 (leap year).
$hour Returns the hour for a date as a number between 0 and 23.
$millisecondReturns the milliseconds of a date as a number between 0 and 999.
$minute Returns the minute for a date as a number between 0 and 59.
$month Returns the month for a date as a number between 1 (January) and 12 (December).
$second Returns the seconds for a date as a number between 0 and 60 (leap seconds).
$week Returns the week number for a date as a number between 0 (the partial week that precedes the rst
Sunday of the year) and 53 (leap year).
$year Returns the year for a date as a number (e.g. 2014).
Conditional Expressions
NameDescription
$condA 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.
$ifNullReturns either the non-null result of the rst expression or the result of the second expression if the rst
expression results in a null result. Null result encompasses instances of undened values or missing
elds. Accepts two expressions as arguments. The result of the second expression can be null.
Accumulators
Accumulators, available only for the$groupstage, 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
$addToSetReturns an array ofuniqueexpression values for each group. Order of the array elements is
undened.
$avg Returns an average for each group. Ignores non-numeric values.
$first Returns a value from the rst document for each group. Order is only dened if the documents are
in a dened order.
$last Returns a value from the last document for each group. Order is only dened if the documents are
in a dened 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.
$sum Returns a sum for each group. Ignores non-numeric values.
7.4.2
The following table provides a brief overview of the features of the MongoDB aggregation commands.
424 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
aggregate mapReduce group
De-
scrip-
tion
New in version 2.2.
Designed with specic 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
http://docs.mongodb.org/manualreference/operator/aggregation
for more information on the
pipeline operators.
Implements the Map-Reduce
aggregation for processing large
data sets.
Provides grouping functionality.
Is slower than theaggregate
command and has less
functionality than the
mapReducecommand.
Key
Fea-
tures
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 lter out
documents.
In addition to grouping
operations, can perform complex
aggregation tasks as well as
perform incremental aggregation
on continuously growing
datasets.
SeeMap-Reduce Examples
(page 411) andPerform
Incremental Map-Reduce
(page 413).
Can either group by existing
elds or with a customkeyf
JavaScript function, can group by
calculated elds.
Seegroupfor information and
example using thekeyf
function.
Flex-
i-
bil-
ity
Limited to the operators and
expressions supported by the
aggregation pipeline.
However, can add computed
elds, create new virtual
sub-objects, and extract
sub-elds into the top-level of
results by using the$project
pipeline operator.
See$projectfor more
information as well as
http://docs.mongodb.org/manualreference/operator/aggregation
for more information on all the
available pipeline operators.
Custommap,reduceand
finalizeJavaScript functions
offer exibility to aggregation
logic.
SeemapReducefor details and
restrictions on the functions.
Customreduceand
finalizeJavaScript functions
offer exibility to grouping logic.
Seegroupfor details and
restrictions on these functions.
Out-
put
Re-
sults
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 theBSON
Document sizelimit 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
mapReducefor 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 t 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.
Shard-
ing
Supports non-sharded and
sharded input collections.
Supports non-sharded and
sharded input collections.
Doesnotsupport 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
In-
for-
ma-
tion
SeeAggregation Pipeline
(page 391) andaggregate.
SeeMap-Reduce(page 394) and
mapReduce.
Seegroup.
7.4. Aggregation Reference 425

MongoDB Documentation, Release 2.6.4
7.4.3
Theaggregation pipeline(page 391) 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 corre-
sponding MongoDBaggregation 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$unwindoperator allows for
somewhat similar functionality, but with elds embedded within the document.
Examples
The following table presents a quick reference of SQL aggregation statements and the corresponding MongoDB state-
ments. The examples in the table assume the following conditions:
twotables,ordersandorder_lineitem that join by the
order_lineitem.order_id and theorders.idcolumns.
onecollectionordersthat contain documents of the following prototype:
{
cust_id:,
ord_date:"2012-11-02T17:04:11.102Z"),
status:,
price:,
items::, qty:, price:
{ sku:, qty:, price:
}
426 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
SQL Example MongoDB Example Description
SELECT (*)AS
FROMorders
db.orders.aggregate( [
{
$group:
_id: null,
count::
}
}
] )
Count all records fromorders
SELECT (price)AStotal
FROMorders
db.orders.aggregate( [
{
$group:
_id: null,
total::
}
}
] )
Sum thepriceeld fromorders
SELECTcust_id,
SUM(price)AStotal
FROMorders
GROUP cust_id
db.orders.aggregate( [
{
$group:
_id:,
total::
}
}
] )
For each uniquecust_id, sum the
priceeld.
SELECTcust_id,
SUM(price)AStotal
FROMorders
GROUP cust_id
ORDER total
db.orders.aggregate( [
{
$group:
_id:,
total::
}
},
{ $sort::
] )
For each uniquecust_id, sum the
priceeld, results sorted by sum.
SELECTcust_id,
ord_date,
SUM(price)AStotal
FROMorders
GROUP cust_id,
ord_date
db.orders.aggregate( [
{
$group:
_id:
cust_id:,
ord_date:
month::
day::
year::}
}
},
total::
}
}
] )
For each unique cust_id,
ord_dategrouping, sum the
priceeld. Excludes the time
portion of the date.
SELECTcust_id,
count(*)
FROMorders
GROUP cust_id
HAVING (*)
db.orders.aggregate( [
{
$group:
_id:,
count::
}
},
{ $match:::
] )
Forcust_idwith multiple records,
return thecust_idand the corre-
sponding record count.
SELECTcust_id,
ord_date,
SUM(price)AStotal
FROMorders
GROUP cust_id,
ord_date
HAVINGtotal
db.orders.aggregate( [
{
$group:
_id:
cust_id:,
ord_date:
month::
day::
year::}
}
},
total::
}
},
{ $match:::
] )
For each unique cust_id,
ord_dategrouping, sum the
priceeld and return only where
the sum is greater than 250. Excludes
the time portion of the date.
SELECTcust_id,
SUM(price)astotal
FROMorders
WHEREstatus
GROUP cust_id
db.orders.aggregate( [
{ $match::
{
$group:
_id:,
total::
}
}
] )
For each uniquecust_idwith sta-
tusA, sum thepriceeld.
SELECTcust_id,
SUM(price)astotal
FROMorders
WHEREstatus
GROUP cust_id
HAVINGtotal
db.orders.aggregate( [
{ $match::
{
$group:
_id:,
total::
}
},
{ $match:::
] )
For each uniquecust_idwith sta-
tusA, sum thepriceeld and return
only where the sum is greater than
250.
SELECTcust_id,
SUM(li.qty)asqty
FROMorders o,
order_lineitem li
WHEREli.order_id
GROUP cust_id
db.orders.aggregate( [
{ $unwind:
{
$group:
_id:,
qty::
}
}
] )
For each uniquecust_id, sum the
corresponding line itemqtyelds
associated with the orders.
SELECT (*)
FROM(SELECTcust_id,
ord_date
FROMorders
GROUP cust_id,
ord_date)
asDerivedTable
db.orders.aggregate( [
{
$group:
_id:
cust_id:,
ord_date:
month::
day::
year::}
}
}
}
},
{
$group:
_id: null,
count::
}
}
] )
Count the number of distinct
cust_id,ord_dategroupings.
Excludes the time portion of the date.
7.4. Aggregation Reference 427

MongoDB Documentation, Release 2.6.4
7.4.4
Aggregation Commands
Name Description
aggregate Performsaggregation tasks(page 391) such as group using the aggregation framework.
count Counts the number of documents in a collection.
distinct Displays the distinct values found for a specied key in a collection.
group Groups documents in a collection by the specied key and performs simple aggregation.
mapReduce Performsmap-reduce(page 394) aggregation for large data sets.
Aggregation Methods
Name Description
db.collection.aggregate() Provides access to theaggregation pipeline(page 391).
db.collection.group() Groups documents in a collection by the specied key and performs simple
aggregation.
db.collection.mapReduce() Performsmap-reduce(page 394) aggregation for large data sets.
7.4.5
Aggregation expressions(page 420) can use both user-dened and system variables.
Variables can hold anyBSON type data(page 167). To access the value of the variable, use a string with the variable
name prexed with double dollar signs ($$).
If the variable references an object, to access a specic eld 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:
428 Chapter 7. Aggregation

MongoDB Documentation, Release 2.6.4
Variable Description
ROOT
References the root document, i.e. the top-level doc-
ument, currently being processed in the aggregation
pipeline stage.
CURRENT
References the start of the eld path being processed in
the aggregation pipeline stage. Unless documented oth-
erwise, all stages start withCURRENT(page 429) the
same asROOT(page 429).
CURRENT(page 429) is modiable. However, since
$<field>is equivalent to$$CURRENT.<field>,
rebindingCURRENT(page 429) changes the meaning
of$accesses.
DESCEND
One of the allowed results of a$redactexpression.
PRUNE
One of the allowed results of a$redactexpression.
KEEP
One of the allowed results of a$redactexpression.
See also:
$let,$redact
7.4. Aggregation Reference 429

MongoDB Documentation, Release 2.6.4
430 Chapter 7. Aggregation

CHAPTER8
Indexes
Indexes provide high performance read operations for frequently used queries.
This section introduces indexes in MongoDB, describes the types and conguration 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(page 431)An introduction to indexes in MongoDB.
Index Concepts(page 436)The core documentation of indexes in MongoDB, including geospatial and text indexes.
Index Types(page 437)MongoDB provides different types of indexes for different purposes and different types
of content.
Index Properties(page 456)The properties you can specify when building indexes.
Index Creation(page 460)The options available when creating indexes.
Index Intersection(page 462)The use of index intersection to fulll a query.
Indexing Tutorials(page 464)Examples of operations involving indexes, including index creation and querying in-
dexes.
Indexing Reference(page 500)Reference material for indexes in MongoDB.
8.1
Indexes support the efcient execution of queries in MongoDB. Without indexes, MongoDB must scan every document
in a collection to select those documents that match the query statement. Thesecollection scansare inefcient because
they requiremongodto 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 specic eld or set of elds, ordered by the value of the eld.
Fundamentally, indexes in MongoDB are similar to indexes in other database systems. MongoDB denes indexes at
thecollectionlevel and supports indexes on any eld or sub-eld 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.
431

MongoDB Documentation, Release 2.6.4
Figure 8.1: Diagram of a query selecting documents using an index. MongoDB narrows the query by scanning the
range of documents with values ofscoreless than30.
8.1.1
Consider the documentation of thequery optimizer(page 61) 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 specic 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.
Covered Results
When the query criteria and theprojectionof a query includeonlythe indexed elds, MongoDB will return results
directly from the indexwithoutscanning any documents or bringing documents into memory. These covered queries
can beveryefcient.
8.1.2
MongoDB provides a number of different index types to support specic types of data and queries.
432 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Figure 8.2: Diagram of a query that uses an index to select and return sorted results. The index storesscorevalues
in ascending order. MongoDB can traverse the index in either ascending or descending order to return sorted results.
Figure 8.3: Diagram of a query that uses only the index to match the query criteria and return the results. MongoDB
does not need to inspect data outside of the index to fulll the query.
8.1. Index Introduction 433

MongoDB Documentation, Release 2.6.4
Default_id
All MongoDB collections have an index on the_ideld that exists by default. If applications do not specify a value
for_idthe driver or themongodwill create an_ideld with anObjectIdvalue.
The_idindex isunique, and prevents clients from inserting two documents with the same value for the_ideld.
Single Field
In addition to the MongoDB-dened_idindex, MongoDB supports user-dened indexes on asingle eld of a docu-
ment(page 438). Consider the following illustration of a single-eld index:
Figure 8.4: Diagram of an index on thescoreeld (ascending).
Compound Index
MongoDBalsosupports user-dened indexes on multiple elds. Thesecompound indexes(page 440) behave like
single-eld indexes;however, the query can select documents based on additional elds. The order of elds listed
in a compound index has signicance. For instance, if a compound index consists of{ userid: 1, score:
-1 }, the index sorts rst byuseridand then, within eachuseridvalue, sort byscore. Consider the following
illustration of this compound index:
Multikey Index
MongoDB usesmultikey indexes(page 442) to index the content stored in arrays. If you index a eld that holds an
array value, MongoDB creates separate index entries foreveryelement of the array. Thesemultikey indexes(page 442)
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 eld 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 efcient queries of geospatial coordinate data, MongoDB provides two special indexes:2d indexes
(page 451) that uses planar geometry when returning results and2sphere indexes(page 447) that use spherical ge-
ometry to return results.
434 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Figure 8.5: Diagram of a compound index on theuserideld (ascending) and thescoreeld (descending). The
index sorts rst by theuserideld and then by thescoreeld.
Figure 8.6: Diagram of a multikey index on theaddr.zipeld. Theaddreld contains an array of address
documents. The address documents contain thezipeld.
8.1. Index Introduction 435

MongoDB Documentation, Release 2.6.4
See2d Index Internals(page 452) for a high level introduction to geospatial indexes.
Text Indexes
MongoDB provides atextindex type that supports searching for string content in a collection. These text indexes
do not store language-specicstopwords (e.g. the, a, or) andstemthe words in a collection to only store root
words.
SeeText Indexes(page 454) for more information on text indexes and search.
Hashed Indexes
To supporthash based sharding(page 621), MongoDB provides ahashed index(page 455) type, which indexes the
hash of the value of a eld. These indexes have a more random distribution of values along their range, butonly
support equality matches and cannot support range-based queries.
8.1.3
Unique Indexes
Theunique(page 457) property for an index causes MongoDB to reject duplicate values for the indexed eld. To
create aunique index(page 457) on a eld that already has duplicate values, seeDrop Duplicates(page 461) for
index creation options. Other than the unique constraint, unique indexes are functionally interchangeable with other
MongoDB indexes.
Sparse Indexes
Thesparse(page 457) property of an index ensures that the index only contain entries for documents that have the
indexed eld. The index skips documents thatdo nothave the indexed eld.
You can combine the sparse index option with the unique index option to reject documents that have duplicate values
for a eld but ignore documents that do not have the indexed key.
8.1.4
New in version 2.6.
MongoDB can use theintersection of indexes(page 462) to fulll queries. For queries that specify compound query
conditions, if one index can fulll a part of a query condition, and another index can fulll another part of the query
condition, then MongoDB can use the intersection of the two indexes to fulll the query. Whether the use of a
compound index or the use of an index intersection is more efcient depends on the particular query and the system.
For details on index intersection, seeIndex Intersection(page 462).
8.2
These documents describe and provide examples of the types, conguration options, and behavior of indexes in Mon-
goDB. For an over view of indexing, seeIndex Introduction(page 431). For operational instructions, seeIndexing
Tutorials(page 464). TheIndexing Reference(page 500) documents the commands and operations specic to index
construction, maintenance, and querying in MongoDB, including index types and creation options.
436 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Index Types(page 437)MongoDB provides different types of indexes for different purposes and different types of
content.
Single Field Indexes(page 438)A single eld index only includes data from a single eld of the documents in
a collection. MongoDB supports single eld indexes on elds at the top level of a documentandon elds
in sub-documents.
Compound Indexes(page 440)A compound index includes more than one eld of the documents in a collec-
tion.
Multikey Indexes(page 442)A multikey index references an array and records a match if a query includes any
value in the array.
Geospatial Indexes and Queries(page 444)Geospatial indexes support location-based searches on data that is
stored as either GeoJSON objects or legacy coordinate pairs.
Text Indexes(page 454)Text indexes supports search of string content in documents.
Hashed Index(page 455)Hashed indexes maintain entries with hashes of the values of the indexed eld.
Index Properties(page 456)The properties you can specify when building indexes.
TTL Indexes(page 456)The TTL index is used for TTL collections, which expire data after a period of time.
Unique Indexes(page 457)A unique index causes MongoDB to reject all documents that contain a duplicate
value for the indexed eld.
Sparse Indexes(page 457)A sparse index does not index documents that do not have the indexed eld.
Index Creation(page 460)The options available when creating indexes.
Index Intersection(page 462)The use of index intersection to fulll a query.
8.2.1
MongoDB provides a number of different index types. You can create indexes on any eld or embedded eld within
a document or sub-document. You can createsingle eld indexes(page 438) orcompound indexes(page 440). Mon-
goDB also supports indexes of arrays, calledmulti-key indexes(page 442), as well asindexes on geospatial data
(page 444). For a list of the supported index types, seeIndex Type Documentation(page 438).
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 themongoshell, you can create an index by calling theensureIndex()method. For more detailed instructions
about building indexes, see theIndexing Tutorials(page 464) page.
Behavior of Indexes
All indexes in MongoDB areB-treeindexes, which can efciently support equality matches and range queries. The
index stores items internally in order sorted by the value of the index eld. The ordering of index entries supports
efcient 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
also traverse the index in either directions. As a result, for single-eld indexes, ascending and descending indexes are
8.2. Index Concepts 437

MongoDB Documentation, Release 2.6.4
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.
SeeSort Order(page 441) for more information on the impact of index order on results in compound indexes.
Index Intersection
MongoDB can use the intersection of indexes to fulll queries with compound conditions. SeeIndex Intersection
(page 462) 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 Limitationsfor details.
Index Type Documentation
Single Field Indexes(page 438)A single eld index only includes data from a single eld of the documents in a
collection. MongoDB supports single eld indexes on elds at the top level of a documentandon elds in
sub-documents.
Compound Indexes(page 440)A compound index includes more than one eld of the documents in a collection.
Multikey Indexes(page 442)A multikey index references an array and records a match if a query includes any value
in the array.
Geospatial Indexes and Queries(page 444)Geospatial indexes support location-based searches on data that is stored
as either GeoJSON objects or legacy coordinate pairs.
Text Indexes(page 454)Text indexes supports search of string content in documents.
Hashed Index(page 455)Hashed indexes maintain entries with hashes of the values of the indexed eld.
Single Field Indexes
MongoDB provides complete support for indexes on any eld in acollectionofdocuments. By default, all collections
have an index on the_id eld(page 439), and applications and users may add additional indexes to support important
queries and operations.
MongoDB supports indexes that contain either a single eldormultiple elds depending on the operations that this
index-type supports. This document describes indexes that contain a single eld. Consider the following illustration
of a single eld index.
See also:
Compound Indexes(page 440) for information about indexes that include multiple elds, andIndex Introduction
(page 431) for a higher level introduction to indexing in MongoDB.
ExampleGiven the following document in thefriendscollection:
{
"name"
"age"
}
438 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Figure 8.7: Diagram of an index on thescoreeld (ascending).
The following command creates an index on thenameeld:
db.friends.ensureIndex(
Cases
_idField IndexMongoDB creates the_idindex, which is an ascendingunique index(page 457) on the_ideld,
for all collections when the collection is created. You cannot remove the index on the_ideld.
Think of the_ideld as theprimary keyfor a collection. Every documentmusthave a unique_ideld. You may
store any unique value in the_ideld. The default value of_idis anObjectIdwhich is generated when the client
inserts the document. AnObjectIdis a 12-byte unique identier suitable for use as the value of an_ideld.
Note:Insharded clusters, if you donotuse the_ideld as theshard key, then your applicationmustensure the
uniqueness of the values in the_ideld to prevent errors. This is most-often done by using a standard auto-generated
ObjectId.
Before version 2.2,capped collectionsdid not have an_ideld. In version 2.2 and newer, capped collections do
have an_ideld, except those in thelocaldatabase. SeeCapped Collections Recommendations and Restrictions
(page 196) for more information.
Indexes on Embedded FieldsYou can create indexes on elds embedded in sub-documents, just as you can index
top-level elds in documents. Indexes on embedded elds differ fromindexes on sub-documents(page 440), which
include the full content up to the maximumindex sizeof the sub-document in the index. Instead, indexes on
embedded elds allow you to use a dot notation, to introspect into sub-documents.
Consider a collection namedpeoplethat holds documents that resemble the following example document:
{"_id":
"name":
"address":
"street":,
"zipcode":,
"state":
}
}
8.2. Index Concepts 439

MongoDB Documentation, Release 2.6.4
You can create an index on theaddress.zipcodeeld, using the following specication:
db.people.ensureIndex( {:
Indexes on SubdocumentsYou can also create indexes on subdocuments.
For example, thefactoriescollection contains documents that contain ametroeld, such as:
{
_id:
metro:
city:,
state:
},
name:
}
Themetroeld is a subdocument, containing the embedded eldscityandstate. The following command
creates an index on themetroeld as a whole:
db.factories.ensureIndex( { metro:
The following query can use the index on themetroeld:
db.factories.find( { metro::, state:
This query returns the above document. When performing equality matches on subdocuments, eld order matters and
the subdocuments must match exactly. For example, the following query does not match the above document:
db.factories.find( { metro::, city:
Seequery-subdocumentsfor more information regarding querying on subdocuments.
Compound Indexes
MongoDB supportscompound indexes, where a single index structure holds references to multiple elds
2
within a
collection's documents. The following diagram illustrates an example of a compound index on two elds:
Compound indexes can support queries that match on multiple elds.
Example
Consider a collection namedproductsthat holds documents that resemble the following document:
{
"_id":
"item":,
"category":"food",,],
"location":,
"stock":,
"type":,
"arrival":(...)
}
If applications query on theitemeld as well as query on both theitemeld and thestockeld, you can specify
a single compound index to support both of these queries:
2
MongoDB imposes alimit of 31 fields for any compound index .
440 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Figure 8.8: Diagram of a compound index on theuserideld (ascending) and thescoreeld (descending). The
index sorts rst by theuserideld and then by thescoreeld.
db.products.ensureIndex( {:,:
Important:You may not create compound indexes that havehashedindex elds. You will receive an error if you
attempt to create a compound index that includesa hashed index(page 455).
The order of the elds in a compound index is very important. In the previous example, the index will contain
references to documents sorted rst by the values of theitemeld and, within each value of theitemeld, sorted
by values of thestockeld. SeeSort Order(page 441) for more information.
In addition to supporting queries that match on all the index elds, compound indexes can support queries that match
on the prex of the index elds. For details, seePrexes(page 442).
Sort OrderIndexes store references to elds in either ascending (1) or descending (-1) sort order. For single-eld
indexes, the sort order of keys doesn't matter because MongoDB can traverse the index in either direction. However,
forcompound indexes(page 440), sort order can matter in determining whether the index can support a sort operation.
Consider a collectioneventsthat contains documents with the eldsusernameanddate. Applications can issue
queries that return results sorted rst by ascendingusernamevalues and then by descending (i.e. more recent to last)
datevalues, such as:
db.events.find().sort( { username:, date:1
or queries that return results sorted rst by descendingusernamevalues and then by ascendingdatevalues, such
as:
db.events.find().sort( { username:1, date:
The following index can support both these sort operations:
db.events.ensureIndex( {,1
However, the above indexcannotsupport sorting by ascendingusernamevalues and then by ascendingdate
values, such as the following:
db.events.find().sort( { username:, date:
8.2. Index Concepts 441

MongoDB Documentation, Release 2.6.4
PrexesCompound indexes support queries on any prex of the index elds. Index prexes are the beginning
subset of indexed elds. For example, given the index{ a: 1, b: 1, c: 1 } , both{ a: 1 }and{
a: 1, b: 1 } are prexes of the index.
If you have a collection that has a compound index on{ a: 1, b: 1 } , as well as an index that consists of the
prex of that index, i.e.{ a: 1 }, assuming none of the index has a sparse or unique constraints, then you can
drop the{ a: 1 }index. MongoDB will be able to use the compound index in all of situations that it would have
used the{ a: 1 }index.
For example, given the following index:
{:,:,:
MongoDBcanuse this index to support queries that include:
itemeld,
itemeldandthelocationeld,
itemeldandthelocationeldandthestockeld, or
itemandstockelds; however, this index would be less efcient than an index on onlyitemand
stock.
MongoDBcannotuse this index to support queries that include:
locationeld,
stockeld, or
locationandstockelds.
Index IntersectionStarting in version 2.6, MongoDB can useindex intersection(page 462) to fulll queries. The
choice between creating compound indexes that support your queries or relying on index intersection depends on the
specics of your system. SeeIndex Intersection and Compound Indexes(page 463) for more details.
Multikey Indexes
To index a eld that holds an array value, MongoDB adds index items for each item in the array. Thesemultikeyindexes
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 eld 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 multi-
key 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)andnested documents.
Limitations
Interactions between Compound and Multikey IndexesWhile you can create multikeycompound indexes
(page 440), at most one eld 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,], b:}
{a:, b:1,]}
442 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Figure 8.9: Diagram of a multikey index on theaddr.zipeld. Theaddreld contains an array of address
documents. The address documents contain thezipeld.
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,], b:1,]}
If you attempt to insert such a document, MongoDB will reject the insertion, and produce an error that sayscannot
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 difcult
to maintain indexes.
Shard Keys
Important:The index of a shard keycannotbe a multi-key index.
Hashed Indexeshashedindexes are not compatible with multi-key indexes.
To compute the hash for ahashedindex, MongoDB collapses sub-documents and computes the hash for the entire
value. For elds that hold arrays or sub-documents, you cannot use the index to support queries that introspect the
sub-document.
Examples
Index Basic ArraysGiven the following document:
{
"_id""..."),
"name",
8.2. Index Concepts 443

MongoDB Documentation, Release 2.6.4
"author",
"tags",,,
}
Then an index on thetagseld,{ 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 DocumentsYou can create multikey indexes on elds in objects embedded in arrays,
as in the following example:
Consider afeedbackcollection with documents in the following form:
{
"_id":
"title":,
"comments":
{ author_id:
date:(...),
text:
{ author_id:
date:(...),
text:
{ author_id:
date:(...),
text:
]
}
An index on thecomments.texteld 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 thefeedbackcollection, consider the following query:
db.feedback.find( {:
The query would select the documents in the collection that contain the following embedded document in the
commentsarray:
{ author_id:
date:(...),
text:
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, seeGeospatial Index
Tutorials(page 476).
444 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
SurfacesBefore 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:
SphericalTo calculate geometry over an Earth-like sphere, store your location data on a spherical surface and use
2dsphere(page 447) index.
Store your location data as GeoJSON objects with this coordinate-axis order:longitude, latitude. The coordinate
reference system for GeoJSON uses theWGS84datum.
FlatTo calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a2d
(page 451) index.
Location DataIf you choose spherical surface calculations, you store location data as either:
GeoJSON ObjectsQueries onGeoJSONobjects always calculate on a sphere. The default coordinate reference
system for GeoJSON uses theWGS84datum.
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, Geome-
tryCollection.
MongoDB supports the following GeoJSON objects:

Legacy Coordinate PairsMongoDB supports spherical surface calculations onlegacy coordinate pairsusing a
2dsphereindex by converting the data to the GeoJSON Point type.
If you choose at surface calculations, and use a2dindex you can store data only aslegacy coordinate pairs.
Query OperationsMongoDB's geospatial query operators let you query for:
InclusionMongoDB can query for locations contained entirely within a specied polygon. Inclusion queries use
the$geoWithinoperator.
Both2dand2dsphereindexes can support inclusion queries. MongoDB does not require an index for inclusion
queries after 2.2.3; however, these indexes will improve query performance.
8.2. Index Concepts 445

MongoDB Documentation, Release 2.6.4
IntersectionMongoDB can query for locations that intersect with a specied geometry. These queries apply only
to data on a spherical surface. These queries use the$geoIntersectsoperator.
Only2dsphereindexes support intersection.
ProximityMongoDB can query for the points nearest to another point. Proximity queries use the$nearoperator.
The$nearoperator requires a2dor2dsphereindex.
Geospatial IndexesMongoDB provides the following geospatial index types to support the geospatial queries.
2dsphere2dsphere(page 447) indexes support:

2dsphere
index eld
New in version 2.4:2dsphereindexes are not available before version 2.4.
See also:
Query a 2dsphere Index(page 478)
2d2d(page 451) indexes support:

2dindex eld
See also:
Query a 2d Index(page 481)
Geospatial Indexes and ShardingYoucannotuse a geospatial index as theshard keyindex.
You can create and maintain a geospatial index on a sharded collection if using elds other than shard key.
For sharded collections, queries using$nearare not supported. You can instead use either thegeoNearcommand
or the$geoNearaggregation stage.
You also can query for geospatial data using$geoWithin.
Additional ResourcesThe following pages provide complete documentation for geospatial indexes and queries:
2dsphere Indexes(page 447)A2dsphereindex 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(page 451)The2dindex supports data stored as legacy coordinate pairs and is intended for use in Mon-
goDB 2.2 and earlier.
geoHaystack Indexes(page 452)A haystack index is a special index optimized to return results over small areas. For
queries that use spherical geometry, a2dsphereindex is a better option than a haystack index.
2d Index Internals(page 452)Provides a more in-depth explanation of the internals of geospatial indexes. This ma-
terial is not necessary for normal operations but may be useful for troubleshooting and for further understanding.
446 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
2dsphereIndexesNew in version 2.4.
A2dsphereindex supports queries that calculate geometries on an earth-like sphere. The index supports data stored
as bothGeoJSONobjects and as legacy coordinate pairs. The index supports legacy coordinate pairs by converting
the data to the GeoJSONPointtype. The default datum for an earth-like sphere in MongoDB 2.4 isWGS84.
Coordinate-axis order islongitude, latitude.
The2dsphereindex supports all MongoDB geospatial queries: queries for inclusion, intersection and proxim-
ity. See thehttp://docs.mongodb.org/manualreference/operator/query-geospatial for the
query operators that support geospatial queries.
To create a2dsphereindex, use thedb.collection.ensureIndex method. Acompound(page 440)
2dsphereindex can reference multiple location and non-location elds within a collection's documents. SeeCreate
a 2dsphere Index(page 476) for more information.
2dsphereVersion 2Changed in version 2.6.
MongoDB 2.6 introduces a version 2 of2dsphereindexes. Version 2 is the default version of2dsphere
indexes created in MongoDB 2.6. To create a2dsphereindex as a version 1, include the option{
"2dsphereIndexVersion": 1 } when creating the index.
Additional GeoJSON ObjectsChanged in version 2.6.
Version 2 adds support for additional GeoJSON object:MultiPoint(page 449),MultiLineString(page 450),MultiPoly-
gon(page 450), andGeometryCollection(page 450).
sparsePropertyChanged in version 2.6.
Version 22dsphereindexes aresparse(page 457) by default and ignores thesparse: true(page 457) option. If
a document lacks a2dsphereindex eld (or the eld isnullor an empty array), MongoDB does not add an
entry for the document to the2dsphereindex. For inserts, MongoDB inserts the document but does not add to the
2dsphereindex.
For a compound index that includes a2dsphereindex key along with keys of other types, only the2dsphere
index eld determines whether the index references a document.
Earlier versions of MongoDB only support Version 12dsphereindexes. Version 12dsphereindexes arenot
sparse by default and will reject documents withnulllocation elds.
Considerations
geoNearand$geoNearRestrictionsThegeoNearcommand and the$geoNearpipeline stage require that
a collection haveat mostonly one2dsphereindex and/or only one2d(page 451) index whereasgeospatial query
operators(e.g.$nearand$geoWithin) permit collections to have multiple geospatial indexes.
The geospatial index restriction for thegeoNearcommand nor the$geoNearpipeline stage exists because neither
thegeoNearcommand nor the$geoNearpipeline stage syntax includes the location eld. As such, index selection
among multiple2dindexes or2dsphereindexes is ambiguous.
No such restriction applies forgeospatial query operatorssince these operators take a location eld, eliminating the
ambiguity.
Shard Key RestrictionsYou cannot use a2dsphereindex 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 eld as the shard key.
8.2. Index Concepts 447

MongoDB Documentation, Release 2.6.4
GeoJSON ObjectsMongoDB supports the following GeoJSON objects:
Point(page 448)
LineString(page 448)
Polygon(page 448)
MultiPoint(page 449)
MultiLineString(page 450)
MultiPolygon(page 450)
GeometryCollection(page 450)
TheMultiPoint(page 449),MultiLineString(page 450),MultiPolygon(page 450), andGeometryCollection(page 450)
require2dsphereindex version 2.
In order to index GeoJSON data, you must store the data in a location eld that you name. The location eld contains
a subdocument with atypeeld specifying the GeoJSON object type and acoordinateseld specifying the
object's coordinates. Always store coordinates inlongitude, latitude order.
Use the following syntax:
{location field>:::coordinates>
PointNew in version 2.4.
The following example stores a GeoJSONPoint:
{ loc::, coordinates:,
LineStringNew in version 2.4.
The following example stores a GeoJSONLineString:
{ loc::, coordinates:,,
PolygonNew in version 2.4.
Polygonsconsist of an array of GeoJSONLinearRingcoordinate arrays. TheseLinearRingsare closed
LineStrings. ClosedLineStringshave at least four coordinate pairs and specify the same position as the
rst 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 at 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 RingThe following example stores a GeoJSONPolygonwith an exterior ring and no
interior rings (or holes). Note the rst and last coordinate pair with the[ 0 , 0 ]coordinate:
{
loc
{
type:,
coordinates:
}
}
448 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
For Polygons with a single ring, the ring cannot self-intersect.
Polygons with Multiple RingsFor Polygons with multiple rings:

The following document represents a polygon with an interior ring as GeoJSON:
{ loc
type,
coordinates
[ [
[ [
]
}
}
Figure 8.10: Diagram of a Polygon with internal ring.
MultiPointNew in version 2.6: Requires2dsphereindex version 2.
The following example stores coordinates of GeoJSON type
3
:
{ loc:
type:,
coordinates:
[73.9580,
3
http://geojson.org/geojson-spec.html#id5
8.2. Index Concepts 449

MongoDB Documentation, Release 2.6.4
[73.9498,
[73.9737,
[73.9814,
]
}
}
MultiLineString New in version 2.6: Requires2dsphereindex version 2.
The following example stores coordinates of GeoJSON type
4
:
{ loc:
{
type:,
coordinates:
[ [73.96943,73.96082,
[ [73.96415,73.95544,
[ [73.97162,73.96374,
[ [73.97880,73.97036,
]
}
}
MultiPolygon New in version 2.6: Requires2dsphereindex version 2.
The following example stores coordinates of GeoJSON type
5
:
{ loc:
{
type:,
coordinates:
[ [ [73.958,73.9498,73.9737,73.9814,73.958,
[ [ [73.958,73.9498,73.9737,73.958,
]
}
}
GeometryCollection New in version 2.6: Requires2dsphereindex version 2.
The following example stores coordinates of GeoJSON type
6
:
{ loc:
{
type:,
geometries:
{
type:,
coordinates:
[73.9580,
[73.9498,
[73.9737,
[73.9814,
]
4
http://geojson.org/geojson-spec.html#id6
5
http://geojson.org/geojson-spec.html#id7
6
http://geojson.org/geojson-spec.html#geometrycollection
450 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
},
{
type:,
coordinates:
[ [73.96943,73.96082,
[ [73.96415,73.95544,
[ [73.97162,73.96374,
[ [73.97880,73.97036,
]
}
]
}
}
2dIndexesUse a2dindex for data stored as points on a two-dimensional plane. The2dindex is intended for
legacy coordinate pairs used in MongoDB 2.2 and earlier.
Use a2dindex if:
and
GeoJSONobjects.
See thehttp://docs.mongodb.org/manualreference/operator/query-geospatial for the
query operators that support geospatial queries.
ConsiderationsThegeoNearcommand and the$geoNearpipeline stage require that a collection haveat most
only one2dindex and/or only one2dsphere index(page 447) whereasgeospatial query operators(e.g.$nearand
$geoWithin) permit collections to have multiple geospatial indexes.
The geospatial index restriction for thegeoNearcommand nor the$geoNearpipeline stage exists because neither
thegeoNearcommand nor the$geoNearpipeline stage syntax includes the location eld. As such, index selection
among multiple2dindexes or2dsphereindexes is ambiguous.
No such restriction applies forgeospatial query operatorssince these operators take a location eld, eliminating the
ambiguity.
Do not use a2dindex if your location data includes GeoJSON objects. To index on both legacy coordinate pairsand
GeoJSON objects, use a2dsphere(page 447) index.
You cannot use a2dindex 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 eld as the shard key.
BehaviorThe2dindex supports calculations on a at, Euclidean plane. The2dindex also supportsdistance-only
calculations on a sphere, but forgeometriccalculations (e.g.$geoWithin) on a sphere, store data as GeoJSON
objects and use the2dsphereindex type.
A2dindex can reference two elds. The rst must be the location eld. A2dcompound index constructs queries
that select rst on the location eld, and then lters those results by the additional criteria. A compound2dindex can
cover queries.
Points on a 2D PlaneTo store location data as legacy coordinate pairs, use an array or an embedded document.
When possible, use the array format:
loclongitude>latitude>
Consider the embedded document form:
8.2. Index Concepts 451

MongoDB Documentation, Release 2.6.4
loclongitude>latitude>
Arrays are preferred as certain languages do not guarantee associative map ordering.
For all points, if you use longitude and latitude, store coordinates inlongitude, latitudeorder.
sparseProperty2dindexes aresparse(page 457) by default and ignores thesparse: true(page 457) option. If
a document lacks a2dindex eld (or the eld isnullor an empty array), MongoDB does not add an entry for the
document to the2dindex. For inserts, MongoDB inserts the document but does not add to the2dindex.
For a compound index that includes a2dindex key along with keys of other types, only the2dindex eld determines
whether the index references a document.
geoHaystackIndexesAgeoHaystackindex is a special index that is optimized to return results over small
areas.geoHaystackindexes improve performance on queries that use at geometry.
For queries that use spherical geometry, a2dsphere index is a better optionthan a haystack index.2dsphere in-
dexes(page 447) allow eld reordering;geoHaystackindexes require the rst eld to be the location eld. Also,
geoHaystackindexes are only usable via commands and so always return all results at once.
BehaviorgeoHaystackindexes create buckets of documents from the same geographic area in order to improve
performance for queries limited to that area. Each bucket in ageoHaystackindex contains all the documents within
a specied proximity to a given longitude and latitude.
sparsePropertygeoHaystackindexes aresparse(page 457) by default and ignore thesparse: true(page 457)
option. If a document lacks ageoHaystackindex eld (or the eld isnullor an empty array), MongoDB does
not add an entry for the document to thegeoHaystackindex. For inserts, MongoDB inserts the document but does
not add to thegeoHaystackindex.
geoHaystackindexes include onegeoHaystackindex key and one non-geospatial index key; however, only the
geoHaystackindex eld determines whether the index references a document.
CreategeoHaystackIndexTo create ageoHaystackindex, seeCreate a Haystack Index(page 482). For
information and example on querying a haystack index, seeQuery a Haystack Index(page 483).
2dIndex InternalsThis document provides a more in-depth explanation of the internals of MongoDB's2dgeospa-
tial 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 for2dIndexesWhen you create a geospatial index onlegacy coordinate pairs,
MongoDB computesgeohashvalues for the coordinate pairs within the speciedlocation range(page 480) 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
00
452 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
These two-bit values (00,01,10, and11) 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 of00. The top
left quadrant would have the geohash of01. The bottom right and top right would have a geohash of10and11,
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 is11, and the geohash for the sub-quadrants would be (clockwise from the top left):1101,
1111,1110, and1100, respectively.
Multi-location Documents for2dIndexesNew in version 2.0: Support for multiple locations in a document.
While2dgeospatial indexes do not support more than one set of coordinates in a document, you can use amulti-key
index(page 442) to index multiple coordinate pairs in a single document. In the simplest example you may have a
eld (e.g.locs) that holds an array of coordinates, as in the following example:
{ _id
locs
[74
{ lng
}
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 thelocseld, as in the following:
db.places.ensureIndex( {:
You may also model the location data as a eld inside of a sub-document. In this case, the document would contain
a eld (e.g.addresses) that holds an array of documents where each document has a eld (e.g.loc:) that holds
location coordinates. For example:
{ _id
name,
addresses
context
loc,
} ,
{
context,
loc74
}
]
}
You could then create the geospatial index on theaddresses.loceld as in the following example:
db.records.ensureIndex( {:
To include the location eld with the distance eld in multi-location document queries, specifyincludeLocs:
truein thegeoNearcommand.
See also:
geospatial-query-compatibility-chart
8.2. Index Concepts 453

MongoDB Documentation, Release 2.6.4
Text Indexes
New in version 2.4.
MongoDB providestextindexes to support text search of string content in documents of a collection.
textindexes can include any eld whose value is a string or an array of string elements. To perform queries that
access thetextindex, use the$textquery 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 createtextindexes and performtext search(page 455).
Create Text IndexTo create atextindex, use thedb.collection.ensureIndex() method. To index a
eld that contains a string or an array of string elements, include the eld and specify the string literal"text"in the
index document, as in the following example:
db.reviews.ensureIndex( { comments:
A collection can have at mostonetextindex.
For examples of creatingtextindexes on multiple elds, seeCreate a text Index(page 486).
Supported Languages and Stop WordsMongoDB supports text search for various languages.textindexes drop
language-specic stop words (e.g. in English, the, an, a, and, etc.) and uses simple language-specic sufx
stemming. For a list of the supported languages, seeText Search Languages(page 501).
If you specify a language value of"none", then thetextindex uses simple tokenization with no list of stop words
and no stemming.
If the index language is English,textindexes are case-insensitive for non-diacritics; i.e. case insensitive for[A-z].
To specify a language for thetextindex, seeSpecify a Language for Text Index(page 487).
sparsePropertytextindexes aresparse(page 457) by default and ignores thesparse: true(page 457) option.
If a document lacks atextindex eld (or the eld isnullor an empty array), MongoDB does not add an entry for
the document to thetextindex. For inserts, MongoDB inserts the document but does not add to thetextindex.
For a compound index that includes atextindex key along with keys of other types, only thetextindex eld
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 HintsYou cannot usehint()if the query includes a$textquery expression.
Compound IndexAcompound index(page 440) can include atextindex key in combination with ascend-
ing/descending index keys. However, these compound indexes have the following restrictions:
A compoundtextindex cannot include any other special index types, such asmulti-key(page 442) orgeospatial
(page 446) index elds.
If the compoundtextindex includes keysprecedingthetextindex key, to perform a$textsearch, the query
predicate must includeequality match conditionson the preceding keys.
SeeLimit the Number of Entries Scanned(page 491).
454 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Drop a Text IndexTo drop atextindex, pass the name of the index to thedb.collection.dropIndex()
method. To get the name of the index, run thegetIndexes()method.
For information on the default naming scheme fortextindexes as well as overriding the default name, seeSpecify
Name for text Index(page 489).
Storage Requirements and Performance Coststextindexes have the following storage requirements and per-
formance costs:
textindexes change the space allocation method for all future record allocations in a collection to
usePowerOf2Sizes.
textindexes can be large. They contain one index entry for each unique post-stemmed word in each indexed
eld for each document inserted.
textindex 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.
textindex on an existing collection, ensure that you have a sufciently high limit on
open le descriptors. See therecommended settings(page 266).
textindexes will impact insertion throughput because MongoDB must add an index entry for each unique
post-stemmed word in each indexed eld of each new source document.
textindexes 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 ts in RAM.
Text SearchText search supports the search of string content in documents of a collection. MongoDB provides the
$textoperator to perform text search in queries and inaggregation pipelines(page 491).
The text search process:

relevance of a document to a given search query.
The$textoperator can search for words and phrases. The query matches on the complete stemmed words. For
example, if a document eld contains the wordblueberry, a search on the termbluewill not match the document.
However, a search on eitherblueberryorblueberrieswill match.
For information and examples on various text search patterns, see the$textquery operator. For examples of text
search in aggregation pipeline, seeText Search in the Aggregation Pipeline(page 491).
Hashed Index
New in version 2.4.
Hashed indexes maintain entries with hashes of the values of the indexed eld. The hashing function collapses sub-
documents and computes the hash for the entire value but does not support multi-key (i.e. arrays) indexes.
Hashed indexes supportsharding(page 607) a collection using ahashed shard key(page 621). Using a hashed shard
key to shard a collection ensures a more even distribution of data. SeeShard a Collection Using a Hashed Shard Key
(page 641) for more details.
MongoDB can use thehashedindex to support equality queries, buthashedindexes do not support range queries.
You may not create compound indexes that havehashedindex elds or specify a unique constraint
on ahashedindex; however, you can create both ahashedindex and an ascending/descending
(i.e. non-hashed) index on the same eld: MongoDB will use the scalar index for range queries.
8.2. Index Concepts 455

MongoDB Documentation, Release 2.6.4
Warning:MongoDBhashedindexes truncate oating point numbers to 64-bit integers before hashing. For
example, ahashedindex would store the same value for a eld that held a value of2.3,2.2, and2.9. To
prevent collisions, do not use ahashedindex for oating point numbers that cannot be reliably converted to
64-bit integers (and then back to oating point). MongoDBhashedindexes do not support oating point values
larger than 2
53
.
Create ahashedindex using an operation that resembles the following:
db.active.ensureIndex( { a:
This operation creates a hashed index for theactivecollection on theaeld.
8.2.2
In addition to the numerousindex types(page 437) 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(page 456)The TTL index is used for TTL collections, which expire data after a period of time.
Unique Indexes(page 457)A unique index causes MongoDB to reject all documents that contain a duplicate value
for the indexed eld.
Sparse Indexes(page 457)A sparse index does not index documents that do not have the indexed eld.
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 some types of information like machine generated event data, logs, and
session information that only need to persist in a database for a limited amount of time.
Considerations
TTL indexes have the following limitations:
Compound indexes(page 440) arenotsupported.
mustbe a datetype.

thelowest(i.e. earliest) matches the expiration threshold.
The TTL index does not guarantee that expired data will be deleted immediately. 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 runsevery 60 seconds. As a result, documents may remain in a
collectionafterthey expire butbeforethe background task runs or completes.
The duration of the removal operation depends on the workload of yourmongodinstance. Therefore, expired data
may exist for some timebeyondthe 60 second period between runs of the background task.
In all other respects, TTL indexes are normal indexes, and if appropriate, MongoDB can use these indexes to fulll
arbitrary queries.
Additional Information
Expire Data from Collections by Setting TTL(page 198)
456 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Unique Indexes
A unique index causes MongoDB to reject all documents that contain a duplicate value for the indexed eld.
To create a unique index, use thedb.collection.ensureIndex() method with theuniqueoption set to
true. For example, to create a unique index on theuser_ideld of thememberscollection, use the following
operation in themongoshell:
db.members.ensureIndex( {:: true} )
By default,uniqueisfalseon MongoDB indexes.
If you use the unique constraint on acompound index(page 440), then MongoDB will enforce uniqueness on the
combinationof values rather than the individual value for any or all values of the key.
Behavior
Unique Constraint Across Separate DocumentsThe unique constraint applies to separate documents in the col-
lection. That is, the unique index preventsseparatedocuments 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 ona.b:
db.collection.ensureIndex( {:: true} )
The unique index permits the insertion of the following document into the collection if no other document in the
collection has thea.bvalue of5:
db.collection.insert( { a:::
Unique Index and Missing FieldIf a document does not have a value for the indexed eld 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 eld. If there is more than one document without a value for the indexed eld or is
missing the indexed eld, the index build will fail with a duplicate key error.
You can combine the unique constraint with thesparse index(page 457) to lter these null values from the unique
index and avoid the error.
RestrictionsYou may not specify a unique constraint on ahashed index(page 455).
See also:
Create a Unique Index(page 467)
Sparse Indexes
Sparse indexes only contain entries for documents that have the indexed eld, even if the index eld contains a null
value. The index skips over any document that is missing the indexed eld. 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 eld.
To create asparseindex, use thedb.collection.ensureIndex() method with thesparseoption set to
true. For example, the following operation in themongoshell creates a sparse index on thexmpp_ideld of the
addressescollection:
8.2. Index Concepts 457

MongoDB Documentation, Release 2.6.4
db.addresses.ensureIndex( {:: true} )
Note:Do not confuse sparse indexes in MongoDB with
7
indexes in other databases. Think of them as
dense indexes with a specic lter.
Behavior
sparseIndex and Incomplete ResultsChanged 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 ahint()explicitly species the index.
For example, the query{ x: { $exists: false } } will not use a sparse index on thexeld unless
explicitly hinted. SeeSparse Index On A Collection Cannot Return Complete Results(page 459) for an example that
details the behavior.
Indexes that aresparseby Default2dsphere (version 2)(page 447),2d(page 451),geoHaystack(page 452), and
text(page 454) indexes are alwayssparse.
sparseCompound IndexesSparsecompound indexes(page 440) 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(page 447),2d(page 451), orgeoHaystack
(page 452) index keys) along with ascending/descending index key(s), only the existence of the geospatial eld(s) in
a document determine whether the index references the document.
For sparse compound indexes that containtext(page 454) index keys along with ascending/descending index keys,
only the existence of thetextindex eld(s) determine whether the index references a document.
sparseanduniquePropertiesAn index that is bothsparseandunique(page 457) prevents collection from
having documents with duplicate values for a eld but allows multiple documents that omit the key.
Examples
Create a Sparse Index On A CollectionConsider a collectionscoresthat contains the following documents:
{"523b6e32fb408eea0eec2647"),
{"523b6e61fb408eea0eec2648"),,
{"523b6e6ffb408eea0eec2649"),,
The collection has a sparse index on the eldscore:
db.scores.ensureIndex( { score:: true} )
Then, the following query on thescorescollection uses the sparse index to return the documents that have the
scoreeld less than ($lt)90:
db.scores.find( { score::
Because the document for the userid"newbie"does not contain thescoreeld and thus does not meet the query
criteria, the query can use the sparse index to return the results:
7
http://en.wikipedia.org/wiki/Database_index#Sparse_index
458 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
{"523b6e61fb408eea0eec2648"),,
Sparse Index On A Collection Cannot Return Complete ResultsConsider a collectionscoresthat contains the
following documents:
{"523b6e32fb408eea0eec2647"),
{"523b6e61fb408eea0eec2648"),,
{"523b6e6ffb408eea0eec2649"),,
The collection has a sparse index on the eldscore:
db.scores.ensureIndex( { score:: true} )
Because the document for the userid"newbie"does not contain thescoreeld, the sparse index does not contain
an entry for that document.
Consider the following query to returnalldocuments in thescorescollection, sorted by thescoreeld:
db.scores.find().sort( { score:1
Even though the sort is by the indexed eld, MongoDB willnotselect the sparse index to fulll the query in order to
return complete results:
{"523b6e6ffb408eea0eec2649"),,
{"523b6e61fb408eea0eec2648"),,
{"523b6e32fb408eea0eec2647"),
To use the sparse index, explicitly specify the index withhint():
db.scores.find().sort( { score:1:
The use of the index results in the return of only those documents with thescoreeld:
{"523b6e6ffb408eea0eec2649"),,
{"523b6e61fb408eea0eec2648"),,
See also:
explain()andAnalyze Query Performance(page 97)
Sparse Index with Unique ConstraintConsider a collectionscoresthat contains the following documents:
{"523b6e32fb408eea0eec2647"),
{"523b6e61fb408eea0eec2648"),,
{"523b6e6ffb408eea0eec2649"),,
You could create an index with aunique constraint(page 457) and sparse lter on thescoreeld using the following
operation:
db.scores.ensureIndex( { score:: true, unique: true} )
This indexwould permitthe insertion of documents that had unique values for thescoreeldordid not include a
scoreeld. Consider the followinginsert operation(page 84):
db.scores.insert( {:,:
db.scores.insert( {:,:
db.scores.insert( {:
db.scores.insert( {:
8.2. Index Concepts 459

MongoDB Documentation, Release 2.6.4
However, the indexwould not permitthe addition of the following documents since documents already exists with
scorevalue of82and90:
db.scores.insert( {:,:
db.scores.insert( {:,:
8.2.3
MongoDB provides several options thatonlyaffect the creation of the index. Specify these options in a document as
the second argument to thedb.collection.ensureIndex() method. This section describes the uses of these
creation options and their behavior.
Related
Some options that you can specify toensureIndex()options control theproperties of the index(page 456), which
arenotindex creation options. For example, theunique(page 457) option affects the behavior of the index after
creation.
For a detailed description of MongoDB's index types, seeIndex Types(page 437) andIndex Properties(page 456) 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 thebackgroundoperation so that the MongoDB
database remains available during the index building operation. For example, to create an index in the background of
thezipcodeeld of thepeoplecollection, issue the following:
db.people.ensureIndex( { zipcode:}, {background: true} )
By default,backgroundisfalsefor building MongoDB indexes.
You can combine the background option with other options, as in the following:
db.people.ensureIndex( { zipcode:}, {background: true, sparse: true} )
Behavior
As of MongoDB version 2.4, amongodinstance can build more than one index in the background concurrently.
Changed in version 2.4: Before 2.4, amongodinstance could only build one background index per database at a time.
Changed in version 2.2: Before 2.2, a singlemongodinstance 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, themongoshell session or connection where you are creating the indexwillblock until the index
build is complete. To continue issuing commands to the database, open another connection ormongoinstance.
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 administra-
tive operations involving that collection, including runningrepairDatabase, dropping the collection (i.e.
460 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
db.collection.drop() ), and runningcompact. 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 takemuchlonger than the
foreground build.
If your application includesensureIndex()operations, and an indexdoesn'texist 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
8
and terminates if the proper indexes do not ex-
ist. 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 areplica set secondariesbegin after theprimarycompletes building the index. If
MongoDB builds an index in the background on the primary, the secondaries will then build that index in the back-
ground.
To build large indexes on secondaries the best approach is to restart one secondary at a time instandalonemode 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 theoplog, 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.
SeeBuild Indexes on Replica Sets(page 469) for a complete procedure for building indexes on secondaries.
Drop Duplicates
MongoDB cannot create aunique index(page 457) on a eld that has duplicate values. To force the creation of a
unique index, you can specify thedropDupsoption, which will only index the rst 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 eld, MongoDB will include it in the
index with a null value.
If subsequent eldsdo nothave the indexed eld, and you have set{dropDups: true} , MongoDB will remove
these documents from the collection when creating the index. If you combinedropDupswith thesparse(page 457)
option, this index will only include documents in the index that have the value, and the documents without the eld
will remain in the database.
8
http://api.mongodb.org/
8.2. Index Concepts 461

MongoDB Documentation, Release 2.6.4
To create a unique index that drops duplicates on theusernameeld of theaccountscollection, use a command
in the following form:
db.accounts.ensureIndex( { username:: true, dropDups: true} )
Warning:Specifying{ dropDups: true } will delete data from your database. Use with extreme cau-
tion.
By default,dropDupsisfalse.
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 onitemandquantity:
db.products.ensureIndex( { item:, 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 onitemandquantityand specifyinventoryas the index
name:
db.products.ensureIndex( { item:, quantity:1:
The resulting index has the nameinventory.
To view the name of an index, use thegetIndexes()method.
8.2.4
New in version 2.6.
MongoDB can use the intersection of multiple indexes to fulll queries.
9
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 collectionordersthat has the following indexes:
{ qty:
{ item:
MongoDB can use the intersection of the two indexes to support the following query:
db.orders.find( { item:, qty::
For query plans that use index intersection, theexplain()returns the valueComplex Planin thecursoreld.
9
In previous versions, MongoDB could use only a single index to fulll most queries. The exception to this is queries with$orclauses, which
could use a single index for each$orclause.
462 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Index Prex Intersection
With index intersection, MongoDB can use an intersection of either the entire index or the index prex. An index
prex is a subset of a compound index, consisting of one or more keys starting from the beginning of the index.
Consider a collectionorderswith the following indexes:
{ qty:
{ status:, ord_date:1
To fulll the following query which species a condition on both theqtyeld and thestatuseld, MongoDB can
use the intersection of the two indexes:
db.orders.find( { qty:::
Index Intersection and Compound Indexes
Index intersection does not eliminate the need for creatingcompound indexes(page 440). 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 incompound indexes(page 440), a compound index may not support a query condition that does not include
theindex prex keys(page 442) or that species a different sort order.
For example, if a collectionordershas the following compound index, with thestatuseld listed before the
ord_dateeld:
{ status:, ord_date:1
The compound index can support the following queries:
db.orders.find( { status::"A",
db.orders.find(
{
ord_date:: newDate("2014-02-01") },
status::[,
}
)
But not the following two queries:
db.orders.find( { ord_date:: newDate("2014-02-01") } } )
db.orders.find( { } ).sort( { ord_date:
However, if the collection has two separate indexes:
{ status:
{ 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 specics of your system.
See also:
compound indexes(page 440),Create Compound Indexes to Support Several Different Queries(page 494)
8.2. Index Concepts 463

MongoDB Documentation, Release 2.6.4
Index Intersection and Sort
Index intersection does not apply when thesort()operation requires an index completely separate from the query
predicate.
For example, theorderscollection has the following indexes:
{ qty:
{ status:, ord_date:1
{ status:
{ ord_date:1
MongoDB cannot use index intersection for the following query with sort:
db.orders.find( { qty:::
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 fulll part of the query predicate.
db.orders.find( { qty::::1
8.3
Indexes allow MongoDB to process and fulll queries quickly by creating small and efcient representations of the
documents in a collection.
The documents in this section outline specic 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
theIndex Concepts(page 436) document.
Index Creation Tutorials(page 464)Create and congure different types of indexes for different purposes.
Index Management Tutorials(page 472)Monitor and assess index performance and rebuild indexes as needed.
Geospatial Index Tutorials(page 476)Create indexes that support data stored asGeoJSONobjects and legacy coor-
dinate pairs.
Text Search Tutorials(page 486)Build and congure indexes that support full-text searches.
Indexing Strategies(page 493)The factors that affect index performance and practical approaches to indexing in
MongoDB
8.3.1
Instructions for creating and conguring indexes in MongoDB and building indexes on replica sets and sharded clus-
ters.
Create an Index(page 465)Build an index for any eld on a collection.
Create a Compound Index(page 466)Build an index of multiple elds on a collection.
Create a Unique Index(page 467)Build an index that enforces unique values for the indexed eld or elds.
Create a Sparse Index(page 467)Build an index that omits references to documents that do not include the indexed
eld. This saves space when indexing elds that are present in only some documents.
464 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Create a Hashed Index(page 468)Compute a hash of the value of a eld 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(page 469)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(page 470)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(page 471)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
Indexes allow MongoDB to process and fulll queries quickly by creating small and efcient representations of the
documents in acollection. Users can create indexes for any collection on any eld in adocument. By default,
MongoDB creates an index on the_ideld of every collection.
This tutorial describes how to create an index on a single eld. MongoDB also supportscompound indexes(page 440),
which are indexes on multiple elds. SeeCreate a Compound Index(page 466) for instructions on building compound
indexes.
Create an Index on a Single Field
To create an index, useensureIndex()or a similar
10
. TheensureIndex()method
only creates an index if an index of the same specication does not already exist.
For example, the following operation creates an index on theuserideld of therecordscollection:
db.records.ensureIndex( { userid:
The value of the eld in the index specication describes the kind of index for that eld. For example, a value of1
species an index that orders items in ascending order. A value of-1species an index that orders items in descending
order. For additional index types, seeIndex Types(page 437).
The created index will support queries that select on the elduserid, such as the following:
db.records.find( { userid:
db.records.find( { userid::
But the created index does not support the following query on theprofile_urleld:
db.records.find( { profile_url:
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. SeeOper-
ational Considerations for Indexes(page 137) 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 inBackground Construction(page 460). To
build indexes on replica sets, see theBuild Indexes on Replica Sets(page 469) section for more information.
10
http://api.mongodb.org/
8.3. Indexing Tutorials 465

MongoDB Documentation, Release 2.6.4
Note:To build or rebuild indexes for areplica setseeBuild Indexes on Replica Sets(page 469).
Some drivers may specify indexes, usingNumberLong(1)rather than1as the specication. This does not have any
affect on the resulting index.
See also:
Create a Compound Index(page 466),Indexing Tutorials(page 464) andIndex Concepts(page 436) for more infor-
mation.
Create a Compound Index
Indexes allow MongoDB to process and fulll queries quickly by creating small and efcient representations of the
documents in acollection. MongoDB supports indexes that include content on a single eld, as well ascompound
indexes(page 440) that include content from multiple elds. Continue reading for instructions and examples of
building a compound index.
Build a Compound Index
To create acompound index(page 440) use an operation that resembles the following prototype:
db.collection.ensureIndex( { a:, b:, c:
The value of the eld in the index specication describes the kind of index for that eld. For example, a value of1
species an index that orders items in ascending order. A value of-1species an index that orders items in descending
order. For additional index types, seeIndex Types(page 437).
Example
The following operation will create an index on theitem,category, andpriceelds of theproductscollec-
tion:
db.products.ensureIndex( { item:, category:, price:
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 inBackground Construction(page 460). To
build indexes on replica sets, see theBuild Indexes on Replica Sets(page 469) section for more information.
Note:To build or rebuild indexes for areplica setseeBuild Indexes on Replica Sets(page 469).
Some drivers may specify indexes, usingNumberLong(1)rather than1as the specication. This does not have any
affect on the resulting index.
See also:
Create an Index(page 465),Indexing Tutorials(page 464) andIndex Concepts(page 436) for more information.
466 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Create a Unique Index
MongoDB allows you to specify aunique constraint(page 457) on an index. These constraints prevent applications
from insertingdocumentsthat have duplicate values for the inserted elds. Additionally, if you want to create an index
on a collection that has existing data that might have duplicate values for the indexed eld, you may choose to combine
unique enforcement withduplicate dropping(page 461).
Unique Indexes
To create aunique index(page 457), consider the following prototype:
db.collection.ensureIndex( { a:: true} )
For example, you may want to create a unique index on the"tax-id":of theaccountscollection to prevent
storing multiple account records for the same legal entity:
db.accounts.ensureIndex( {:: true} )
The_id index(page 439) is a unique index. In some situations you may consider using the_ideld itself for this
kind of data rather than using a unique index on another eld.
In many situations you will want to combine theuniqueconstraint with thesparseoption. When MongoDB
indexes a eld, if a document does not have a value for a eld, the index entry for that item will benull. Since
unique indexes cannot have duplicate values for a eld, without thesparseoption, MongoDB will reject the second
document and all subsequent documents without the indexed eld. Consider the following prototype.
db.collection.ensureIndex( { a:: true, sparse: true} )
You can also enforce a unique constraint oncompound indexes(page 440), as in the following prototype:
db.collection.ensureIndex( { a:, b:: true} )
These indexes enforce uniqueness for thecombinationof index keys andnotfor either key individually.
Drop Duplicates
To force the creation of aunique index(page 457) index on a collection with duplicate values in the eld you are
indexing you can use thedropDupsoption. This will force MongoDB to create auniqueindex by deleting documents
with duplicate values when building the index. Consider the following prototype invocation ofensureIndex():
db.collection.ensureIndex( { a:: true, dropDups: true} )
See the full documentation ofduplicate dropping(page 461) for more information.
Warning:Specifying{ dropDups: true } may delete data from your database. Use with extreme cau-
tion.
Refer to theensureIndex()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 eld. For elds that are only present in some documents sparse indexes may provide a signicant space
savings. SeeSparse Indexes(page 457) for more information about sparse indexes and their use.
8.3. Indexing Tutorials 467

MongoDB Documentation, Release 2.6.4
See also:
Index Concepts(page 436) andIndexing Tutorials(page 464) for more information.
Prototype
To create asparse index(page 457) on a eld, use an operation that resembles the following prototype:
db.collection.ensureIndex( { a:: true} )
Example
The following operation, creates a sparse index on theuserscollection thatonlyincludes a document in the index if
thetwitter_nameeld exists in a document.
db.users.ensureIndex( { twitter_name:: true} )
The index excludes all documents that do not include thetwitter_nameeld.
Considerations
Note:Sparse indexes can affect the results returned by the query, particularly with respect to sorts on eldsnot
included in the index. See thesparse index(page 457) section for more information.
Create a Hashed Index
New in version 2.4.
Hashed indexes(page 455) compute a hash of the value of a eld 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 donotneed
to compute hashes.
See
Hashed Shard Keys(page 621) for more information about hashed indexes in sharded clusters, as well asIndex Con-
cepts(page 436) andIndexing Tutorials(page 464) for more information about indexes.
Procedure
To create ahashed index(page 455), specifyhashedas the value of the index key, as in the following example:
Example
Specify a hashed index on_id
db.collection.ensureIndex( { _id:
468 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Considerations
MongoDB supportshashedindexes of any single eld. The hashing function collapses sub-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 havehashedindex elds.
Build Indexes on Replica Sets
For replica sets, secondaries will begin building indexesaftertheprimarynishes building the index. Insharded
clusters, themongoswill sendensureIndex()to the primary members of the replica set for each shard, which
then replicate to the secondaries after the primary nishes 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(page 464) andIndex Concepts(page 436) for more information.
Considerations
oplogis large enough to permit the indexing or re-indexing operation to complete without
falling too far behind to catch up. See theoplog sizing(page 535) documentation for additional information.
doestake 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 thanallsecondaries at the same time.
notuse this procedure when building aunique index(page 457) with thedropDupsoption.
Background index creation operations(page 460) becomeforegroundindexing operations
onsecondarymembers 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 asharded cluster, repeat the following procedure for each replica set that
provides eachshard.
Stop One SecondaryStop themongodprocess on one secondary. Restart themongodprocesswithoutthe
--replSetoption and running on a different port.
11
This instance is now in standalone mode.
For example, if yourmongodnormallyruns with on the default port of27017with the--replSetoption you
would use the following invocation:
mongod --port 47017
11
By running themongodon 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.
8.3. Indexing Tutorials 469

MongoDB Documentation, Release 2.6.4
Build the IndexCreate the new index using theensureIndex()in themongoshell, or comparable method in
your driver. This operation will create or rebuild the index on thismongodinstance
For example, to create an ascending index on theusernameeld of therecordscollection, use the following
mongoshell operation:
db.records.ensureIndex(
See also:
Create an Index(page 465) andCreate a Compound Index(page 466) for more information.
Restart the ProgrammongodWhen the index build completes, start themongodinstance 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 SecondariesChanged in version 2.6: Secondary members can nowbuild indexes in the back-
ground(page 470). Previously all index builds on secondaries were in the foreground.
For each secondary in the set, build an index according to the following steps:
1.Stop One Secondary(page 469)
2.Build the Index(page 470)
3.Restart the Program mongod(page 470)
Build the Index on the PrimaryTo build an index on the primary you can either:
1.Build the index in the background(page 470) on the primary.
2. rs.stepDown()method in themongoshell 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:
(a)Stop One Secondary(page 469)
(b)Build the Index(page 470)
(c)Restart the Program mongod(page 470)
Building the index on 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(page 460) allows read and write operations to continue while building the index.
See also:
470 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Index Concepts(page 436) andIndexing Tutorials(page 464) for more information.
Considerations
Background index builds take longer to complete and result in an index that isinitiallylarger, 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 nishes building the index, background-built indexes are functionally identical to any other index.
Procedure
To create an index in the background, add thebackgroundargument to theensureIndex()operation, as in the
following index:
db.collection.ensureIndex( { a:: true} )
Consider the section onbackground index construction(page 460) for more information about these indexes and their
implications.
Build Old Style Indexes
Important:Use this procedureonlyif youmusthave 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 mustdropandre-createyour indexes.
To build pre-2.0 indexes, use thedropIndexes()andensureIndex()methods. Youcannotsimply reindex the
collection. When you reindex on versions that only support{v:0}indexes, thevelds in the index denition still
hold values of1, 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
itemscollection:
{,,
Theveld 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
To recreate the index as a{v:0}index, issue the following command:
db.foo.ensureIndex( { name
See also:
Index Performance Enhancements(page 794).
8.3. Indexing Tutorials 471

MongoDB Documentation, Release 2.6.4
8.3.2
Instructions for managing indexes and assessing index performance and use.
Remove Indexes(page 472)Drop an index from a collection.
Modify an Index(page 472)Modify an existing index.
Rebuild Indexes(page 474)In a single operation, drop all indexes on a collection and then rebuild them.
Manage In-Progress Index Creation(page 474)Check the status of indexing progress, or terminate an ongoing in-
dex build.
Return a List of All Indexes(page 475)Obtain a list of all indexes on a collection or of all indexes on all collections
in a database.
Measure Index Use(page 475)Study query operations and observe index use for your database.
Remove Indexes
To remove an index from a collection use thedropIndex()method and the following procedure. If you simply
need to rebuild indexes you can use the process described in theRebuild Indexes(page 474) document.
See also:
Indexing Tutorials(page 464) andIndex Concepts(page 436) for more information about indexes and indexing oper-
ations in MongoDB.
Remove a Specic Index
To remove an index, use thedb.collection.dropIndex() method.
For example, the following operation removes an ascending index on thetax-ideld in theaccountscollection:
db.accounts.dropIndex( {:
The operation returns a document with the status of the operation:
{,
Where the value ofnIndexesWasreects the number of indexesbeforeremoving this index.
Fortext(page 454) indexes, pass the index name to thedb.collection.dropIndex() method. SeeUse the
Index Name to Drop a text Index(page 489) for details.
Remove All Indexes
You can also use thedb.collection.dropIndexes() to removeallindexes, except for the_id index(page 439)
from a collection.
These shell helpers provide wrappers around thedropIndexesdatabase command. Yourclient librarymay
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.
472 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Step 1: Create a unique index.
Use theensureIndex()method create a unique index.
db.orders.ensureIndex(
{,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. SeeCreate an Index(page 465) andIndex Creation Tutorials(page 464) for more information on
creating indexes.
Step 2: Attempt to modify the index.
To modify an existing index, youcannotjust re-issue theensureIndex()method with the updated specication
of the index.
For example, the following operation attempts to remove theuniqueconstraint from the previously created index by
using theensureIndex()method.
db.orders.ensureIndex(
{,1,
)
The status document returned by the operation shows an error.
Step 3: Drop the index.
To modify the index, you must drop the index rst.
db.orders.dropIndex(
{,1,
)
The method returns a document with the status of the operation. Upon successful operation, theokeld in the returned
document should specify a1. SeeRemove Indexes(page 472) for more information about dropping indexes.
Step 4: Recreate the index without theuniqueconstraint.
Recreate the index without theuniqueconstraint.
db.orders.ensureIndex(
{,1,
)
The method returns a document with the status of the results. Upon successful operation, the returned document
should show thenumIndexesAfterto be greater thannumIndexesBeforeby one.
See also:
Index Introduction(page 431),Index Concepts(page 436).
8.3. Indexing Tutorials 473

MongoDB Documentation, Release 2.6.4
Rebuild Indexes
If you need to rebuild indexes for a collection you can use thedb.collection.reIndex() method to rebuild all
indexes on a collection in a single operation. This operation drops all indexes, including the_id index(page 439), and
then rebuilds all indexes.
See also:
Index Concepts(page 436) andIndexing Tutorials(page 464).
Process
The operation takes the following form:
db.accounts.reIndex()
MongoDB will return the following document when the operation completes:
{
"nIndexesWas",
"msg",
"nIndexes",
"indexes"
{
"key"
"_id",
"tax-id"
},
"ns",
"name"
}
],
"ok"
}
This shell helper provides a wrapper around thereIndexdatabase command. Yourclient librarymay have
a different or additional interface for this operation.
Additional Considerations
Note:To build or rebuild indexes for areplica setseeBuild Indexes on Replica Sets(page 469).
Manage In-Progress Index Creation
To see the status of the indexing processes, you can use thedb.currentOp()method in themongoshell. The
value of thequeryeld and themsgeld will indicate if the operation is an index build. Themsgeld also indicates
the percent of the build that is complete.
To terminate an ongoing index build, use thedb.killOp()method in themongoshell.
For more information seedb.currentOp().
Changed in version 2.4: Before MongoDB 2.4, you couldonlyterminatebackgroundindex builds. After 2.4, you can
terminate any index build, including foreground index builds.
474 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
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 correspondingdocumentin thesystem.indexes(page 271) collection, and you can use standard queries (i.e.
find()) to list the indexes, or in themongoshell, thegetIndexes()method to return a list of the indexes on a
collection, as in the following examples.
See also:
Index Concepts(page 436) andIndexing Tutorials(page 464) 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 thedb.collection.getIndexes() method or a similar
method for your driver
12
.
For example, to view all indexes on thepeoplecollection:
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 themongoshell:
db.system.indexes.find()
Seesystem.indexes(page 271) 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, Mon-
goDB provides a number of tools that allow you to study query operations and observe index use for your database.
See also:
Index Concepts(page 436) andIndexing Tutorials(page 464) for more information.
Operations
Return Query Plan withexplain()Append theexplain()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 withhint()Append thehint()to any cursor (e.g. query) with the index as the argument to
forceMongoDB to use a specic index to fulll the query. Consider the following example:
db.people.find( { name:, zipcode:::
12
http://api.mongodb.org/
8.3. Indexing Tutorials 475

MongoDB Documentation, Release 2.6.4
You can usehint()andexplain()in conjunction with each other to compare the effectiveness of a specic
index. Specify the$naturaloperator to thehint()method to prevent MongoDB from usinganyindex:
db.people.find( { name:, zipcode:::
Instance Index Use ReportingMongoDB provides a number of metrics of index use and operation that you may
want to consider when analyzing index use for your database:
serverStatus:
indexCounters
scanned
scanAndOrder
collStats:
totalIndexSize
indexSizes
dbStats:
dbStats.indexes
dbStats.indexSize
8.3.3
Instructions for creating and querying2d,2dsphere, and haystack indexes.
Create a 2dsphere Index(page 476)A2dsphereindex supports data stored as both GeoJSON objects and as
legacy coordinate pairs.
Query a 2dsphere Index(page 478)Search for locations within, near, or intersected by a GeoJSON shape, or within
a circle as dened by coordinate points on a sphere.
Create a 2d Index(page 480)Create a2dindex to support queries on data stored as legacy coordinate pairs.
Query a 2d Index(page 481)Search for locations using legacy coordinate pairs.
Create a Haystack Index(page 482)A haystack index is optimized to return results over small areas. For queries
that use spherical geometry, a2dsphereindex is a better option.
Query a Haystack Index(page 483)Search based on location and non-location data within a small area.
Calculate Distance Using Spherical Geometry(page 483)Convert distances to radians and back again.
Create a2dsphereIndex
To create a geospatial index for GeoJSON-formatted data, use thedb.collection.ensureIndex()
method to create a2dsphere index(page 447). In the index specication document for the
db.collection.ensureIndex() method, specify the location eld as the index key and specify the
string literal"2dsphere"as the value:
db.collection.ensureIndex( {location field>
The following procedure presents steps to populate a collection with documents that contain a GeoJSON data eld
and create2dsphere indexes(page 447). Although the procedure populates the collection rst, you can also create the
indexes before populating the collection.
476 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Procedure
First, populate a collectionplaceswith documents that store location data asGeoJSON Point(page 448) in a eld
namedloc. The coordinate order is longitude, then latitude.
db.places.insert(
{
loc:, coordinates:73.97,
name:,
category
}
)
db.places.insert(
{
loc:, coordinates:73.88,
name:,
category
}
)
Then, create the2dsphere(page 447) index.
Create a2dsphereIndexFor example, the following creates a2dsphere(page 447) index on the location eld
loc:
db.places.ensureIndex( { loc
Create a Compound Index with2dsphereIndex KeyAcompound index(page 440) can include a2dsphere
index key in combination with non-geospatial index keys. For example, the following operation creates a compound
index where the rst keylocis a2dsphereindex key, and the remaining keyscategoryandnamesare non-
geospatial index keys, specically descending (-1) and ascending (1) keys respectively.
db.places.ensureIndex( { loc1, name:
Unlike the2d(page 451) index, a compound2dsphereindex does not require the location eld to be the rst eld
indexed. For example:
db.places.ensureIndex( { category
Considerations
ThegeoNearcommand and the$geoNearpipeline stage require that a collection haveat mostonly one2dsphere
index and/or only one2d(page 451) index whereasgeospatial query operators(e.g.$nearand$geoWithin)
permit collections to have multiple geospatial indexes.
The geospatial index restriction for thegeoNearcommand nor the$geoNearpipeline stage exists because neither
thegeoNearcommand nor the$geoNearpipeline stage syntax includes the location eld. As such, index selection
among multiple2dindexes or2dsphereindexes is ambiguous.
No such restriction applies forgeospatial query operatorssince these operators take a location eld, eliminating the
ambiguity.
As such, although this tutorial creates multiple2dsphereindexes, to use thegeoNearcommand or the$geoNear
pipeline stage against the example collection, you will need todropall but one of the2dsphereindexes.
8.3. Indexing Tutorials 477

MongoDB Documentation, Release 2.6.4
To query using the2dsphereindex, seeQuery a 2dsphere Index(page 478).
Query a2dsphereIndex
The following sections describe queries supported by the2dsphereindex. For an overview of recommended geospa-
tial queries, seegeospatial-query-compatibility-chart.
GeoJSON Objects Bounded by a Polygon
The$geoWithinoperator 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
coordinatescoordinates>
} } } } )
The following example selects all points and shapes that exist entirely within a GeoJSON polygon:
db.places.find( { loc
{ $geoWithin
{ $geometry
{ type
coordinates
[
[
[
[
] ]
} } } } )
Intersections of GeoJSON Objects
New in version 2.4.
The$geoIntersectsoperator queries for locations that intersect a specied GeoJSON object. A location inter-
sects the object if the intersection is non-empty. This includes documents that have a shared edge.
The$geoIntersectsoperator uses the following syntax:
db.<collection>.find( {location field>
{ $geoIntersects
{ $geometry
{ type
coordinatescoordinates>
} } } } )
The following example uses$geoIntersectsto select all indexed points and shapes that intersect with the polygon
dened by thecoordinatesarray.
db.places.find( { loc
{ $geoIntersects
{ $geometry
{ type
478 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
coordinates:
[
[
[
[
] ]
} } } } )
Proximity to a GeoJSON Point
Proximity queries return the points closest to the dened point and sorts the results by distance. A proximity query on
GeoJSON data requires a2dsphereindex.
To query for proximity to a GeoJSON point, use either the$nearoperator orgeoNearcommand. Distance is in
meters.
The$nearuses the following syntax:
db.<collection>.find( {location field>
{ $near
{ $geometry
{ type
coordinateslongitude>latitude>
$maxDistancedistance inmeters>
} } } )
For examples, see$near.
ThegeoNearcommand uses the following syntax:
db.runCommand( { geoNearcollection>
near
coordinates:longitude>,latitude>
spherical true} )
ThegeoNearcommand offers more options and returns more information than does the$nearoperator. To run the
command, seegeoNear.
Points within a Circle Dened on a Sphere
To select all grid coordinates in a spherical cap on a sphere, use$geoWithinwith the$centerSphereoperator.
Specify an array that contains:

Calculate Distance Using Spherical Geometry
(page 483).
Use the following syntax:
db.<collection>.find( {location field>
{ $geoWithin
{ $centerSphere
[ [x>,y>radius>
} } )
8.3. Indexing Tutorials 479

MongoDB Documentation, Release 2.6.4
The following example queries grid coordinates and returns all documents within a 10 mile radius of longitude88 W
and latitude30 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
} } } )
Create a2dIndex
To build a geospatial2dindex, use theensureIndex()method and specify2d. Use the following syntax:
db.<collection>.ensureIndex( {location field>
<additional field>value>
{index-specification options>
The2dindex uses the following optional index-specication options:
{ minlower bound>upper bound>
bitsbit precision>
Dene Location Range for a2dIndex
By default, a2dindex assumes longitude and latitude and has boundaries of -180 inclusive and 180 non-inclusive
(i.e.[ -180 , 180 )). If documents contain coordinate data outside of the specied 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 dened.
On2dindexes you can change the location range.
You can build a2dgeospatial index with a location range other than the default. Use theminandmaxoptions when
creating the index. Use the following syntax:
db.collection.ensureIndex( {location field>
{ minlower bound>upper bound>
Dene Location Precision for a2dIndex
By default, a2dindex 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 thegeohash
values used to store location data. You can congure 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 nal query process-
ing. 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 congure a location precision other than the default, use thebitsoption when creating the index. Use following
syntax:
db.<collection>.ensureIndex( {<location field>} ,
{ bitsbit precision>
480 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
For information on the internals of geohash values, seeCalculation of Geohash Values for 2d Indexes(page 452).
Query a2dIndex
The following sections describe queries supported by the2dindex. For an overview of recommended geospatial
queries, seegeospatial-query-compatibility-chart.
Points within a Shape Dened on a Flat Surface
To select all legacy coordinate pairs found within a given shape on a at surface, use the$geoWithinoperator along
with a shape operator. Use the following syntax:
db.<collection>.find( {location field>
{ $geoWithin
{ $box|$polygon|$centercoordinates>
} } } )
The following queries for documents within a rectangle dened by[ 0 , 0 ]at the bottom left corner and by[
100 , 100 ]at the top right corner.
db.places.find( { loc
{ $geoWithin
{ $box
[
} } } )
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:
{ $center-74,
} } } )
For syntax and examples for each shape, see the following:
$box
$polygon
$center(denes a circle)
Points within a Circle Dened on a Sphere
MongoDB supports rudimentary spherical queries on at2dindexes for legacy reasons. In general, spherical calcula-
tions should use a2dsphereindex, as described in2dsphere Indexes(page 447).
To query for legacy coordinate pairs in a spherical cap on a sphere, use$geoWithinwith the$centerSphere
operator. Specify an array that contains:

Calculate Distance Using Spherical Geometry
(page 483).
Use the following syntax:
8.3. Indexing Tutorials 481

MongoDB Documentation, Release 2.6.4
db.<collection>.find( {location field>
{ $geoWithin
{ $centerSpherex>,y>radius>
} } )
The following example query returns all documents within a 10-mile radius of longitude88 Wand latitude30 N.
The example converts distance to radians by dividing distance by the approximate radius of the earth, 3959 miles:
db.<collection>.find( { loc
{ $centerSphere
[ [
} } } )
Proximity to a Point on a Flat Surface
Proximity queries return the 100 legacy coordinate pairs closest to the dened point and sort the results by distance.
Use either the$nearoperator orgeoNearcommand. Both require a2dindex.
The$nearoperator uses the following syntax:
db.<collection>.find( {location field>
{ $nearx>y>
} } )
For examples, see$near.
ThegeoNearcommand uses the following syntax:
db.runCommand( { geoNear:collection>, near:x>y>
ThegeoNearcommand offers more options and returns more information than does the$nearoperator. To run the
command, seegeoNear.
Exact Matches on a Flat Surface
Changed in version 2.6: Previously,2dindexes would support exact-match queries for coordinate pairs.
You cannot use a2dindex to return an exact match for a coordinate pair. Use a scalar, ascending or descending, index
on a eld that stores coordinates to return exact matches.
In the following example, thefind()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 elds: the location eld and a second eld. The second eld 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:
482 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
db.coll.ensureIndex( {location field>
<additional field>
{ bucketSizebucket value>
To build a haystack index, you must specify thebucketSizeoption when creating the index. AbucketSize
of5creates an index that groups location values that are within 5 units of the specied longitude and latitude. The
bucketSizealso 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 dened by buckets can overlap. A document can
exist in multiple buckets.
Example
If you have a collection with documents that contain elds similar to the following:
{ _id, pos:, lat}
{ _id, pos:, lat}
{ _id, pos:, lat}
The following operations create a haystack index with buckets that store keys within 1 unit of longitude or latitude.
db.places.ensureIndex( { pos, type
{ bucketSize
This index stores the document with an_ideld that has the value200in two different buckets:
_ideld has a value of100
_ideld has a value of300
To query using a haystack index you use thegeoSearchcommand. SeeQuery a Haystack Index(page 483).
By default, queries that use a haystack index return 50 documents.
Query a Haystack Index
A haystack index is a special2dgeospatial index that is optimized to return results over small areas. To create a
haystack index seeCreate a Haystack Index(page 482).
To query a haystack index, use thegeoSearchcommand. You must specify both the coordinates and the additional
eld togeoSearch. For example, to return all documents with the valuerestaurantin thetypeeld near the
example point, the command would resemble:
db.runCommand( { geoSearch
search:
near-74,] ,
maxDistance
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(page 483) are not currently supported by haystack indexes.
Thefind()method andgeoNearcommand cannot access the haystack index.
Calculate Distance Using Spherical Geometry
8.3. Indexing Tutorials 483

MongoDB Documentation, Release 2.6.4
Note:While basic queries using spherical distance are supported by the2dindex, consider moving to a2dsphere
index if your data is primarily longitude and latitude.
The2dindex supports queries that calculate distances on a Euclidean plane (at surface). The index also supports the
following query operators and command that calculate distances using spherical geometry:
$nearSphere
$centerSphere
$near
geoNearcommand 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 approximately3,959miles or6,371kilometers.
The following query would return documents from theplacescollection within the circle described by the center[
-74, 40.74 ]with a radius of100miles:
db.places.find( { loc:::74,
100
You may also use thedistanceMultiplier option to thegeoNearto convert radians in themongodprocess,
rather than in your application code. Seedistance multiplier(page 485).
The following spherical query, returns all documents in the collectionplaceswithin100miles from the point[
-74, 40.74 ].
db.runCommand( { geoNear:,
near:74,
spherical: true
} )
The output of the above command would be:
{
// [ ... ]
"results"
{
"dis",
"obj"
"_id"
"loc"
-73,
40
]
}
}
],
484 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
"stats"
// [ ... ]
"avgDistance",
"maxDistance"
},
"ok"
}
Warning:Spherical queries that wrap around the poles or at the transition from-180to180longitude raise an
error.
Note:While the default Earth-like bounds for geospatial indexes are between-180inclusive, and180, valid values
for latitude are between-90and90.
Distance Multiplier
ThedistanceMultiplier option of thegeoNearcommand 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.
UsingdistanceMultiplier in spherical queries provides results from thegeoNearcommand that do not need
radian-to-distance conversion. The following example usesdistanceMultiplier in thegeoNearcommand
with aspherical(page 483) example:
db.runCommand( { geoNear:,
near:74,
spherical: true,
distanceMultiplier:
} )
The output of the above operation would resemble the following:
{
// [ ... ]
"results"
{
"dis",
"obj"
"_id"
"loc"
-73,
40
]
}
}
],
"stats"
// [ ... ]
"avgDistance",
"maxDistance"
},
"ok"
}
8.3. Indexing Tutorials 485

MongoDB Documentation, Release 2.6.4
8.3.4
Instructions for enabling MongoDB's text search feature, and for building and conguring text indexes.
Create a text Index(page 486)Atextindex allows searches on text strings in the index's specied elds.
Specify a Language for Text Index(page 487)The specied language determines the list of stop words and the rules
for Text Search's stemmer and tokenizer.
Specify Name for text Index(page 489)Override thetextindex name limit for long index names.
Control Search Results with Weights(page 490)Give priority to certain search values by denoting the signicance
of an indexed eld relative to other indexed elds
Limit the Number of Entries Scanned(page 491)Create an index to support queries that includes$textexpres-
sions and equality conditions.
Text Search in the Aggregation Pipeline(page 491)Perform various text search in the aggregation pipeline.
Create atextIndex
You can create atextindex on the eld or elds whose value is a string or an array of string elements. When creating
atextindex on multiple elds, you can specify the individual elds or you can use wildcard specier ($**).
Index Specic Fields
The following example creates atextindex on the eldssubjectandcontent:
db.collection.ensureIndex(
{
subject:,
content:
}
)
Thistextindex catalogs all string data in thesubjecteld and thecontenteld, where the eld value is either
a string or an array of string elements.
Index All Fields
To allow for text search on all elds with string content, use the wildcard specier ($**) to index all elds that contain
string content.
The following example indexes any string value in the data of every eld of every document incollectionand
names the indexTextIndex:
db.collection.ensureIndex(
{ **":
{ name:
)
Note:In order to drop atextindex, use the index name. SeeUse the Index Name to Drop a text Index(page 489)
for more information.
486 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Specify a Language for Text Index
This tutorial describes how tospecify the default language associated with the text index(page 487) and also how to
create text indexes for collections that contain documents in different languages(page 487).
Specify the Default Language for atextIndex
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 isenglish.
To specify a different language, use thedefault_languageoption when creating thetextindex. SeeText Search
Languages(page 501) for the languages available fordefault_language.
The following example creates for thequotescollection atextindex on thecontenteld and sets the
default_languagetospanish:
db.quotes.ensureIndex(
{ content
{ default_language:
)
Create atextIndex for a Collection in Multiple Languages
Changed in version 2.6: Added support for language overrides within sub-documents.
Specify the Index Language within the DocumentIf a collection contains documents or sub-documents that are
in different languages, include a eld namedlanguagein the documents or sub-documents and specify as its value
the language for that document or sub-document.
MongoDB will use the specied language for that document or sub-document when building thetextindex:
textindex.

default language for the index.
SeeText Search Languages(page 501) for a list of supported languages.
For example, a collectionquotescontains multi-language documents that include thelanguageeld in the docu-
ment and/or the sub-document as needed:
{
_id:,
language:,
original:,
translation:
[
{
language:,
quote:
},
{
language:,
quote:
}
]
}
8.3. Indexing Tutorials 487

MongoDB Documentation, Release 2.6.4
{
_id:,
language:,
original:,
translation:
[
{
language:,
quote:
},
{
language:,
quote:
}
]
}
{
_id:,
original:,
translation:
{
language:,
quote:
}
}
If you create atextindex on thequoteeld with the default language of English.
db.quotes.ensureIndex( { original:,:
Then, for the documents and subdocuments that contain thelanguageeld, thetextindex uses that language to
parse word stems and other linguistic characteristics.
For sub-documents that do not contain thelanguageeld,
languageeld, then the index uses the document's language for the
sub-document.

For documents that do not contain thelanguageeld, the index uses the default language, which is English.
Use any Field to Specify the Language for a DocumentTo use a eld with a name other thanlanguage, include
thelanguage_overrideoption when creating the index.
For example, give the following command to useidiomaas the eld name instead oflanguage:
db.quotes.ensureIndex( { quote
{ language_override:
The documents of thequotescollection may specify a language with theidiomaeld:
{ _id:, idioma:, quote:
{ _id:, idioma:, quote:
{ _id:, idioma:, quote:
488 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
Specify Name fortextIndex
The default name for the index consists of each indexed eld name concatenated with_text. For example, the
following command creates atextindex on the eldscontent,users.comments, andusers.profiles:
db.collection.ensureIndex(
{
content:,
"users.comments":,
"users.profiles":
}
)
The default name for the index is:
"content_text_users.comments_text_users.profiles_text"
Thetextindex, like other indexes, must fall within theindex name length limit .
Specify a Name fortextIndex
To avoid creating an index with a name that exceeds theindex name length limit , you can pass thename
option to thedb.collection.ensureIndex() method:
db.collection.ensureIndex(
{
content:,
"users.comments":,
"users.profiles":
},
{
name:
}
)
Use the Index Name to Drop atextIndex
Whether thetext(page 454) index has the default name or you specied a name for thetext(page 454) index, to drop
thetext(page 454) index, pass the index name to thedb.collection.dropIndex() method.
For example, consider the index created by the following operation:
db.collection.ensureIndex(
{
content:,
"users.comments":,
"users.profiles":
},
{
name:
}
)
Then, to remove this text index, pass the name"MyTextIndex"to thedb.collection.dropIndex()
method, as in the following:
8.3. Indexing Tutorials 489

MongoDB Documentation, Release 2.6.4
db.collection.dropIndex("MyTextIndex")
To get the names of the indexes, use thedb.collection.getIndexes() method.
Control Search Results with Weights
This document describes how to create atextindex with specied weights for results elds.
For atextindex, theweightof an indexed eld denotes the signicance of the eld relative to the other indexed elds
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 elds in that document. See$metaoperator for details on returning and sorting by text scores.
The default weight is 1 for the indexed elds. To adjust the weights for the indexed elds, include theweights
option in thedb.collection.ensureIndex() method.
Warning:Choose the weights carefully in order to prevent the need to reindex.
A collectionbloghas the following documents:
{ _id:,
content:,
about:,
keywords:
}
{ _id:,
content:,
about:,
keywords:,,
}
To create atextindex with different eld weights for thecontenteld and thekeywordseld, include the
weightsoption to theensureIndex()method. For example, the following command creates an index on three
elds and assigns weights to two of the elds:
db.blog.ensureIndex(
{
content:,
keywords:,
about:
},
{
weights:
content:,
keywords:,
},
name:
}
)
Thetextindex has the following elds and weights:
contenthas a weight of 10,
keywordshas a weight of 5, and
abouthas the default weight of 1.
490 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
These weights denote the relative signicance of the indexed elds to each other. For instance, a term match in the
contenteld has:
2times (i.e.10:5) the impact as a term match in thekeywordseld and
10times (i.e.10:1) the impact as a term match in theabouteld.
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
$textexpression and equality conditions.
A collectioninventorycontains the following documents:
{ _id:, dept:, description:
{ _id:, dept:, description:
{ _id:, dept:, description:
{ _id:, dept:, description:
{ _id:, dept:, description:
{ _id:, dept:, description:
Consider the common use case that performs text searches byindividualdepartments, such as:
db.inventory.find( { dept:, $text::
To limit the text search to scan only those documents within a specicdept, create a compound index thatrstspec-
ies an ascending/descending index key on the elddeptand then atextindex key on the elddescription:
db.inventory.ensureIndex(
{
dept:,
description:
}
)
Then, the text search
13
within a particular department will limit the scan of indexed documents. For example, the
following query scans only those documents withdeptequal tokitchenorfood:
db.inventory.find( { dept:, $text::
A compoundtextindex cannot include any other special index types, such asmulti-key(page 442) orgeospatial
(page 446) index elds.
If the compoundtextindex includes keysprecedingthetextindex key, to perform a$textsearch, the query
predicate must includeequality match conditionson the preceding keys.
See also:
Text Indexes(page 454)
Text Search in the Aggregation Pipeline
New in version 2.6. In the aggregation pipeline, text search is available via the use of the$textquery operator in
the$matchstage.
13
If using the deprecatedtextcommand, thetextcommandmustinclude thefilteroption that species anequalitycondition for the
prex elds.
8.3. Indexing Tutorials 491

MongoDB Documentation, Release 2.6.4
Restrictions
Text search in the aggregation pipeline has the following restrictions:
$matchstage that includes a$textmust be therststage in the pipeline.
textoperator can only occur once in the stage.
textoperator expression cannot appear in$oror$notexpressions.
$meta
aggregation expression in the$sortstage.
Text Score
The$textoperator assigns a score to each document that contains the search term in the indexed elds. The score
represents the relevance of a document to a given text search query. The score can be part of a$sortpipeline
specication as well as part of the projection expression. The{ $meta: "textScore" } expression provides
information on the processing of the$textoperation. See$metaaggregation for details on accessing the score for
projection or sort.
The metadata is only available after the$matchstage that includes the$textoperation.
ExamplesThe following examples assume a collectionarticlesthat has a text index on the eldsubject:
db.articles.ensureIndex( { subject:
Calculate the Total Views for Articles that Contains a Word
The following aggregation searches for the termcakein the$matchstage and calculates the totalviewsfor the
matching documents in the$groupstage.
db.articles.aggregate(
[
{ $match:::
{ $group:: null, views::
]
)
Return Results Sorted by Text Search Score
To sort by the text search score, include a$metaexpression in the$sortstage. The following example matches on
eitherthe termcakeortea, sorts by thetextScorein descending order, and returns only thetitleeld in the
results set.
db.articles.aggregate(
[
{ $match:::
{ $sort:::
{ $project::, _id:
]
)
492 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
The specied metadata determines the sort order. For example, the"textScore"metadata sorts in descending
order. See$metafor 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$matchstage that
includes the$textoperation.
The following example matches oneitherthe termcakeortea, projects thetitleand thescoreelds, and then
returns only those documents with ascoregreater than1.0.
db.articles.aggregate(
[
{ $match:::
{ $project::, _id:, score::
{ $match:::
]
)
Specify a Language for Text Search
The following aggregation searches in spanish for documents that contain the termsaberbut not the termclaroin
the$matchstage and calculates the totalviewsfor the matching documents in the$groupstage.
db.articles.aggregate(
[
{ $match:::, $language:
{ $group:: null, views::
]
)
8.3.5
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 elds.
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 justies an index.
The best overall strategy for designing indexes is to prole a variety of index congurations with data sets similar to
the ones you'll be running in production to see which congurations 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 useoneindex to support any given operation. However, each clause of an$orquery may use a
different index.
The following documents introduce indexing strategies:
Create Indexes to Support Your Queries(page 494)An index supports a query when the index contains all the elds
scanned by the query. Creating indexes that supports queries results in greatly increased query performance.
8.3. Indexing Tutorials 493

MongoDB Documentation, Release 2.6.4
Use Indexes to Sort Query Results(page 496)To support efcient queries, use the strategies here when you specify
the sequential order and sort order of index elds.
Ensure Indexes Fit in RAM(page 498)When your index ts in RAM, the system can avoid reading the index from
disk and you get the fastest processing.
Create Queries that Ensure Selectivity(page 498)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 fullling
the query.
Create Indexes to Support Your Queries
An index supports a query when the index contains all the elds 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 oncategoryin theproductcollection:
db.products.ensureIndex( {:
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 efcient than creating a single-key index. MongoDB will use the compound index for both
queries. For example, you might create an index on bothcategoryanditem.
db.products.ensureIndex( {:,:
This allows you both options. You can query on justcategory, and you also can query oncategorycombined
withitem. A singlecompound index(page 440) on multiple elds can support all the queries that search a prex
subset of those elds.
Example
The following index on a collection:
{ x:, y:, z:
Can support queries that the following indexes support:
{ x:
{ x:, y:
There are some situations where the prex indexes may offer better query performance: for example ifzis a large
array.
The{ x: 1, y: 1, z: 1 } index can also support many of the same queries as the following index:
{ x:, z:
Also,{ x: 1, z: 1 } has an additional use. Given the following query:
494 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
db.collection.find( { x::} )
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, seeUse Indexes to Sort Query Results
(page 496).
Starting in version 2.6, MongoDB can useindex intersection(page 462) to fulll queries. The choice between creating
compound indexes that support your queries or relying on index intersection depends on the specics of your system.
SeeIndex Intersection and Compound Indexes(page 463) for more details.
Create Indexes that Support Covered Queries
A covered query is a query in which:
query(page 87) are part of an index,and

Because the index covers the query, MongoDB can both match thequery conditions(page 87)andreturn the results
using only the index; MongoDB does not need to look at the documents, only the index, to fulll the query.
Queryingonlythe 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.
MongoDB automatically uses an index that covers a query when possible. To ensure that an index cancovera query,
create an index that includes all the elds listed in thequery document(page 87) and in the query result. You can
specify the elds to return in the query results with aprojection(page 94) document. By default, MongoDB includes
the_ideld in the query result. So, if the index doesnotinclude the_ideld, then you must exclude the_ideld
(i.e._id: 0) from the query results.
Example
Given collectionuserswith an index on the eldsuserandstatus, as created by the following option:
db.users.ensureIndex( { status:, user:
Then, this index will cover the following query which selects on thestatuseld and returns only theusereld:
db.users.find( { status::, _id:
In the operation, the projection document explicitly species_id: 0to exclude the_ideld from the result since
the index is only on thestatusand theuserelds.
If the projection document does not specify the exclusion of the_ideld, the query returns the_ideld. The
following query isnotcovered by the index on thestatusand theuserelds because with the projection document
{ user: 1 }, the query returns both theusereld and the_ideld:
db.users.find( { status::
An indexcannotcover a query if:

array, the index becomes amulti-key index(page 442) index and cannot support a covered query.
dot notation. For
example, consider a collectionuserswith documents of the following form:
8.3. Indexing Tutorials 495

MongoDB Documentation, Release 2.6.4
{ _id:, user::
The collection has the following indexes:
{ user: 1 }
{ "user.login": 1 }
The{ user: 1 }index covers the following query:
db.users.find( { user: { login: "tester" } }, { user: 1, _id: 0 } )
However, the{ "user.login": 1 } index doesnotcover the following query:
db.users.find( { "user.login": "tester" }, { "user.login": 1, _id: 0 } )
The query, however, does use the{ "user.login": 1 } index to nd matching documents.
To determine whether a query is a covered query, use theexplain()method. If theexplain()output displays
truefor theindexOnlyeld, the query is covered by an index, and MongoDB queries only that index to match
the queryandreturn the results.
For more information seeMeasure Index Use(page 475).
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 donot
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 eld, the sort operation on the eld can be in either direction.
For example, create an ascending index on the eldafor a collectionrecords:
db.records.ensureIndex( { a:
This index can support an ascending sort ona:
db.records.find().sort( { a:
The index can also support the following descending sort onaby traversing the index in reverse order:
db.records.find().sort( { a:1
Sort on Multiple Fields
Create acompound index(page 440) to support sorting on multiple elds.
You can specify a sort on all the keys of the index or on a subset; however, the sort keys must be listed in thesame
orderas they appear in the index. For example, an index key pattern{ a: 1, b: 1 } can support a sort on{
a: 1, b: 1 } butnoton{ b: 1, a: 1 } .
The sort must specify thesame sort direction(i.e.ascending/descending) for all its keys as the index key pattern or
specify thereverse sort directionfor all its keys as the index key pattern. For example, an index key pattern{ a:
496 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
1, b: 1 }can support a sort on{ a: 1, b: 1 } and{ a: -1, b: -1 } butnoton{ a: -1,
b: 1 }.
Sort and Index PrexIf the sort keys correspond to the index keys or an indexprex, MongoDB can use the index
to sort the query results. Aprexof 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 thedatacollection:
db.data.ensureIndex( { a:1, b:, c:, d:
Then, the following are prexes for that index:
{ a:
{ a:, b:
{ a:, b:, c:
The following query and sort operations use the index prexes to sort the results. These operations do not need to sort
the result set in memory.
Example Index Prex
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 prex keys of the index appear in both the query predicate and the sort:
db.data.find( { a:::, b:
In such cases, MongoDB can use the index to retrieve the documents in order specied by the sort. As the example
shows, the index prex in the query predicate can be different from the prex in the sort.
Sort and Non-prex Subset of an IndexAn index can support sort operations on a non-prex subset of the index
key pattern. To do so, the query must includeequalityconditions on all the prex keys that precede the sort keys.
For example, the collectiondatahas the following index:
{ a:, b:, c:, d:
The following operations can use the index to get the sort order:
Example Index Prex
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 eldsprecedingthe sort subset must have the equality conditions in the
query document; the other index elds may specify other conditions.
8.3. Indexing Tutorials 497

MongoDB Documentation, Release 2.6.4
If the query doesnotspecify an equality conditions on an index prex that precedes or overlaps with the sort speci-
cation, the operation willnotefciently 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 eldsaandb:
db.data.find( { a:::
db.data.find( { c::
These operationswill notefciently 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 t entirely in RAM so that the system can avoid reading the index
from disk.
To check the size of your indexes, use thedb.collection.totalIndexSize() helper, which returns data in
bytes:
>
4294976499
The above example shows an index size of almost 4.3 gigabytes. To ensure this index ts in RAM, you must not only
have more than that much RAM available but also must have RAM available for the rest of theworking 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 t in memory at the same time.
There are some limited cases where indexes do not need to t in memory. SeeIndexes that Hold Only Recent Values
in RAM(page 498).
See also:
collStatsanddb.collection.stats()
Indexes that Hold Only Recent Values in RAM
Indexes do not have to tentirelyinto RAM in all cases. If the value of the indexed eld 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 efcient 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 fullling the query.
To ensure selectivity, write queries that limit the number of possible documents with the indexed eld. Write queries
that are appropriately selective relative to your indexed data.
Example
Suppose you have a eld calledstatuswhere the possible values arenewandprocessed. If you add an index
onstatusyou'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 acompound index(page 440) that includes the low-
selectivity eld and another eld. For example, you could create a compound index onstatusandcreated_at.
498 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
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 keyasorted in ascending order) on a collection whereahas
three values evenly distributed across the collection:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
If you query for{ a: 2, b: "no" } MongoDB must scan 3documentsin 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 whereahasninevalues evenly distributed across the collection:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
{ _id::, b:
If you query for{ a: 2, b: "cd" } , MongoDB must scan only one document to fulll the query. The index
and query are more selective because the values ofaare evenly distributedandthe query can select a specic document
using the index.
However, although the index onais 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, seeMeasure Index Use(page 475).
For a conceptual introduction to indexes in MongoDB seeIndex Concepts(page 436).
8.3. Indexing Tutorials 499

MongoDB Documentation, Release 2.6.4
8.4
8.4.1 mongoShell
Name Description
db.collection.createIndex()Builds an index on a collection. Usedb.collection.ensureIndex() .
db.collection.dropIndex()Removes a specied 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 existsensureIndex()
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 byindexStatswhich
reects B-tree utilization.
db.collection.indexStats()Renders a human-readable view of the data collected byindexStatswhich
reects 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
thetotalIndexSizeeld of thecollStatsoutput.
cursor.explain() Reports on the query execution plan, including index use, for a cursor.
cursor.hint() Forces MongoDB to use a specic index for a query.
cursor.max() Species an exclusive upper index bound for a cursor. For use with
cursor.hint()
cursor.min() Species an inclusive lower index bound for a cursor. For use with
cursor.hint()
cursor.snapshot() Forces the cursor to use the index on the_ideld. Ensures that the cursor returns
each document, with regards to the value of the_ideld, only once.
8.4.2
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'shaystack indexfunctionality.
geoWalk An internal command to support geospatial queries.
checkShardingIndex Internal command that validates index on shard key.
8.4.3
Name Description
$geoWithin Selects geometries within a boundingGeoJSONgeometry.
$geoIntersects Selects geometries that intersect with aGeoJSONgeometry.
$near Returns geospatial objects in proximity to a point.
$nearSphere Returns geospatial objects in proximity to a point on a sphere.
500 Chapter 8. Indexes

MongoDB Documentation, Release 2.6.4
8.4.4
Name Description
$explain Forces MongoDB to report on query execution plans. Seeexplain().
$hint Forces MongoDB to use a specic index. Seehint()
$max Species anexclusiveupper limit for the index to use in a query. Seemax().
$min Species aninclusivelower limit for the index to use in a query. Seemin().
$returnKey Forces the cursor to only return elds included in the index.
$snapshot Forces the query to use the index on the_ideld. Seesnapshot().
8.4.5
Text Search Languages(page 501)Supported languages fortext indexes(page 454) and$textquery operations.
Text Search Languages
Thetext index(page 454), the$textoperator, and thetextcommand
14
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 dened in ISO 639-1. Version 1 of text search only supported the long
form of each language name.
daordanish
nlordutch
enorenglish
fiorfinnish
frorfrench
deorgerman
huorhungarian
itoritalian
nbornorwegian
ptorportuguese
roorromanian
ruorrussian
esorspanish
svorswedish
trorturkish
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.
14
Thetextcommand is deprecated in MongoDB 2.6.
8.4. Indexing Reference 501

MongoDB Documentation, Release 2.6.4
502 Chapter 8. Indexes

CHAPTER9
Replication
Areplica setin MongoDB is a group ofmongodprocesses 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(page 503)An introduction to replica sets, their behavior, operation, and use.
Replication Concepts(page 507)The core documentation of replica set operations, congurations, architectures and
behaviors.
Replica Set Members(page 507)Introduces the components of replica sets.
Replica Set Deployment Architectures(page 516)Introduces architectural considerations related to replica
sets deployment planning.
Replica Set High Availability(page 523)Presents the details of the automatic failover and recovery process
with replica sets.
Replica Set Read and Write Semantics(page 528)Presents the semantics for targeting read and write opera-
tions to the replica set, with an awareness of location and set conguration.
Replica Set Tutorials(page 543)Tutorials for common tasks related to the use and maintenance of replica sets.
Replication Reference(page 593)Reference for functions and operations related to replica sets.
9.1
Replication is the process of synchronizing data across multiple servers.
9.1.1
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.
503

MongoDB Documentation, Release 2.6.4
9.1.2
A replica set is a group ofmongodinstances that host the same data set. Onemongod, the primary, receives all write
operations. All other instances, secondaries, apply operations from the primary so that they have the same data set.
Theprimaryaccepts all write operations from clients. Replica set can have only one primary. Because only one
member can accept write operations, replica sets providestrict consistencyfor all reads from the primary. To support
replication, the primary logs all changes to its data sets in itsoplog(page 535). Seeprimary(page 508) for more
information.
Figure 9.1: Diagram of default routing of reads and writes to the primary.
Thesecondariesreplicate the primary's oplog and apply the operations to their data sets. Secondaries' data sets reect
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 aread preferences(page 530) to send read operations to
secondaries. Reads from secondaries may return data that does not reect the state of the primary. Seesecondaries
(page 508) for more information.
You may add an extramongodinstance to a replica set as anarbiter. 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. Seearbiter(page 515) for more
information.
504 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.2: Diagram of a 3 member replica set that consists of a primary and two secondaries.Figure 9.3: Diagram of a replica set that consists of a primary, a secondary, and an arbiter.
9.1. Replication Introduction 505

MongoDB Documentation, Release 2.6.4
Anarbiterwill always be an arbiter. Aprimarymay step down and become asecondary. Asecondarymay 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.
SeeReplica Set Oplog(page 535) andReplica Set Data Synchronization(page 536) for more information. SeeRead
Preference(page 530) 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 rst secondary that receives a majority of the
votes becomes primary.
Figure 9.4: Diagram of an election of a new primary. In a three member replica set with two secondaries, the primary
becomes unreachable. The loss of a primary triggers an election where one of the secondaries becomes the new
primary
506 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
SeeReplica Set Elections(page 523) andRollbacks During Replica Set Failover(page 527) for more information.
Additional Features
Replica sets provide a number of options to support application needs. For example, you may deploy a replica set
withmembers in multiple data centers(page 522), or control the outcome of elections by adjusting thepriority
(page 596) of some members. Replica sets also support dedicated members for reporting, disaster recovery, or backup
functions.
SeePriority 0 Replica Set Members(page 512),Hidden Replica Set Members(page 513) andDelayed Replica Set
Members(page 513) for more information.
9.2
These documents describe and provide examples of replica set operation, conguration, and behavior. For an overview
of replication, seeReplication Introduction(page 503). For documentation of the administration of replica sets, see
Replica Set Tutorials(page 543). TheReplication Reference(page 593) documents commands and operations specic
to replica sets.
Replica Set Members(page 507)Introduces the components of replica sets.
Replica Set Primary(page 508)The primary is the only member of a replica set that accepts write operations.
Replica Set Secondary Members(page 508)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(page 512)Priority 0 members are secondaries that cannot become the pri-
mary.
Hidden Replica Set Members(page 513)Hidden members are secondaries that are invisible to applications.
These members support dedicated workloads, such as reporting or backup.
Replica Set Arbiter(page 515)An arbiter does not maintain a copy of the data set but participate in elections.
Replica Set Deployment Architectures(page 516)Introduces architectural considerations related to replica sets de-
ployment planning.
Replica Set High Availability(page 523)Presents the details of the automatic failover and recovery process with
replica sets.
Replica Set Elections(page 523)Elections occur when the primary becomes unavailable and the replica set
members autonomously select a new primary.
Read Preference(page 530)Applications specifyread preferenceto control how drivers direct read operations
to members of the replica set.
Replication Processes(page 535)Mechanics of the replication process and related topics.
Master Slave Replication(page 538)Master-slave replication provided redundancy in early versions of MongoDB.
Replica sets replace master-slave for most use cases.
9.2.1
Areplica setin MongoDB is a group ofmongodprocesses that provide redundancy and high availability. The
members of a replica set are:
Primary(page ??).Theprimaryreceives all write operations.
9.2. Replication Concepts 507

MongoDB Documentation, Release 2.6.4
Secondaries(page ??).Secondaries replicate operations from the primary to maintain an identical data set. Secon-
daries may have additional congurations for special usage proles. For example, secondaries may benon-
voting(page 526) orpriority 0(page 512).
You can also maintain anarbiter(page??) 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: Aprimary(page??), asecondary(page??), and anarbiter(page??).
Most deployments, however, will keep three members that store data: Aprimary(page??) and twosecondary members
(page??).
Replica Set Primary
The primary is the only member in the replica set that receives write operations. MongoDB applies write operations
on theprimaryand then records the operations on the primary'soplog(page 535).Secondary(page??) 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 opera-
tions to the primary member. SeeRead Preference(page 530) 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. SeeReplica Set Elections(page 523) 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 theprimary'sdata set. To replicate data, a secondary applies operations from the
primary'soplog(page 535) 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. SeeRead Preference
(page 530) 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 anelectionto
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.
SeeReplica Set Elections(page 523) for more details.
You can congure a secondary member for a specic purpose. You can congure a secondary to:

serve as a cold standby. SeePriority 0 Replica Set Members(page 512).

trafc. SeeHidden Replica Set Members(page 513).
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 usemaster-slave(page 538) replication. Master-slave replication lacks the automatic failover capabilities.
508 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.5: Diagram of default routing of reads and writes to the primary.
9.2. Replication Concepts 509

MongoDB Documentation, Release 2.6.4
Figure 9.6: Diagram of an election of a new primary. In a three member replica set with two secondaries, the primary
becomes unreachable. The loss of a primary triggers an election where one of the secondaries becomes the new
primary
Figure 9.7: Diagram of a 3 member replica set that consists of a primary and two secondaries.
510 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.8: Diagram of an election of a new primary. In a three member replica set with two secondaries, the primary
becomes unreachable. The loss of a primary triggers an election where one of the secondaries becomes the new
primary
9.2. Replication Concepts 511

MongoDB Documentation, Release 2.6.4

databases. SeeDelayed Replica Set Members(page 513).
Priority 0 Replica Set Members
Apriority 0member is a secondary thatcannotbecomeprimary.Priority 0members cannottrigger elections.
Otherwise these members function as normal secondaries. Apriority 0member maintains a copy of the data set,
accepts read operations, and votes in elections. Congure apriority 0member to preventsecondariesfrom 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 0member that cannot become primary.
Figure 9.9: Diagram of a 3 member replica set distributed across two data centers. Replica set includes a priority 0
member.
Priority 0 Members as StandbysApriority 0member 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 topriority 0. However, in sets with varied hardware orgeographic distribution
(page 522), apriority 0standby ensures that only qualied members become primary.
Apriority 0standby may also be valuable for some members of a set with different hardware or workload proles.
In these cases, deploy a member withpriority 0so it can't become primary. Also consider using anhidden member
(page 513) for this purpose.
If your set already has seven voting members, also congure the member asnon-voting(page 526).
Priority 0 Members and FailoverWhen conguring apriority 0member, 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.
CongurationTo congure apriority 0member, seePrevent Secondary from Becoming Primary(page 563).
512 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Hidden Replica Set Members
A hidden member maintains a copy of theprimary'sdata set but isinvisibleto client applications. Hidden members
are good for workloads with different usage patterns from the other members in thereplica set. Hidden members must
always bepriority 0 members(page 512) and socannot become primary. Thedb.isMaster()method does not
display hidden members. Hidden members, however,do voteinelections(page 523).
In the following ve-member replica set, all four secondary members have copies of the primary's data set, but one of
the secondary members is hidden.
Figure 9.10: Diagram of a 5 member replica set with a hidden priority 0 member.
Behavior
Read OperationsClients will not distribute reads with the appropriateread preference(page 530) to hidden mem-
bers. As a result, these members receive no trafc other than basic replication. Use hidden members for dedicated
tasks such as reporting and backups.Delayed members(page 513) should be hidden.
In a sharded cluster,mongosdo not interact with hidden members.
VotingHidden membersdovote in replica set elections. If you stop a hidden member, ensure that the set has an
active majority or theprimarywill step down.
For the purposes of backups, you can avoid stopping a hidden member with thedb.fsyncLock()and
db.fsyncUnlock()operations to ush all writes and lock themongodinstance for the duration of the backup
operation.
Further ReadingFor more information about backing up MongoDB databases, seeMongoDB Backup Methods
(page 172). To congure a hidden member, seeCongure a Hidden Replica Set Member(page 565).
Delayed Replica Set Members
Delayed members contain copies of areplica set'sdata set. However, a delayed member's data set reects 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.
9.2. Replication Concepts 513

MongoDB Documentation, Release 2.6.4
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
RequirementsDelayed members:
Must bepriority 0(page 512) members. Set the priority to 0 to prevent a delayed member from becoming
primary.
Should behidden(page 513) members. Always prevent applications from seeing and querying delayed mem-
bers.
dovote inelectionsfor primary.
BehaviorDelayed members apply operations from theoplogon a delay. When choosing the amount of delay,
consider that the amount of delay:

smallerthan the capacity of the oplog. For more information on oplog size, seeOplog Size(page 535).
ShardingIn sharded clusters, delayed members have limited utility when thebalanceris 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.
ExampleIn 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 alsohiddenand is a
priority 0 member.
Figure 9.11: Diagram of a 5 member replica set with a hidden delayed priority 0 member.
514 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
CongurationA delayed member has itspriority(page 596) equal to0,hidden(page 596) equal totrue,
and itsslaveDelay(page 597) equal to the number of seconds of delay:
{
"_id"num>,
"host"hostname:port>,
"priority",
"slaveDelay"seconds>,
"hidden" true
}
To congure a delayed member, seeCongure a Delayed Replica Set Member(page 566).
Replica Set Arbiter
An arbiter doesnothave a copy of data set andcannotbecome a primary. Replica sets may have arbiters to add a vote
inelections of for primary(page 523). 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 tiedelections. To add an arbiter, seeAdd an Arbiter to Replica Set(page 555).
Example
For example, in the following replica set, an arbiter allows the set to have an odd number of votes for elections:
Figure 9.12: Diagram of a four member replica set plus an arbiter for odd number of votes.
Security
AuthenticationWhen running withauthorization, arbiters exchange credentials with other members of the
set to authenticate. MongoDB encrypts the authentication process. The MongoDB authentication exchange is crypto-
graphically secure.
Arbiters usekeyfilesto authenticate to the replica set.
9.2. Replication Concepts 515

MongoDB Documentation, Release 2.6.4
CommunicationThe only communication between arbiters and other set members are: votes during elections,
heartbeats, and conguration data. These exchanges are not encrypted.
However, if your MongoDB deployment uses SSL, MongoDB will encryptallcommunication between replica set
members. SeeCongure mongod and mongos for SSL(page 304) for more information.
As with all MongoDB components, run arbiters in trusted network environments.
9.2.2
The architecture of areplica setaffects 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 re-
dundancy 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 MembersAn 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.Arbitersdo 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 ToleranceFault tolerancefor 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 notalwaysincrease 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 FunctionsAddhidden(page 513) ordelayed(page 513) mem-
bers to support dedicated functions, such as backup or reporting.
Load Balance on Read-Heavy DeploymentsIn a deployment withveryhigh read trafc, 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.
516 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Add Capacity Ahead of DemandThe 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 GeographicallyTo protect your data if your main data center fails, keep at least one member
in an alternate data center. Set these members'priority(page 596) to 0 to prevent them from becoming primary.
Keep a Majority of Members in One LocationWhen 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 conrm
a majority and elect a primary, keep a majority of the set's members in one location.
Target Operations with Tags
Usereplica set tags(page 576) to ensure that operations replicate to specic data centers. Tags also support targeting
read operations to specic machines.
See also:
Data Center Awareness(page 194) andOperational Segregation in MongoDB Deployments(page 195).
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(page 518)Three-member replica sets provide the minimum recommended architecture
for a replica set.
Replica Sets with Four or More Members(page 518)Four or more member replica sets provide greater redundancy
and can support greater distribution of read operations and dedicated functionality.
Geographically Distributed Replica Sets(page 522)Geographically distributed sets include members in multiple lo-
cations to protect against facility-specic failures, such as power outages.
9.2. Replication Concepts 517

MongoDB Documentation, Release 2.6.4
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 MembersA replica set with three members that store data has:
primary(page 508).
secondary(page 508) members. Both secondaries can become the primary in anelection(page 523).
Figure 9.13: Diagram of a 3 member replica set that consists of a primary and two secondaries.
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 andhigh availability(page 523). 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 ArbiterA three member replica set with a two members that store data has:
primary(page 508).
secondary(page 508) member. The secondary can become primary in anelection(page 523).
arbiter(page 515). 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
primaryorthe secondary is unavailable. If the primary is unavailable, the replica set will elect the secondary to be
primary.
See also:
Deploy a Replica Set(page 545).
Replica Sets with Four or More Members
Although the standard replica set conguration 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.
518 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.14: Diagram of an election of a new primary. In a three member replica set with two secondaries, the primary
becomes unreachable. The loss of a primary triggers an election where one of the secondaries becomes the new
primary
Figure 9.15: Diagram of a replica set that consists of a primary, a secondary, and an arbiter.
9.2. Replication Concepts 519

MongoDB Documentation, Release 2.6.4
Figure 9.16: Diagram of an election of a new primary. In a three member replica set with a secondary and an arbiter, the
primary becomes unreachable. The loss of a primary triggers an election where the secondary becomes new primary.
520 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
When adding members, ensure that:
evennumber of voting members, deploy an
arbiter(page??) so that the set has an odd number.
The following replica set needs an arbiter to have an odd number of voting members.
Figure 9.17: Diagram of a four member replica set plus an arbiter for odd number of votes.

2
but only 7 voting members. Seenon-voting members(page 526) for
more information.
The following 9 member replica set has 7 voting members and 2 non-voting members.
Figure 9.18: Diagram of a 9 member replica set with the maximum of 7 voting members.
failoverhavepriority 0 conguration(page 512).
For instance, some members that have limited resources or networking constraints and should never be able to
become primary. Congure members that should not become primary to havepriority 0(page 512). In following
replica set, the secondary member in the third data center has a priority of 0:
2
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 usemaster-slave(page 538) replication. Master-slave replication lacks the automatic failover capabilities.
9.2. Replication Concepts 521

MongoDB Documentation, Release 2.6.4
Figure 9.19: Diagram of a 5 member replica set distributed across three data centers. Replica set includes a priority 0
member.

See also:
Deploy a Replica Set(page 545),Add an Arbiter to Replica Set(page 555), andAdd Members to a Replica Set
(page 557).
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 apriority of 0(page 512) to prevent them from
becoming primary.
For example: the architecture of a geographically distributed replica set may be:
primaryin the main data center.
secondarymember in the main data center. This member can become primary at any time.
priority 0(page 512) member in a second data center. This member cannot become primary.
In the following replica set, the primary and one secondary are inData Center 1, whileData Center 2has apriority 0
(page 512) secondary that cannot become a primary.
If the primary is unavailable, the replica set will elect a new primary fromData Center 1. If the data centers cannot
connect to each other, the member inData Center 2will not become the primary.
IfData Center 1becomes unavailable, you can manually recover the data set fromData Center 2with minimal
downtime. With sufcientwrite concern(page 72), 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 anarbiter(page??). For more information on elections, seeReplica Set Elections(page 523).
See also:
Deploy a Geographically Redundant Replica Set(page 550).
522 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.20: Diagram of a 3 member replica set distributed across two data centers. Replica set includes a priority 0
member.
9.2.3
Replica setsprovide high availability using automaticfailover. Failover allows asecondarymember to becomepri-
maryif 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 anelection(page 523) to select a new primary. In some situations, the failover process may require a
rollback(page 527).
3
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.
Failover Processes
The replica set recovers from the loss of a primary by holding an election. Consider the following:
Replica Set Elections(page 523)Elections occur when the primary becomes unavailable and the replica set members
autonomously select a new primary.
Rollbacks During Replica Set Failover(page 527)A rollback reverts write operations on a former primary when the
member rejoins the replica set after a failover.
Replica Set Elections
Replica setsuse elections to determine which set member will becomeprimary. 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 thefailover process(page 523).
Important:Elections are essential for independent operation of a replica set; however, elections take time to com-
plete. While an election is in process, the replica set has no primary and cannot accept writes. MongoDB avoids
elections unless necessary.
3
Replica sets remove rollback data when needed without intervention. Administrators must apply or discard rollback data manually.
9.2. Replication Concepts 523

MongoDB Documentation, Release 2.6.4
In the following three-member replica set, the primary is unavailable. The remaining secondaries hold an election to
choose a new primary.
Figure 9.21: Diagram of an election of a new primary. In a three member replica set with two secondaries, the primary
becomes unreachable. The loss of a primary triggers an election where one of the secondaries becomes the new
primary
Factors and Conditions that Affect Elections
HeartbeatsReplica 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 ComparisonsThepriority(page 596) setting affects elections. Members will prefer to vote for mem-
bers with the highest priority value.
Members with a priority value of0cannot become primary and do not seek election. For details, seePriority 0 Replica
Set Members(page 512).
A replica set doesnothold 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 latestoplogentry in the set.
524 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
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.
OptimeTheoptimeis 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)optimeof any visible member in the set.
ConnectionsA 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 ofvotes, 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 asecondary
because it cannot connect to a majority of the set's members. If the remaining member is aprimaryand two members
become unavailable, the primary steps down and becomes and secondary.
Network PartitionsNetwork 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 willnotelect 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 EventsReplica sets hold an election any time there is no primary. Specically, the following:

Note:Priority 0 members(page 512), do not trigger elections, even when they cannot connect to the primary.
A primary will step down:
replSetStepDowncommand.
andhas a higher priority.

In some cases, modifying a replica set's conguration 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 preventrollbacks.
Participation in ElectionsEvery replica set member has aprioritythat helps determine its eligibility to become a
primary. In an election, the replica set elects an eligible member with the highestpriority(page 596) value as
primary. By default, all members have a priority of1and have an equal chance of becoming primary. In the default,
all members also can trigger an election.
9.2. Replication Concepts 525

MongoDB Documentation, Release 2.6.4
You can set thepriority(page 596) value to weight the election in favor of a particular member or group of
members. For example, if you have ageographically distributed replica set(page 522), you can adjust priorities so
that only members in a specic data center can become primary.
The rst member to receive the majority of votes becomes primary. By default, all members have a single vote, unless
you modify thevotes(page 597) setting.Non-voting members(page 567) havevotes(page 597) value of0. All
other members have1vote.
Note:Deprecated since version 2.6:votes(page 597) values greater than1.
Earlier versions of MongoDB allowed a member to have more than1vote by settingvotes(page 597) to a value
greater than1. Settingvotes(page 597) to value greater than1now produces a warning message.
Thestateof a member also affects its eligibility to vote. Only members in the following states can vote:PRIMARY,
SECONDARY,RECOVERING,ARBITER, andROLLBACK.
Important:Do not alter the number of votes in a replica set to control the outcome of an election. Instead, modify
thepriority(page 596) value.
Vetoes in ElectionsAll members of a replica set can veto an election, includingnon-voting members(page 526). A
member will veto an election:

election.
priority 0 member(page 512)
4
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.
optime) than the member seeking election,
from the perspective of the voting member.
optime) than the member
seeking election.
Non-Voting MembersNon-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, butcanveto(page 526) 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 avotes(page 597) setting equal to0in its member conguration:
{
"_id"num>
"host"hostname:port>,
"votes"
}
4
Remember thathidden(page 513) anddelayed(page 513) implypriority 0(page 512) conguration.
526 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.22: Diagram of a 9 member replica set with the maximum of 7 voting members.
Important:Donotalter the number of votes to control which members will become primary. Instead, modify the
priority(page 596) option.Onlyalter 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 congure a non-voting member, seeCongure Non-Voting Replica Set Member(page 567).
Rollbacks During Replica Set Failover
A rollback reverts write operations on a formerprimarywhen the member rejoins itsreplica setafter afailover.
A rollback is necessary only if the primary had accepted write operations that thesecondarieshadnotsuccessfully
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 doesnotoccur if the write operations replicate to another member of the replica set before the primary
steps downandif that member remains available and accessible to a majority of the replica set.
Collect Rollback DataWhen a rollback does occur, administrators must decide whether to apply or ignore the
rollback data. MongoDB writes the rollback data toBSONles in therollback/folder under the database's
dbPathdirectory. The names of rollback les 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. Usebsondumpto read the contents of the rollback les. Then usemongorestoreto apply the changes to
the new primary.
9.2. Replication Concepts 527

MongoDB Documentation, Release 2.6.4
Avoid Replica Set RollbacksTo prevent rollbacks, usereplica acknowledged write concern(page 75) to guarantee
that the write operations propagate to the members of a replica set.
Rollback LimitationsAmongodinstance 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 yourmongodlog:
[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 thedbPathdirectory for the member that requires a larger
rollback.
See also:
Replica Set High Availability(page 523) andReplica Set Elections(page 523).
9.2.4
From the perspective of a client application, whether a MongoDB instance is running as a single server (i.e. stan-
dalone) or areplica setis transparent.
By default, in MongoDB, read operations to a replica set return results from theprimary(page 508) and areconsistent
with the last write operation.
Users may congureread preferenceon a per-connection basis to prefer that the read operations return on thesec-
ondarymembers. If clients congure theread preferenceto permit secondary reads, read operations can return from
secondarymembers that have not replicated more recent updates or operations. When reading from a secondary, a
query may return data that reects a previous state.
This behavior is sometimes characterized aseventual consistencybecause the secondary member's state willeventually
reect the primary's state and MongoDB cannot guaranteestrict consistencyfor read operations from secondary
members.
To guarantee consistency for reads from secondary members, you can congure theclientanddriverto ensure that
write operations succeed on all members before completing successfully. SeeWrite Concern(page 72) for more
information. Additionally, such conguration can help preventRollbacks During Replica Set Failover(page 527)
during a failover.
Note:Sharded clusterswhere the shards are also replica sets provide the same operational semantics with regards to
write and read operations.
Write Concern for Replica Sets(page 528)Write concern is the guarantee an application requires from MongoDB
to consider a write operation successful.
Read Preference(page 530)Applications specifyread preferenceto control how drivers direct read operations to
members of the replica set.
Read Preference Processes(page 533)With replica sets, read operations may have additional semantics and behav-
ior.
Write Concern for Replica Sets
From the perspective of a client application, whether a MongoDB instance is running as a single server (i.e. stan-
dalone) or areplica setis transparent. However, replica sets offer some conguration options for write.
5
5
Sharded clusterswhere the shards are also replica sets provide the same conguration options with regards to write and read operations.
528 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Verify Write Operations to Replica Sets
For a replica set, the defaultwrite concern(page 72) conrms write operations only on the primary. You can, how-
ever, override this default write concern, such as to conrm write operations on a specied number of the replica set
members.
Figure 9.23: Write operation to a replica set with write concern level ofw:2or write to the primary and at least one
secondary.
To override the default write concern, specify a write concern with each write operation. For example, the following
method includes a write concern that species 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:, qty, type:
{ writeConcern::, wtimeout:
)
9.2. Replication Concepts 529

MongoDB Documentation, Release 2.6.4
You can include a timeout threshold for a write concern. This prevents write operations from blocking indenitely
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. Seewtimeout(page 119).
See also:
Write Method Acknowledgements(page 743)
Modify Default Write Concern
You can modify the default write concern for a replica set by setting thegetLastErrorDefaults (page 598)
setting in thereplica set conguration(page 594). The following sequence of commands creates a conguration that
waits for the write operation to complete on a majority of the set members before returning:
cfg
cfg.settings
cfg.settings.getLastErrorDefaults:, wtimeout:
rs.reconfig(cfg)
If you issue a write operation with a specic write concern, the write operation uses its own write concern instead of
the default.
Note:Use of insufcient write concern can lead torollbacks(page 527) in the case ofreplica set failover(page 523).
Always ensure that your operations have specied the required write concern for your application.
See also:
Write Concern(page 72) andconnections-write-concern
Custom Write Concerns
You cantag(page 576) the members of replica sets and use the tags to create custom write concerns. SeeCongure
Replica Set Tag Sets(page 576) for information on conguring custom write concerns using tag sets.
Read Preference
Read preference describes how MongoDB clients route read operations to members of areplica set.
By default, an application directs its read operations to theprimarymember in areplica set. Reading from the primary
guarantees that read operations reect 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 thanprimary(page 603) can
and willreturn stale data because the secondary queries will not include the most recent write operations to the replica
set'sprimary.
Use Cases
IndicationsThe following are common use cases for using non-primary(page 603) read preference modes:
530 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Figure 9.24: Read operations to a replica set. Default read preference routes the read to the primary. Read preference
ofnearestroutes the read to the nearest member.

Note:Read preferences aren't relevant to direct connections to a singlemongodinstance. 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 assecondary.

If you have application servers in multiple data centers, you may consider having ageographically distributed
replica set(page 522) and using a non primary read preference or thenearest(page 604). This allows the
client to read from the lowest-latency members, rather than always reading from the primary.

UseprimaryPreferred(page 603) 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-IndicationsIn general, donotusesecondary(page 603) andsecondaryPreferred (page 603) to
provide extra capacity for reads, because:

roughly the same rate as the primary.

and its replication to secondaries, reading from a secondary can return out-of-date data.
9.2. Replication Concepts 531

MongoDB Documentation, Release 2.6.4
anymembers of the set are unavailable
because the remaining members of the set will need to be able to handle all application requests.
do notinclude the shard key, secondaries may return stale results with
missing or duplicated data because of incomplete or terminated migrations.
Sharding(page 607) 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.
SeeRead Preference Processes(page 533) for more information about the internal application of read preferences.
Read Preference Modes
New in version 2.2.
Important:All read preference modes exceptprimary(page 603) may return stale data becausesecondaries
replicate operations from the primary with some delay. Ensure that your application can tolerate stale data if you
choose to use a non-primary(page 603) mode.
MongoDBdriverssupport ve read preference modes.
Read Preference
Mode
Description
primary(page 603)Default mode. All operations read from the current replica setprimary.
primaryPreferred
(page 603)
In most situations, operations read from theprimarybut if it is unavailable, operations
read fromsecondarymembers.
secondary
(page 603)
All operations read from thesecondarymembers of the replica set.
secondaryPreferred
(page 603)
In most situations, operations read fromsecondarymembers but if nosecondary
members are available, operations read from theprimary.
nearest(page 604)Operations read from member of thereplica setwith the least network latency,
irrespective of the member's type.
The syntax for specifying the read preference mode is
6
.
Read preference modes are also available to clients connecting to asharded clusterthrough amongos. Themongos
instance obeys specied read preferences when connecting to thereplica setthat provides eachshardin the cluster.
In themongoshell, thereadPref()cursor method provides access to read preferences.
For more information, seeread preference background(page 530) andread preference behavior(page 533). See also
the
7
.
Tag Sets
Tag sets allow you to target read operations to specic 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,
exceptto consider whether or not the value is unique.
You can specify tag sets with the following read preference modes:
primaryPreferred(page 603)
secondary(page 603)
6
http://api.mongodb.org/
7
http://api.mongodb.org/
532 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
secondaryPreferred (page 603)
nearest(page 604)
Tags are not compatible with modeprimary(page 603) and, in general, only apply whenselecting(page 533) a
secondarymember of a set for a read operation. However, thenearest(page 604) 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 samemember selection logic(page 533) to choose the member to which to direct read operations,
basing the choice on read preference mode and tag sets.
For information on conguring tag sets, see theCongure Replica Set Tag Sets(page 576) tutorial.
For more information on how read preferencemodes(page 603) interact with tag sets, see thedocumentation for each
read preference mode(page 602).
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 isprimary, and verifying the latency to eachmongodinstance.
Member Selection
Clients, by way of their drivers, andmongosinstances for sharded clusters, periodically update their view of the
replica set's state.
When you select non-primary(page 603) read preference, the driver will determine which member to target using
the following process:
1.
2.
3.
4.
member.
Applications can congure the threshold used in this stage. The default acceptable latency is 15 milliseconds,
which you can override in the drivers with their ownsecondaryAcceptableLatencyMS option. For
mongosyou can use the--localThresholdorlocalPingThresholdMs runtime options to set this
value.
5.
Drivers can then associate the thread or connection with the selected member. Thisrequest association(page 533) is
congurable by the application. See yourdriverdocumentation about request association conguration and default
behavior.
Request Association
Important:Request associationis congurable by the application. See yourdriverdocumentation about request
association conguration and default behavior.
9.2. Replication Concepts 533

MongoDB Documentation, Release 2.6.4
Becausesecondarymembers of areplica setmay lag behind the currentprimaryby different amounts, reads for
secondarymembers may reect data at different points in time. To prevent sequential reads from jumping around in
time, the drivercanassociate application threads to a specic member of the set after the rst read, thereby preventing
reads from other members. The thread will continue to read from the same member until:

mongodcloses
connections during afailover. This triggers aretry(page 534), which may be transparent to the application.
When using request association, if the client detects that the set has elected a newprimary, the driver will discard all
associations between threads and members.
Auto-Retry
Connections between MongoDB drivers andmongodinstances in areplica setmust balance two concerns:
1.
the replica set as much as possible. Requests should preferrequest association(page 533) (e.g.pinning).
2.
issue, networking problem, orfailoverin a replica set.
As a result, MongoDB drivers andmongos:
mongodfor as long as possible after establishing a connection to that instance.
This connection ispinnedto thismongod.
read preference modes(page 603), if the connection to
mongodis lost.
Reconnections are transparent to the application itself. If the connection permits reads fromsecondarymem-
bers, 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 reect the state of
your database at different moments.
onlyafter attempting to connect to three members of the set that match theread preference mode
(page 603) andtag set(page 532). 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 specied read preference mode. In the absence of a
specied read preference, the driver usesprimary(page 603).

8
the driver attempts to refresh the state of the replica set as quickly as
possible.
Read Preference in Sharded Clusters
Changed in version 2.2: Before version 2.2,mongosdid not support theread preference mode semantics(page 603).
In mostsharded clusters, each shard consists of areplica 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.
8
When afailoveroccurs, all members of the set close all client connections that produce a socket error in the driver. This behavior prevents or
minimizesrollback.
534 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Unlike simple replica sets, in sharded clusters, all interactions with the shards pass from the clients to themongos
instances that are actually connected to the set members.mongosis then responsible for the application of read
preferences, which is transparent to applications.
There are no conguration changes required for full support of read preference modes in sharded environments, as long
as themongosis at least version 2.2. Allmongosmaintain their own connection pool to the replica set members.
As a result:
primary(page 603), the default, unless, themongosreuses an
existing connection that has a different mode set.
To prevent confusion, always explicitly set your read preference mode.
nearest(page 604) and latency calculations reect the connection between themongosand themongod
instances, not the client and themongodinstances.
This produces the desired result, because all results must pass through themongosbefore returning to the
client.
9.2.5
Members of areplica setreplicate data continuously. First, a member usesinitial syncto capture the data set. Then the
member continuously records and applies every operation that modies the data set. Every member records operations
in itsoplog(page 535), which is acapped collection.
Replica Set Oplog(page 535)The oplog records all operations that modify the data in the replica set.
Replica Set Data Synchronization(page 536)Secondaries must replicate all changes accepted by the primary. This
process is the basis of replica set operations.
Replica Set Oplog
Theoplog(operations log) is a specialcapped collectionthat keeps a rolling record of all operations that modify the
data stored in your databases. MongoDB applies database operations on theprimaryand then records the operations
on the primary's oplog. Thesecondarymembers then copy and apply these operations in an asynchronous process.
All replica set members contain a copy of the oplog, in thelocal.oplog.rs(page 600) 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 isidempotent. For proper replication operations, entries in the oplog must be idempotent:

Oplog Size
When you start a replica set member for the rst 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 sufcient. For example, if an oplog is 5% of free disk space and lls up in 24
hours of operations, then secondaries can stop copying entries from the oplog for up to 24 hours without becoming
9.2. Replication Concepts 535

MongoDB Documentation, Release 2.6.4
too stale to continue replicating. However, most replica sets have much lower operation volumes, and their oplogs can
hold much higher numbers of operations.
Beforemongodcreates an oplog, you can specify its size with theoplogSizeMBoption. However, after you have
started a replica set member for the rst time, you can only change the size of the oplog using theChange the Size of
the Oplog(page 570) procedure.
By default, the size of the oplog is as follows:

space, but will always allocate at least 1 gigabyte and never more than 50 gigabytes.

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 sufcient.
The following workloads might require a larger oplog size.
Updates to Multiple Documents at OnceThe oplog must translate multi-updates into individual operations in order
to maintainidempotency. 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 InsertsIf you delete roughly the same amount of data as you insert,
the database will not grow signicantly in disk use, but the size of the operation log can be quite large.
Signicant Number of In-Place UpdatesIf a signicant 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, seeCheck the Size of the
Oplog(page 591).
Under various exceptional situations, updates to asecondary'soplog might lag behind the desired performance time.
Usedb.getReplicationInfo() from a secondary member and thereplication status output to assess
the current state of replication and determine if there is any unintended replication delay.
SeeReplication Lag(page 589) for more information.
Replica Set Data Synchronization
In order to maintain up-to-date copies of the shared data set, members of a replica setsyncor replicate data from other
members. MongoDB uses two forms of data synchronization:initial sync(page 537) to populate new members with
the full data set, and replication to apply ongoing changes to the entire data set.
536 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
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:
1. mongodqueries 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.
2. mongodupdates its data set to reect
the current state of the replica set.
3.
When themongodnishes building all index builds, the member can transition to a normal state, i.e.secondary.
To perform an initial sync, seeResync a Member of a Replica Set(page 575).
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 theirsync targetsif needed based on changes in the ping time and state of other members'
replication.
For a member to sync from another, thebuildIndexes(page 595) setting for both members must have the same
value/buildIndexes(page 595) must be eithertrueorfalsefor both members.
Beginning in version 2.2, secondaries avoid syncing fromdelayed members(page 513) andhidden members
(page 513).
Validity and Durability
In a replica set, only the primary can accept write operations. Writing only to the primary providesstrict consistency
among members.
Journalingprovides single-instance write durability. Without journaling, if a MongoDB instance terminates ungrace-
fully, 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 reects 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. Thispre-fetchstage minimizes the amount of time MongoDB holds the write lock while applying oplog
entries. By default, secondaries will pre-fetch allIndexes(page 431).
9.2. Replication Concepts 537

MongoDB Documentation, Release 2.6.4
Optionally, you can disable all pre-fetching or only pre-fetch the index on the_ideld. See the
secondaryIndexPrefetch setting for more information.
9.2.6
Important:Replica sets(page 507) replacemaster-slavereplication 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 pro-
duction use. Master-slave replication preceded replica sets and made it possible 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 repli-
cation provides less redundancy and does not automate failover. SeeDeploy Master-Slave Equivalent using Replica
Sets(page 540) for a replica set conguration that is equivalent to master-slave replication. If you wish to convert an
existing master-slave deployment to a replica set, seeConvert a Master-Slave Deployment to a Replica Set(page 540).
Fundamental Operations
Initial Deployment
To congure amaster-slavedeployment, start twomongodinstances: one in master mode, and the other in slave
mode.
To start amongodinstance in master mode, invokemongodas follows:
mongodmasterdbpathdata/masterdb/
With the--masteroption, themongodwill create alocal.oplog.$main(page 600) collection, which the op-
eration log that queues operations that the slaves will apply to replicate operations from the master. The--dbpath
is optional.
To start amongodinstance in slave mode, invokemongodas follows:
mongodslavesourcemasterhostname><:<port>>dbpathdata/slavedb/
Specify the hostname and port of the master instance to the--sourceargument. The--dbpathis optional.
For slave instances, MongoDB stores data about the source server in thelocal.sources(page 600) collection.
Conguration Options for Master-Slave Deployments
As an alternative to specifying the--sourcerun-time option, can add a document tolocal.sources(page 600)
specifying the master instance, as in the following operation in themongoshell:
1use local
2db.sources.find()
3db.sources.insert( { host:masterhostname>,only:>
In line 1, you switch context to thelocaldatabase. In line 2, thefind()operation should return no documents, to
ensure that there are no documents in thesourcescollection. Finally, line 3 usesdb.collection.insert()
to insert the source document into thelocal.sources(page 600) collection. The model of thelocal.sources
(page 600) document is as follows:
538 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
host
The host eld species the mastermongodinstance, and holds a resolvable hostname, i.e. IP address, or a name
from ahostle, or preferably a fully qualied domain name.
You can append<:port>to the host name if themongodis not running on the default27017port.
only
Optional. Specify a name of a database. When specied, MongoDB will only replicate the indicated database.
Operational Considerations for Replication with Master Slave Deployments
Master instances store operations in anoplogwhich is acapped collection(page 196). 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 master.
When slaves are out of sync, replication stops. Administrators must intervene manually to restart replication. Use the
resynccommand. Alternatively, the--autoresyncallows a slave to restart replication automatically, after ten
second pause, when the slave falls out of sync with the master. With--autoresyncspecied, 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 themasterinstance, by adding the
--oplogSizeoption when startingmongod. If you do not specify--oplogSize,mongodwill 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 Conguration
MongoDB provides a number of command line options formongodinstances inmaster-slavedeployments. See the
Master-Slave Replication Command Line Optionsfor options.
Diagnostics
On amasterinstance, issue the following operation in themongoshell 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 aslaveinstance, use the following operation in themongoshell 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 theserverStatusas in the following operation, to return status of the replication:
db.serverStatus()
Seeserver status repl eldsfor documentation of the relevant section of output.
9.2. Replication Concepts 539

MongoDB Documentation, Release 2.6.4
Security
When running withauthorizationenabled, inmaster-slavedeployments congure akeyFileso that slave
mongodinstances can authenticate and communicate with the mastermongodinstance.
To enable authentication and congure thekeyFileadd the following option to your conguration le:
keyFile
Note:You may chose to set these run-time conguration options using the--keyFileoption on the command line.
SettingkeyFileenables authentication and species a key le for themongodinstances to use when authenticating
to each other. The content of the key le is arbitrary but must be the same on all members of the deployment can
connect to each other.
The key le must be less one kilobyte in size and may only contain characters in the base64 set. The key le 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 le:
openssl rand -base64 741
See also:
Security(page 279) 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 conguration that resemblesmaster-slavereplication, usingreplica setsreplica sets, con-
sider the following replica conguration document. In this deployment hosts<master>and<slave>
9
provide
replication that is roughly equivalent to a two-instance master-slave deployment:
{
_id,
members
{ _id, host, priority
{ _id, host, priority, votes
]
}
SeeReplica Set Conguration(page 594) for more information about replica set congurations.
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.
1.
db.isMaster()
This should return a document that resembles the following:
9
In replica set congurations, thehost(page 595) eld must hold a resolvable hostname.
540 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
{
"ismaster",
"maxBsonObjectSize"
"maxMessageSizeBytes"
"localTime"("2013-07-08T20:15:13.664Z"),
"ok"
}
2. mongodprocesses on the master and all slave(s), using the following command while connected
to each instance:
db.adminCommand({shutdown : 1, force :})
3. /data/dbdirectories, in case you need to revert to the master-slave deployment.
4. --replSetoption, as in the following:
mongod --replSet <setname>
5. mongodwith themongoshell, 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 theconvert a standalone to a replica set(page 556) tutorial to deploy your replica set, picking up
from theExpand the Replica Set(page 557) section.
Failing over to a Slave (Promotion)
To permanently failover from a unavailable or damagedmaster(Ain the following example) to aslave(B):
1. A.
2. mongodonB.
3. localonBfrom thedbPath.
Warning:Removinglocal.*is irrevocable and cannot be undone. Perform this step with extreme
caution.
4. mongodonBwith the--masteroption.
Note:This is a one time operation, and is not reversible.Acannot become a slave ofBuntil it completes a full resync.
Inverting Master and Slave
If you have amaster(A) and aslave(B) and you would like to reverse their roles, follow this procedure. The procedure
assumesAis healthy, up-to-date and available.
IfAis not healthy but the hardware is okay (power outage, server crash, etc.), skip steps 1 and 2 and in step 8 replace
all ofA`s les withB`s les in step 8.
9.2. Replication Concepts 541

MongoDB Documentation, Release 2.6.4
IfAis not healthy and the hardware is not okay, replaceAwith a new machine. Also follow the instructions in the
previous paragraph.
To invert the master and slave in a deployment:
1. Ausing thefsynccommand.
2. Bis up to date with the state ofA.
3. B.
4. localonBfrom thedbPathto remove the existing
local.sourcesdata.
Warning:Removinglocal.*is irrevocable and cannot be undone. Perform this step with extreme
caution.
5. Bwith the--masteroption.
6. B, which primes theoplogto provide a new sync start point.
7. B.Bwill now have a new set of data les that start withlocal.
8. Aand replace all les in thedbPathofAthat start withlocalwith a copy of the les in the
dbPathofBthat begin withlocal.
Considering compressing thelocalles fromBwhile you copy them, as they may be quite large.
9. Bwith the--masteroption.
10. Awith all the usual slave options, but includefastsync.
Creating a Slave from an Existing Master's Disk Image
If you can stop write operations to themasterfor an indenite period, you can copy the data les from the master to
the newslaveand then start the slave with--fastsync.
Warning:Be careful with--fastsync. If the data on both instances isnotidentical, a discrepancy will exist
forever.
fastsyncis 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 otherslave'sdata le snapshot without any special options. Only take data snapshots when a
mongodprocess is down or locked usingdb.fsyncLock().
Resyncing a Slave that is too Stale to Recover
Slavesasynchronously apply write operations from themasterthat the slaves poll from the master'soplog. The oplog
is nite 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 themongoand issue theresynccommand:
542 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
use admin
db.runCommand( { resync:
This forces a full resync of all data (which will be very slow on a large database). You can achieve the same effect by
stoppingmongodon the slave, deleting the entire content of thedbPathon the slave, and restarting themongod.
Slave Chaining
Slavescannot be chained. They must all connect to themasterdirectly.
If a slave attempts slave from another slave you will see the following line in themongodlong of the shell:
assertion 13051 tailable cursor requested on non capped collection ns:local.oplog.$main
Correcting a Slave's Source
To change aslave'ssource, manually modify the slave'slocal.sources(page 600) collection.
Example
Consider the following: If you accidentally set an incorrect hostname for the slave'ssource, as in the following
example:
mongodslavesource prod.mississippi
You can correct this, by restarting the slave without the--slaveand--sourcearguments:
mongod
Connect to thismongodinstance using themongoshell and update thelocal.sources(page 600) collection,
with the following operation sequence:
use local
db.sources.update( { host
{ $set
Restart the slave with the correct command line arguments or with no--sourceoption. After conguring
local.sources(page 600) the rst time, the--sourcewill have no subsequent effect. Therefore, both of
the following invocations are correct:
mongodslavesource prod.mississippi.example.net
or
mongodslave
The slave now polls data from the correctmaster.
9.3
The administration ofreplica setsincludes the initial deployment of the set, adding and removing members to a set,
and conguring 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
9.3. Replica Set Tutorials 543

MongoDB Documentation, Release 2.6.4
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(page 544)Instructions for deploying replica sets, as well as adding and removing
members from an existing replica set.
Deploy a Replica Set(page 545)Congure a three-member replica set for either a production system.
Convert a Standalone to a Replica Set(page 556)Convert an existing standalonemongodinstance into a
three-member replica set.
Add Members to a Replica Set(page 557)Add a new member to an existing replica set.
Remove Members from Replica Set(page 560)Remove a member from a replica set.
Continue reading fromReplica Set Deployment Tutorials(page 544) for additional tutorials of related to setting
up replica set deployments.
Member Conguration Tutorials(page 562)Tutorials that describe the process for conguring replica set members.
Adjust Priority for Replica Set Member(page 562)Change the precedence given to a replica set members in
an election for primary.
Prevent Secondary from Becoming Primary(page 563)Make a secondary member ineligible for election as
primary.
Congure a Hidden Replica Set Member(page 565)Congure a secondary member to be invisible to appli-
cations in order to support signicantly different usage, such as a dedicated backups.
Continue reading fromMember Conguration Tutorials(page 562) for more tutorials that describe replica set
conguration.
Replica Set Maintenance Tutorials(page 570)Procedures and tasks for common operations on active replica set
deployments.
Change the Size of the Oplog(page 570)Increase the size of theoplogwhich logs operations. In most cases,
the default oplog size is sufcient.
Resync a Member of a Replica Set(page 575)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.
Change the Size of the Oplog(page 570)Increase the size of theoplogwhich logs operations. In most cases,
the default oplog size is sufcient.
Force a Member to Become Primary(page 573)Force a replica set member to become primary.
Change Hostnames in a Replica Set(page 584)Update the replica set conguration to reect changes in
members' hostnames.
Continue reading fromReplica Set Maintenance Tutorials(page 570) for descriptions of additional replica set
maintenance procedures.
Troubleshoot Replica Sets(page 588)Describes common issues and operational challenges for replica sets. For ad-
ditional diagnostic information, seeFAQ: MongoDB Diagnostics(page 720).
9.3.1
The following tutorials provide information in deploying replica sets.
See also:
Security Deployment Tutorials(page 313) for additional related tutorials.
544 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Deploy a Replica Set(page 545)Congure a three-member replica set for either a production system.
Deploy a Replica Set for Testing and Development(page 547)Congure a three-member replica set for either a de-
velopment and testing systems.
Deploy a Geographically Redundant Replica Set(page 550)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(page 555)Add an arbiter give a replica set an odd number of voting members to
prevent election ties.
Convert a Standalone to a Replica Set(page 556)Convert an existing standalonemongodinstance into a three-
member replica set.
Add Members to a Replica Set(page 557)Add a new member to an existing replica set.
Remove Members from Replica Set(page 560)Remove a member from a replica set.
Replace a Replica Set Member(page 561)Update the replica set conguration when the hostname of a member's
correspondingmongodinstance has changed.
Deploy a Replica Set
This tutorial describes how to create a three-memberreplica setfrom three existingmongodinstances.
If you wish to deploy a replica set from a single MongoDB instance, seeConvert a Standalone to a Replica Set
(page 556). For more information on replica set deployments, see theReplication(page 503) andReplica Set Deploy-
ment Architectures(page 516) documentation.
Overview
Three memberreplica setsprovide enough redundancy to survive most network partitions and other system failures.
These sets also have sufcient capacity for many distributed read operations. Replica sets should always have an odd
number of members. This ensures thatelections(page 523) will proceed smoothly. For more about designing replica
sets, seethe Replication overview(page 503).
The basic procedure is to start themongodinstances that will become members of the replica set, congure the replica
set itself, and then add themongodinstances to it.
Requirements
For production deployments, you should maintain as much separation between members as possible by hosting the
mongodinstances on separate machines. When using virtual machines for production deployments, you should place
eachmongodinstance 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 yourreplica set. If
you have not already installed MongoDB, see theinstallation tutorials(page 5).
Before creating your replica set, you should verify that your network conguration 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, seeTest Connections Between all Members(page 590).
Considerations When Deploying a Replica Set
9.3. Replica Set Tutorials 545

MongoDB Documentation, Release 2.6.4
ArchitectureIn a production, deploy each member of the replica set to its own machine and if possible bind to the
standard MongoDB port of27017. Use thebind_ipoption to ensure that MongoDB listens for connections from
applications on congured addresses.
For a geographically distributed replica sets, ensure that the majority of the set'smongodinstances reside in the
primary site.
SeeReplica Set Deployment Architectures(page 516) for more information.
ConnectivityEnsure that network trafc can pass between all members of the set and all clients in the network
securely and efciently. Consider the following:

a single site over the local area network.

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 congure your DNS names appropriately or set up your systems'/etc/hostsle to reect this conguration.
CongurationSpecify the run time conguration on each system in aconfiguration file stored in
/etc/mongodb.conf or a related location. Create the directory where MongoDB stores data les before de-
ploying MongoDB.
For more information about the run time options used above and other conguration options, see
http://docs.mongodb.org/manualreference/configuration-options .
Procedure
Step 1: Start each member of the replica set with the appropriate options.For each member, start amongodand
specify the replica set name through thereplSetoption. Specify any other parameters specic to your deployment.
For replication-specic parameters, seecli-mongod-replica-setrequired 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 species the replica set name through the--replSetcommand-line option:
mongodreplSet
The following example species the name through a conguration le:
mongodconfig $HOME/.mongodb/config
In production deployments, you can congure acontrol scriptto manage this process. Control scripts are beyond the
scope of this document.
Step 2: Open amongoshell and connect to one of the replica set members.For example, to connect to amongod
running on localhost on the default port of27017, simply issue:
mongo
546 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Step 3: Initiate the replica set.Users.initiate():
rs.initiate()
MongoDB initiates a set that consists of the current member and that uses the default replica set conguration.
Step 4: Verify the initial replica set conguration.Users.conf()to display thereplica set conguration object
(page 594):
rs.conf()
The replica set conguration object resembles the following:
{
"_id",
"version",
"members"
{
"_id",
"host"
}
]
}
Step 5: Add the remaining members to the replica set.Add the remaining members with thers.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 aprimary.
Step 6: Check the status of the replica set.Use thers.status()operation:
rs.status()
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 theDeploy a Replica Set(page 545) tutorial.
This tutorial describes how to create a three-memberreplica setfrom three existingmongodinstances.
If you wish to deploy a replica set from a single MongoDB instance, seeConvert a Standalone to a Replica Set
(page 556). For more information on replica set deployments, see theReplication(page 503) andReplica Set Deploy-
ment Architectures(page 516) documentation.
Overview
Three memberreplica setsprovide enough redundancy to survive most network partitions and other system failures.
These sets also have sufcient capacity for many distributed read operations. Replica sets should always have an odd
number of members. This ensures thatelections(page 523) will proceed smoothly. For more about designing replica
sets, seethe Replication overview(page 503).
9.3. Replica Set Tutorials 547

MongoDB Documentation, Release 2.6.4
The basic procedure is to start themongodinstances that will become members of the replica set, congure the replica
set itself, and then add themongodinstances to it.
Requirements
For test and development systems, you can run yourmongodinstances 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 yourreplica set. If
you have not already installed MongoDB, see theinstallation tutorials(page 5).
Before creating your replica set, you should verify that your network conguration 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, seeTest Connections Between all Members(page 590).
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 namedrs0.
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 threemongodinstances as members of a replica set namedrs0.
Procedure
1.
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 les.
2. mongodinstances 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 namedrs0, each running on a distinct port, and species
the path to your data directory with the--dbpathsetting. If you are already using the suggested ports, select
different ports.
The--smallfiles and--oplogSize settings reduce the disk space that eachmongod
instance uses. This is ideal for testing and development deployments as it prevents over-
loading your machine. For more information on these and other conguration options, see
http://docs.mongodb.org/manualreference/configuration-options .
548 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
3. mongodinstances through themongoshell. 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 rst one, as in
the following command;
mongo --port 27017
4. mongoshell, users.initiate()to initiate the replica set. You can create a replica set conguration
object in themongoshell environment, as in the following example:
rsconf
_id:,
members:
{
_id:,
host:
}
]
}
replacing<hostname>with your system's hostname, and then pass thersconfle tors.initiate()as
follows:
rs.initiate( rsconf )
5. replica conguration(page 594) by issuing the following command:
rs.conf()
The replica set conguration object resembles the following
{
"_id",
"version",
"members"
{
"_id",
"host"
}
]
}
6. mongoshell connected to theprimary, add the second and thirdmongodinstances to the replica set
using thers.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 aprimary.
Check the status of your replica set at any time with thers.status()operation.
See also:
The documentation of the following shell functions for more information:
rs.initiate()
rs.conf()
rs.reconfig()
rs.add()
9.3. Replica Set Tutorials 549

MongoDB Documentation, Release 2.6.4
You may also consider the
10
as an example of a basic automatically-congured replica set.
Refer toReplica Set Read and Write Semantics(page 528) 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 areplica setwith members in multiple locations. The tutorial addresses
three-member sets, four-member sets, and sets with more than four members.
For appropriate background, seeReplication(page 503) andReplica Set Deployment Architectures(page 516). For
related tutorials, seeDeploy a Replica Set(page 545) andAdd Members to a Replica Set(page 557).
Considerations
Whilereplica setsprovide 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:
voting members(page 526) are within a primary facility, Site A. This includes
priority 0 members(page 512) andarbiters(page 515). Deploy other members in secondary facilities, Site B,
Site C, etc., to provide additional copies of the data. SeeDetermine the Distribution of Members(page 517)
for more information on the voting requirements for geographically redundant replica sets.
arbiter(page 515) 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 singlearbiterin Site A.
For all congurations 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 theinstallation tutorials(page 5).
Procedures
General Considerations
10
https://github.com/mongodb/mongo-snippets/blob/master/replication/simple-setup.py
550 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
ArchitectureIn a production, deploy each member of the replica set to its own machine and if possible bind to the
standard MongoDB port of27017. Use thebind_ipoption to ensure that MongoDB listens for connections from
applications on congured addresses.
For a geographically distributed replica sets, ensure that the majority of the set'smongodinstances reside in the
primary site.
SeeReplica Set Deployment Architectures(page 516) for more information.
ConnectivityEnsure that network trafc can pass between all members of the set and all clients in the network
securely and efciently. Consider the following:

a single site over the local area network.

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 congure your DNS names appropriately or set up your systems'/etc/hostsle to reect this conguration.
CongurationSpecify the run time conguration on each system in aconfiguration file stored in
/etc/mongodb.conf or a related location. Create the directory where MongoDB stores data les before de-
ploying MongoDB.
For more information about the run time options used above and other conguration options, see
http://docs.mongodb.org/manualreference/configuration-options .
Figure 9.25: Diagram of a 3 member replica set distributed across two data centers. Replica set includes a priority 0
member.
Deploy a Geographically Redundant Three-Member Replica Set
Step 1: Start each member of the replica set with the appropriate options.For each member, start amongodand
specify the replica set name through thereplSetoption. Specify any other parameters specic to your deployment.
For replication-specic parameters, seecli-mongod-replica-setrequired by your deployment.
9.3. Replica Set Tutorials 551

MongoDB Documentation, Release 2.6.4
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 species the replica set name through the--replSetcommand-line option:
mongodreplSet
The following example species the name through a conguration le:
mongodconfig $HOME/.mongodb/config
In production deployments, you can congure acontrol scriptto manage this process. Control scripts are beyond the
scope of this document.
Step 2: Open amongoshell and connect to one of the replica set members.For example, to connect to amongod
running on localhost on the default port of27017, simply issue:
mongo
Step 3: Initiate the replica set.Users.initiate():
rs.initiate()
MongoDB initiates a set that consists of the current member and that uses the default replica set conguration.
Step 4: Verify the initial replica set conguration.Users.conf()to display thereplica set conguration object
(page 594):
rs.conf()
The replica set conguration object resembles the following:
{
"_id",
"version",
"members"
{
"_id",
"host"
}
]
}
Step 5: Add the remaining members to the replica set.Add the remaining members with thers.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 aprimary.
Step 6: Congure the outside member aspriority 0 members.Congure the member located in Site B (in this
example,mongodb2.example.net ) as apriority 0 member(page 512).
552 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
1. members(page 595) array position for the member. Keep
in mind the array position is not the same as the_id:
rs.conf()
2. cfgin the example below). Then, in the variable,
set the correct priority for the member. Then pass the variable tors.reconfig()to update the replica set
conguration.
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
cfg.members[2].priority
rs.reconfig(cfg)
Note:Thers.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 elec-
tions complete within a minute, always make sure any replica conguration changes occur during scheduled
maintenance periods.
After these commands return, you have a geographically redundant three-member replica set.
Step 7: Check the status of the replica set.Use thers.status()operation:
rs.status()
Deploy a Geographically Redundant Four-Member Replica SetA geographically redundant four-member de-
ployment has two additional considerations:
mongodb4.example.net ) must be anarbiter. This host can run on a system that is also used
for an application server or on the same machine as another MongoDB process.

replica set:
Three members in Site A, onepriority 0 member(page 512) in Site B, and an arbiter in Site A.
Two members in Site A, twopriority 0 members(page 512) 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 rst architecture is preferable because it is the least complex.
To deploy a geographically redundant four-member set:
Step 1: Start each member of the replica set with the appropriate options.For each member, start amongodand
specify the replica set name through thereplSetoption. Specify any other parameters specic to your deployment.
For replication-specic parameters, seecli-mongod-replica-setrequired 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 species the replica set name through the--replSetcommand-line option:
9.3. Replica Set Tutorials 553

MongoDB Documentation, Release 2.6.4
mongodreplSet
The following example species the name through a conguration le:
mongodconfig $HOME/.mongodb/config
In production deployments, you can congure acontrol scriptto manage this process. Control scripts are beyond the
scope of this document.
Step 2: Open amongoshell and connect to one of the replica set members.For example, to connect to amongod
running on localhost on the default port of27017, simply issue:
mongo
Step 3: Initiate the replica set.Users.initiate():
rs.initiate()
MongoDB initiates a set that consists of the current member and that uses the default replica set conguration.
Step 4: Verify the initial replica set conguration.Users.conf()to display thereplica set conguration object
(page 594):
rs.conf()
The replica set conguration object resembles the following:
{
"_id",
"version",
"members"
{
"_id",
"host"
}
]
}
Step 5: Add the remaining members to the replica set.Users.add()in amongoshell 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 aprimary.
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")
554 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Step 7: Congure outside members aspriority 0 members.Congure each member located outside of Site A (e.g.
mongodb3.example.net ) as apriority 0 member(page 512).
1. members(page 595) array position for the member. Keep
in mind the array position is not the same as the_id:
rs.conf()
2. cfgin the example below). Then, in the variable,
set the correct priority for the member. Then pass the variable tors.reconfig()to update the replica set
conguration.
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
cfg.members[2].priority
rs.reconfig(cfg)
Note:Thers.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 elec-
tions complete within a minute, always make sure any replica conguration changes occur during scheduled
maintenance periods.
After these commands return, you have a geographically redundant four-member replica set.
Step 8: Check the status of the replica set.Use thers.status()operation:
rs.status()
Deploy a Geographically Redundant Set with More than Four MembersThe 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:

the procedure for a four-member set(page 551)). Ensure that
a single facility, Site A, always has a majority of the members by deploying thearbiterin 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.
the procedure for a three-member set(page 551). Ensure that a
single facility, Site A always has a majority of the members of the set. For example, if a set has ve members,
deploy three members within Site A and two members in other facilities.
outsideof Site A and the network partitions to prevent com-
munication 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 aremongodinstances that are part of areplica setbut do not hold data. Arbiters participate inelections
(page 523) 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.
9.3. Replica Set Tutorials 555

MongoDB Documentation, Release 2.6.4
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'smongodprocess is added to the replica set, the arbiter will act
like any othermongodprocess and start up with a set of data les and with a full-sizedjournal.
To minimize the default creation of data, set the following in the arbiter'sconfiguration file:
journal.enabledtofalse
Warning:Never setjournal.enabledtofalseon a data-bearing node.
smallFilestotrue
preallocDataFilestofalse
These settings are specic to arbiters. Do not setjournal.enabledtofalseon a data-bearing node. Similarly,
do not setsmallFilesorpreallocDataFilesunless specically indicated.
Add an Arbiter
1. dbPath) for the arbiter. Themongodinstance uses the directory for conguration
data. The directorywill nothold the data set. For example, create the/data/arbdirectory:
mkdir /data/arb
2.
/data/arb dbPathfor thersreplica set:
mongod --port 30000 --dbpath /data/arb --replSet rs
3. rs.addArb()method, as in the following
example:
rs.addArb("m1.example.net:30000")
This operation adds the arbiter running on port30000on them1.example.nethost.
Convert a Standalone to a Replica Set
This tutorial describes the process for converting astandalonemongodinstance into a three-memberreplica set. Use
standalone instances for testing and development, but always use replica sets in production. To install a standalone
instance, see theinstallation tutorials(page 5).
To deploy a replica set without using a pre-existingmongodinstance, seeDeploy a Replica Set(page 545).
Procedure
1. standalonemongodinstance.
556 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
2. --replSetoption 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 namedrs0.
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 conguration options, seehttp://docs.mongodb.org/manualreference/configuration-options
and themongodmanual page.
3. mongodinstance.
4. rs.initiate()to initiate the new replica set:
rs.initiate()
The replica set is now operational.
To view the replica set conguration, users.conf(). To check the status of the replica set, use
rs.status().
Expand the Replica SetAdd additional replica set members by doing the following:
1. mongodinstances. For information on starting a standalone
instance, see theinstallation tutorial(page 5) specic to your environment.
2. mongodinstance (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 themongodinstance to add to
the set. For more information on adding a host to a replica set, seeAdd Members to a Replica Set(page 557).
Sharding ConsiderationsIf the new replica set is part of asharded cluster, change the shard host information in
thecong databaseby doing the following:
1. mongosinstances and issue a command in the following form:
db.getSiblingDB("config").shards.save( {_id:, host:
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.
2. mongosinstances. If possible, restart all components of the replica sets (i.e., allmongosand all
shardmongodinstances).
Add Members to a Replica Set
Overview
This tutorial explains how to add an additional member to an existingreplica set. For background on replication
deployment patterns, see theReplica Set Deployment Architectures(page 516) document.
9.3. Replica Set Tutorials 557

MongoDB Documentation, Release 2.6.4
Maximum Voting Members A replica set can have a maximum of sevenvoting members(page 523). To add
a member to a replica set that already has seven votes, you must either add the member as anon-voting member
(page 526) or remove a vote from anexisting member(page 597).
Control ScriptsIn production deployments you can congure acontrol scriptto manage member processes.
Existing MembersYou 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 FilesIf you have a backup or snapshot of an existing member, you can move the data les (e.g. thedbPath
directory) to a new system and use them to quickly initiate a new member. The les must be:
Backup and Restore with Filesystem
Snapshots(page 229) document for more information.
Important:Always use lesystem snapshots to create a copy of a member of the existing replica set.Do not
usemongodumpandmongorestoreto seed a new replica set member.
primary's oplog. The new member must be able to become current
by applying operations from the primary's oplog.
Requirements
1.
2.
network.
Otherwise, use the MongoDBinstallation tutorial(page 5) and theDeploy a Replica Set(page 545) tutorials.
Procedures
Prepare the Data DirectoryBefore adding a new member to an existingreplica set, prepare the new member'sdata
directoryusing one of the following strategies:
does notcontain data. The new member will copy the data from an
existing member.
If the new member is in arecoveringstate, it must exit and become asecondarybefore MongoDB can copy all
data as part of the replication process. This process takes time but does not require administrator intervention.

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 thewindow allowed
by the oplog(page 535). Otherwise, the new instance will have to perform an initial sync, which completely
resynchronizes the data, as described inResync a Member of a Replica Set(page 575).
Users.printReplicationInfo() to check the current state of replica set members with regards to the
oplog.
For background on replication deployment patterns, see theReplica Set Deployment Architectures(page 516) docu-
ment.
558 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Add a Member to an Existing Replica Set
1. mongodinstance. Specify the data directory and the replica set name. The following example
species the/srv/mongodb/db0data directory and thers0replica set:
mongod --dbpath /srv/mongodb/db0 --replSet rs0
Take note of the host name and port information for the newmongodinstance.
For more information on conguration options, see themongodmanual page.
Optional
You can specify the data directory and replica set in themongo.conf configuration file , and start the
mongodwith the following command:
mongod --config /etc/mongodb.conf
2.
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 thedb.isMaster()command.
3. 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")
4. rs.conf()method, which displays thereplica
set conguration(page 594):
rs.conf()
To view replica set status, issue thers.status()method. For a description of the status elds, see
http://docs.mongodb.org/manualreference/command/replSetGetStatus .
Congure and Add a MemberYou can add a member to a replica set by passing to thers.add()method a
members(page 595) document. The document must be in the form of alocal.system.replset.members
(page 595) document. These documents dene a replica set member in the same form as thereplica set conguration
document(page 594).
Important:Specify a value for the_ideld of themembers(page 595) document. MongoDB does not automat-
ically populate the_ideld in this case. Finally, themembers(page 595) document must declare thehostvalue.
All other elds are optional.
Example
To add a member with the following conguration:
_idof1.
hostname and port number (page 595) ofmongodb3.example.net:27017 .
priority(page 596) value within the replica set of0.
hidden(page 596),
9.3. Replica Set Tutorials 559

MongoDB Documentation, Release 2.6.4
Issue the following:
rs.add({_id:, host:, priority:, hidden: true})
Remove Members from Replica Set
To remove a member of areplica setuse either of the following procedures.
Remove a Member Usingrs.remove()
1. mongodinstance for the member you wish to remove. To shut down the instance, connect using
themongoshell and thedb.shutdownServer() method.
2. primary. To determine the current primary, usedb.isMaster()while
connected to any member of the replica set.
3. 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 briey as the replica set elects a new primary. The shell then automatically
reconnects. The shell displays aDBClientCursor::init call() failed error even though the com-
mand succeeds.
Remove a Member Usingrs.reconfig()
To remove a member you can manually edit thereplica set conguration document(page 594), as described here.
1. mongodinstance for the member you wish to remove. To shut down the instance, connect using
themongoshell and thedb.shutdownServer() method.
2. primary. To determine the current primary, usedb.isMaster()while
connected to any member of the replica set.
3. rs.conf()method to view the current conguration document and determine the position in the
membersarray of the member to remove:
Example
mongod_C.example.net is in position2of the following conguration le:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
560 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
"host"
}
]
}
4. cfg:
cfg
5. cfgobject to remove the member.
Example
To removemongod_C.example.net:27017 use the following JavaScript operation:
cfg.members.splice(2,1)
6.
rs.reconfig(cfg)
As a result ofrs.reconfig()the shell will disconnect while the replica set renegotiates which member is
primary. The shell displays aDBClientCursor::init call() failed error even though the com-
mand succeeds, and will automatically reconnected.
7. rs.conf().
For the example above the output would be:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
Replace a Replica Set Member
If you need to change the hostname of a replica set member without changing the conguration 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 thehost(page 595) eld. The value of_id(page 595)
eld will not change when you recongure the set.
SeeReplica Set Conguration(page 594) andrs.reconfig()for more information.
9.3. Replica Set Tutorials 561

MongoDB Documentation, Release 2.6.4
Note:Any replica set conguration change can trigger the currentprimaryto step down, which forces anelection
(page 523). 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 tomongo2.example.net for the replica set member congured atmembers[0], issue
the following sequence of commands:
cfg
cfg.members[0].host
rs.reconfig(cfg)
9.3.2
The following tutorials provide information in conguring replica set members to support specic operations, such as
to provide dedicated backups, to support reporting, or to act as a cold standby.
Adjust Priority for Replica Set Member(page 562)Change the precedence given to a replica set members in an elec-
tion for primary.
Prevent Secondary from Becoming Primary(page 563)Make a secondary member ineligible for election as pri-
mary.
Congure a Hidden Replica Set Member(page 565)Congure a secondary member to be invisible to applications
in order to support signicantly different usage, such as a dedicated backups.
Congure a Delayed Replica Set Member(page 566)Congure a secondary member to keep a delayed copy of the
data set in order to provide a rolling backup.
Congure Non-Voting Replica Set Member(page 567)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(page 568)Convert a secondary to an arbiter.
Adjust Priority for Replica Set Member
Overview
The priority settings of replica set members affect the outcomes ofelections(page 523) 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'spriority(page 596) setting determines the member's priority in elections. The higher
the number, the higher the priority.
Considerations
To modify priorities, you update themembers(page 595) array in the replica conguration object. The array index
begins with0. Donotconfuse this index value with the value of the replica set member's_id(page 595) eld in the
array.
The value ofpriority(page 596) can be any oating point (i.e. decimal) number between0and1000. The default
value for thepriority(page 596) eld is1.
562 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
To block a member from seeking election as primary, assign it a priority of0.Hidden members(page 513),delayed
members(page 513), andarbiters(page??) all havepriority(page 596) set to0.
Adjust priority during a scheduled maintenance window. Reconguring priority can force the current primary to step
down, leading to an election. Before an election the primary closes all openclientconnections.
Procedure
Step 1: Copy the replica set conguration to a variable.In themongoshell, users.conf()to retrieve the
replica set conguration and assign it to a variable. For example:
cfg
Step 2: Change each member's priority value.Change each member'spriority(page 596) value, as cong-
ured in themembers(page 595) array.
cfg.members[0].priority
cfg.members[1].priority
cfg.members[2].priority
This sequence of operations modies the value ofcfgto set the priority for the rst three members dened in the
members(page 595) array.
Step 3: Assign the replica set the new conguration.Users.reconfig()to apply the new conguration.
rs.reconfig(cfg)
This operation updates the conguration of the replica set using the conguration dened by the value ofcfg.
Prevent Secondary from Becoming Primary
Overview
In a replica set, by default allsecondarymembers are eligible to become primary through the election process. You
can use thepriority(page 596) 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 asecondarymember from ever becoming aprimaryin afailover, assign the secondary a priority of0, as
described here. For a detailed description of secondary-only members and their purposes, seePriority 0 Replica Set
Members(page 512).
Considerations
When updating the replica conguration object, access the replica set members in themembers(page 595) array with
thearray index. The array index begins with0. Donotconfuse this index value with the value of the_id(page 595)
eld in each document in themembers(page 595) array.
Note:MongoDB does not permit the currentprimaryto have a priority of0. To prevent the current primary from
again becoming a primary, you must rst step down the current primary usingrs.stepDown().
9.3. Replica Set Tutorials 563

MongoDB Documentation, Release 2.6.4
Procedure
This tutorial uses a sample replica set with 5 members.
Warning:
rs.reconfig()shell method can force the current primary to step down, which causes anelection
(page 523). When the primary steps down, themongodcloses all client connections. While this typically
takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

has an even number of members, add anarbiter(page 555) to ensure that members can quickly obtain a
majority of votes in an election for primary.
Step 1: Retrieve the current replica set conguration.Thers.conf()method returns areplica set congura-
tion document(page 594) that contains the current conguration for a replica set.
In amongoshell connected to a primary, run thers.conf()method and assign the result to a variable:
cfg
The returned document contains amembers(page 595) eld which contains an array of member conguration docu-
ments, one document for each member of the replica set.
Step 2: Assign priority value of0.To prevent a secondary member from becoming a primary, update the secondary
member'spriority(page 596) to0.
To assign a priority value to a member of the replica set, access the member conguration document using the array
index. In this tutorial, the secondary member to change corresponds to the conguration document found at position
2of themembers(page 595) array.
cfg.members[2].priority
The conguration change does not take effect until you recongure the replica set.
Step 3: Recongure the replica set.Users.reconfig()method to recongure the replica set with the updated
replica set conguration document.
Pass thecfgvariable to thers.reconfig()method:
rs.reconfig(cfg)
Related Documents
priority(page 596)
Adjust Priority for Replica Set Member(page 562)
Replica Set Reconguration
Replica Set Elections(page 523)
564 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Congure a Hidden Replica Set Member
Hidden members are part of areplica setbut cannot becomeprimaryand are invisible to client applications. Hidden
members do vote inelections(page 523). For a more information on hidden members and their uses, seeHidden
Replica Set Members(page 513).
Considerations
The most common use of hidden nodes is to supportdelayed members(page 513). If you only need to prevent a
member from becoming primary, congure apriority 0 member(page 512).
If thechainingAllowed(page 597) 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 thereplSetSyncFrom
database command to override the default sync target. See the documentation forreplSetSyncFrombefore using
the command.
See also:
Manage Chained Replication(page 583)
Changed in version 2.0: Forsharded clustersrunning with replica sets before 2.0, if you recongured a member as
hidden, youhadto restartmongosto prevent queries from reaching the hidden member.
Examples
Member Conguration DocumentTo congure a secondary member as hidden, set itspriority(page 596)
value to0and set itshidden(page 596) value totruein its member conguration:
{
"_id"num>
"host"hostname:port>,
"priority",
"hidden" true
}
Conguration ProcedureThe following example hides the secondary member currently at the index0in the
members(page 595) array. To congure ahidden member, use the following sequence of operations in amongo
shell connected to the primary, specifying the member to congure by its array index in themembers(page 595)
array:
cfg
cfg.members[0].priority
cfg.members[0].hidden true
rs.reconfig(cfg)
After re-conguring the set, this secondary member has a priority of0so that it cannot become primary and is hidden.
The other members in the set will not advertise the hidden member in theisMasterordb.isMaster()output.
When updating the replica conguration object, access the replica set members in themembers(page 595) array with
thearray index. The array index begins with0. Donotconfuse this index value with the value of the_id(page 595)
eld in each document in themembers(page 595) array.
9.3. Replica Set Tutorials 565

MongoDB Documentation, Release 2.6.4
Warning:
rs.reconfig()shell method can force the current primary to step down, which causes anelection
(page 523). When the primary steps down, themongodcloses all client connections. While this typically
takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

has an even number of members, add anarbiter(page 555) to ensure that members can quickly obtain a
majority of votes in an election for primary.
Related Documents
Replica Set Reconguration
Replica Set Elections(page 523)
Read Preference(page 530)
Congure a Delayed Replica Set Member
To congure a delayed secondary member, set itspriority(page 596) value to0, itshidden(page 596) value to
true, and itsslaveDelay(page 597) value to the number of seconds to delay.
Important:The length of the secondaryslaveDelay(page 597) must t within the window of the oplog. If
the oplog is shorter than theslaveDelay(page 597) window, the delayed member cannot successfully replicate
operations.
When you congure a delayed member, the delay applies both to replication and to the member'soplog. For details
on delayed members and their uses, seeDelayed Replica Set Members(page 513).
Example
The following example sets a 1-hour delay on a secondary member currently at the index0in themembers(page 595)
array. To set the delay, issue the following sequence of operations in amongoshell connected to the primary:
cfg
cfg.members[0].priority
cfg.members[0].hidden true
cfg.members[0].slaveDelay
rs.reconfig(cfg)
After the replica set recongures, the delayed secondary member cannot becomeprimaryand is hidden from appli-
cations. TheslaveDelay(page 597) value delays both replication and the member'soplogby 3600 seconds (1
hour).
When updating the replica conguration object, access the replica set members in themembers(page 595) array with
thearray index. The array index begins with0. Donotconfuse this index value with the value of the_id(page 595)
eld in each document in themembers(page 595) array.
566 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Warning:
rs.reconfig()shell method can force the current primary to step down, which causes anelection
(page 523). When the primary steps down, themongodcloses all client connections. While this typically
takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

has an even number of members, add anarbiter(page 555) to ensure that members can quickly obtain a
majority of votes in an election for primary.
Related Documents
slaveDelay(page 597)
Replica Set Reconguration
Oplog Size(page 535)
Change the Size of the Oplog(page 570) tutorial
Replica Set Elections(page 523)
Congure Non-Voting Replica Set Member
Non-voting members allow you to add additional members for read distribution beyond the maximum seven voting
members. To congure a member as non-voting, set itsvotes(page 597) value to0.
Example
To disable the ability to vote in elections for the fourth, fth, and sixth replica set members, use the following command
sequence in themongoshell connected to the primary. You identify each replica set member by its array index in the
members(page 595) array:
cfg
cfg.members[3].votes
cfg.members[4].votes
cfg.members[5].votes
rs.reconfig(cfg)
This sequence gives0votes to the fourth, fth, and sixth members of the set according to the order of themembers
(page 595) array in the output ofrs.conf(). This setting allows the set to elect these members asprimarybut 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 conguration object, access the replica set members in themembers(page 595) array with
thearray index. The array index begins with0. Donotconfuse this index value with the value of the_id(page 595)
eld in each document in themembers(page 595) array.
Warning:
rs.reconfig()shell method can force the current primary to step down, which causes anelection
(page 523). When the primary steps down, themongodcloses all client connections. While this typically
takes 10-20 seconds, try to make these changes during scheduled maintenance periods.

has an even number of members, add anarbiter(page 555) to ensure that members can quickly obtain a
majority of votes in an election for primary.
9.3. Replica Set Tutorials 567

MongoDB Documentation, Release 2.6.4
In general and when possible, all members should have only 1 vote. This prevents intermittent ties, deadlocks, or the
wrong members from becoming primary. Usepriority(page 596) to control which members are more likely to
become primary.
Related Documents
votes(page 597)
Replica Set Reconguration
Replica Set Elections(page 523)
Convert a Secondary to an Arbiter
If you have asecondaryin areplica setthat no longer needs to hold data but that needs to remain in the set to ensure that
the set canelect a primary(page 523), you may convert the secondary to anarbiter(page??) using either procedure
in this tutorial. Both procedures are operationally equivalent:

the secondary and remove its data before restarting and reconguring it as an arbiter.
For this procedure, seeConvert Secondary to Arbiter and Reuse the Port Number(page 568).

down the instance running as a secondary.
For this procedure, seeConvert Secondary to Arbiter Running on a New Port Number(page 569).
Convert Secondary to Arbiter and Reuse the Port Number
1.
don't reach the secondary.
2.
3. secondaryfrom thereplica setby calling thers.remove()method. Perform this operation while
connected to the currentprimaryin themongoshell:
rs.remove("<hostname><:port>")
4. rs.conf()method in themongo
shell:
rs.conf()
5.
mv /data/db /data/db-old
Optional
You may remove the data instead.
6. mongodinstance. You can reuse the previous
name. For example:
568 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
mkdir /data/db
7. mongodinstance 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
8. mongoshell convert the secondary to an arbiter using thers.addArb()method:
rs.addArb("<hostname><:port>")
9. rs.conf()method in themongoshell.
rs.conf()
The arbiter member should include the following:
"arbiterOnly" true
Convert Secondary to Arbiter Running on a New Port Number
1.
modify the application so that MongoDB queries don't reach the secondary.
2.
mkdir /data/db-temp
3. mongodinstance 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
4. mongoshell connected to the current primary, convert the newmongodinstance to an arbiter using the
rs.addArb()method:
rs.addArb("<hostname><:port>")
5. rs.conf()method in themongoshell.
rs.conf()
The arbiter member should include the following:
"arbiterOnly" true
6.
7. secondaryfrom thereplica setby calling thers.remove()method in themongoshell:
rs.remove("<hostname><:port>")
8. rs.conf()method in themongo
shell:
rs.conf()
9.
9.3. Replica Set Tutorials 569

MongoDB Documentation, Release 2.6.4
mv /data/db /data/db-old
Optional
You may remove the data instead.
9.3.3
The following tutorials provide information in maintaining existing replica sets.
Change the Size of the Oplog(page 570)Increase the size of theoplogwhich logs operations. In most cases, the
default oplog size is sufcient.
Perform Maintenance on Replica Set Members(page 572)Perform maintenance on a member of a replica set while
minimizing downtime.
Force a Member to Become Primary(page 573)Force a replica set member to become primary.
Resync a Member of a Replica Set(page 575)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.
Congure Replica Set Tag Sets(page 576)Assign tags to replica set members for use in targeting read and write
operations to specic members.
Recongure a Replica Set with Unavailable Members(page 580)Recongure a replica set when a majority of
replica set members are down or unreachable.
Manage Chained Replication(page 583)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(page 584)Update the replica set conguration to reect changes in members'
hostnames.
Congure a Secondary's Sync Target(page 587)Specify the member that a secondary member synchronizes from.
Change the Size of the Oplog
Theoplogexists internally as acapped collection, so you cannot modify its size in the course of normal operations. In
most cases thedefault oplog size(page 535) 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, seeOplog Size(page 535).
For details how oplog size affectsdelayed membersand affectsreplication lag, seeDelayed Replica Set Members
(page 513).
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 themongodinstance 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 nish with the maintenance on
primary member.
570 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Procedure

Tip
Always users.stepDown()to force the primary to become a secondary, before stopping the server. This
facilitates a more efcient election process.

mongodinstance as a member of the replica set.
Restart a Secondary in Standalone Mode on a Different PortShut down themongodinstance for one of the
non-primary members of your replica set. For example, to shut down, use thedb.shutdownServer() method:
db.shutdownServer()
Restart thismongodas a standalone instance running on a different port andwithoutthe--replSetparameter. 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
Recreate the Oplog with a New Size and a Seed EntrySave the last entry from the oplog. For example, connect
to the instance using themongoshell, and enter the following command to switch to thelocaldatabase:
use local
Inmongoshell scripts you can use the following operation to set thedbobject:
dblocal)
Ensure that thetemptemporary collection is empty by dropping the collection:
db.temp.drop()
Use thedb.collection.save() method and a sort on reversenatural orderto nd the last entry and save it to a
temporary collection:
db.temp.save( db.oplog.rs.find( { }, { ts:, h:1} ).limit(1).next() )
To see this oplog entry, use the following operation:
db.temp.find()
Remove the Existing Oplog CollectionDrop the oldoplog.rscollection in thelocaldatabase. Use the fol-
lowing command:
dblocal)
db.oplog.rs.drop()
This returnstruein the shell.
9.3. Replica Set Tutorials 571

MongoDB Documentation, Release 2.6.4
Create a New OplogUse thecreatecommand to create a new oplog of a different size. Specify thesize
argument in bytes. A value of2*1024*1024*1024will create a new oplog that's 2 gigabytes:
db.runCommand( { create:, capped: true, size:2 *1024*1024*1024) } )
Upon success, this command returns the following status:
{
Insert the Last Entry of the Old Oplog into the New OplogInsert the previously saved last entry from the old
oplog into the new oplog. For example:
db.oplog.rs.save( db.temp.findOne() )
To conrm the entry is in the new oplog, use the following operation:
db.oplog.rs.find()
Restart the MemberRestart themongodas a member of the replica set on its usual port. For example:
db.shutdownServer()
mongodreplSet rs0dbpathsrv/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 PrimaryRepeat 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 PrimaryTo nish the rolling maintenance operation, step down the primary
with thers.stepDown()method and repeat the oplog resizing procedure above.
Perform Maintenance on Replica Set Members
Overview
Replica setsallow 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 theprimaryis unavailable and
controlling the impact on the entire deployment.
Use these steps as the basis for common replica set operations, particularly for procedures such asupgrading to the
latest version of MongoDB(page 218) andchanging the size of the oplog(page 570).
Procedure
For each member of a replica set, starting with a secondary member, perform the following sequence of events, ending
with the primary:
mongodinstance as a standalone.

mongodinstance as a member of the replica set.
572 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Step 1: Stop a secondary.In themongoshell, shut down themongodinstance:
db.shutdownServer()
Step 2: Restart the secondary as a standalone on a different port.At the operating system shell prompt, restart
mongodas a standalone instance running on a different port andwithoutthe--replSetparameter:
mongod --port 37017 --dbpath /srv/mongodb
Step 3: Perform maintenance operations on the secondary.While the member is a standalone, use themongo
shell to perform maintenance:
mongo --port 37017
Step 4: Restartmongodas a member of the replica set.After performing all maintenance tasks, use the following
procedure to restart themongodas a member of the replica set on its usual port.
From themongoshell, shut down the standalone server after completing the maintenance:
db.shutdownServer()
Restart themongodinstance as a member of the replica set using its normal command-line arguments or conguration
le.
The secondary takes time tocatch up to the primary(page 536). From themongoshell, use the following command
to verify that the member has caught up from theRECOVERING(page 602) state to theSECONDARY(page 601) state.
rs.status()
Step 5: Perform maintenance on the primary last.To perform maintenance on the primary after completing
maintenance tasks on all secondaries, users.stepDown()in themongoshell 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 ve minutes:
rs.stepDown(300)
After the primary steps down, the replica set will elect a new primary. SeeReplica Set Elections(page 523) for more
information about replica set elections.
Force a Member to Become Primary
Synopsis
You can force areplica setmember to becomeprimaryby giving it a higherpriority(page 596) value than any
other member in the set.
Optionally, you also can force a member never to become primary by setting itspriority(page 596) value to0,
which means the member can never seekelection(page 523) as primary. For more information, seePriority 0 Replica
Set Members(page 512).
9.3. Replica Set Tutorials 573

MongoDB Documentation, Release 2.6.4
Procedures
Force a Member to be Primary by Setting its Priority HighChanged in version 2.0.
For more information on priorities, seepriority(page 596).
This procedure assumes your currentprimaryism1.example.net and that you'd like to instead make
m3.example.netprimary. The procedure also assumes you have a three-memberreplica setwith the congu-
ration below. For more information on congurations, seeReplica Set Conguration Use.
This procedure assumes this conguration:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
1. mongoshell, use the following sequence of operations to makem3.example.netthe primary:
cfg
cfg.members[0].priority
cfg.members[1].priority
cfg.members[2].priority
rs.reconfig(cfg)
This setsm3.example.netto have a higherlocal.system.replset.members[n].priority
(page 596) value than the othermongodinstances.
The following sequence of events occur:
m3.example.netandm2.example.netsync withm1.example.net(typically within 10 sec-
onds).
m1.example.netsees that it no longer has highest priority and, in most cases, steps down.
m1.example.netdoes notstep down ifm3.example.net`s sync is far behind. In that case,
m1.example.netwaits untilm3.example.netis within 10 seconds of its optime and then steps
down. This minimizes the amount of time with no primary following failover.
m3.example.netbecomes primary based on itspriority
(page 596) setting.
2. m3.example.netis more than 10 seconds behindm1.example.net`s optime, and if you
don't need to have a primary designated within 10 seconds, you can forcem1.example.netto step down by
running:
db.adminCommand({replSetStepDown:, force:})
574 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
This preventsm1.example.netfrom being primary for 86,400 seconds (24 hours), even if there is no other
member that can become primary. Whenm3.example.netcatches up withm1.example.netit will
become primary.
If you later want to makem1.example.netprimary again while it waits form3.example.netto catch
up, issue the following command to makem1.example.netseek election again:
rs.freeze()
Thers.freeze()provides a wrapper around thereplSetFreezedatabase command.
Force a Member to be Primary Using Database CommandsChanged in version 1.8.
Consider areplica setwith the following members:
mdb0.example.net- the currentprimary.
mdb1.example.net- asecondary.
mdb2.example.net- a secondary .
To force a member to become primary use the following procedure:
1. mongoshell, runrs.status()to ensure your replica set is running as expected.
2. mongoshell connected to themongodinstance running onmdb2.example.net, freeze
mdb2.example.netso that it does not attempt to become primary for 120 seconds.
rs.freeze(120)
3. mongoshell connected themongodrunning onmdb0.example.net, step down this instance that the
mongodis not eligible to become primary for 120 seconds:
rs.stepDown(120)
mdb1.example.netbecomes primary.
Note:During the transition, there is a short window where the set does not have a primary.
For more information, consider thers.freeze()andrs.stepDown() methods that wrap the
replSetFreezeandreplSetStepDowncommands.
Resync a Member of a Replica Set
Areplica setmember becomes stale when its replication process falls so far behind that theprimaryoverwrites
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 aninitial sync(page 537).
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:
mongodwith 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.
SeeProcedures(page 576).
9.3. Replica Set Tutorials 575

MongoDB Documentation, Release 2.6.4

can replace the data more quickly but requires more manual steps.
SeeSync by Copying Data Files from Another Member(page 576).
Procedures
Automatically Sync a MemberWarning:During initial sync,mongodwill remove the content of thedbPath.
This procedure relies on MongoDB's regular process forinitial sync(page 537). This will store the current data on the
member. For an overview of MongoDB initial sync process, see theReplication Processes(page 535) section.
If the instance has no data, you can simply follow theAdd Members to a Replica Set(page 557) orReplace a Replica
Set Member(page 561) procedure to add a new member to a replica set.
You can also force amongodthat is already a member of the set to to perform an initial sync by restarting the instance
without the content of thedbPathas follows:
1. mongodinstance. To ensure a clean shutdown, use thedb.shutdownServer() method
from themongoshell or on Linux systems, themongod --shutdownoption.
2. dbPath, MongoDB
will perform a complete resync. Consider making a backup rst.
At this point, themongodwill 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 trafc 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 MemberThis approach seeds a new or stale member using the data
les from an existing member of the replica set. The data lesmustbe sufciently recent to allow the new member to
catch up with theoplog. Otherwise the member would need to perform an initial sync.
Copy the Data FilesYou can capture the data les as either a snapshot or a direct copy. However, in most cases you
cannot copy data les from a runningmongodinstance to another because the data les will change during the le
copy operation.
Important:If copying data les, you must copy the content of thelocaldatabase.
Youcannotuse amongodumpbackup to for the data les,only a snapshot backup. For approaches to capture a
consistent snapshot of a runningmongodinstance, see theMongoDB Backup Methods(page 172) documentation.
Sync the MemberAfter you have copied the data les from the seed source, start themongodinstance and allow
it to apply all operations from the oplog until it reects the current state of the replica set.
Congure Replica Set Tag Sets
Tag sets let you customizewrite concernandread preferencesfor areplica set. MongoDB stores tag sets in the replica
set conguration object, which is the document returned byrs.conf(), in themembers[n].tags(page 596)
sub-document.
576 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
This section introduces the conguration of tag sets. For an overview on tag sets and their use, seeReplica Set Write
Concern(page 75) andTag Sets(page 532).
Differences Between Read Preferences and Write Concerns
Custom read preferences and write concerns evaluate tags sets in different ways:

unique.
For example, a tag set for a read operation may resemble the following document:
{:,:
To fulll such a read operation, a member would need to have both of these tags. Any of the following tag sets would
satisfy this requirement:
{:,:
{:,:,:
{:,:,:
{:,:,:}
The following tag sets wouldnotbe able to fulll this query:
{:
{:
{:,:
{:,:,:
{:,:,:
Add Tag Sets to a Replica Set
Given the following replica set conguration:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
You could add tag sets to the members of this replica set with the following command sequence in themongoshell:
9.3. Replica Set Tutorials 577

MongoDB Documentation, Release 2.6.4
conf
conf.members[0].tags:,:
conf.members[1].tags:,:
conf.members[2].tags:
rs.reconfig(conf)
After this operation the output ofrs.conf()would resemble the following:
{
"_id",
"version",
"members"
{
"_id",
"host",
"tags"
"dc":,
"use":
}
},
{
"_id",
"host",
"tags"
"dc":,
"use":
}
},
{
"_id",
"host",
"tags"
"use":
}
}
]
}
Important:In tag sets, all tag values must be strings.
Custom Multi-Datacenter Write Concerns
Given a ve member replica set with members in two data centers:
1. VAtaggeddc.va
2. GTOtaggeddc.gto
Create a custom write concern to require conrmation from two data centers using replica set tags, using the following
sequence of operations in themongoshell:
1. conf:
conf
2.
578 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
conf.members[0].tags:}
conf.members[1].tags:}
conf.members[2].tags:}
conf.members[3].tags:}
conf.members[4].tags:}
rs.reconfig(conf)
3. getLastErrorModes(page 598) setting to ensure that the write operation will propagate
to at least one member of each facility:
conf.settings::,:}}
4. confconguration object:
rs.reconfig(conf)
To ensure that a write operation propagates to at least one member of the set in both data centers, use theMultipleDC
write concern mode as follows:
db.users.insert( { id:, status:::
Alternatively, if you want to ensure that each write operation propagates to at least 2 racks in each facility, recongure
the replica set as follows in themongoshell:
1. conf:
conf
2. getLastErrorModes (page 598) value to require two different values of bothdc.vaand
dc.gto:
conf.settings::,:}}
3. confconguration 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 forwrite operations(page 737) integrates write concerns with the write
operations. Previous versions used thegetLastErrorcommand to specify the write concerns.
db.users.insert( { id:, status:::
Congure Tag Sets for Functional Segregation of Read and Write Operations
Given a replica set with tag sets that reect:

Where each member of the set has a tag set that resembles one of the following:
11
11
Since read preferences and write concerns use the value of elds in tag sets differently, larger deployments may have some redundancy.
9.3. Replica Set Tutorials 579

MongoDB Documentation, Release 2.6.4
{"dc.va":, disk:"ssd", ssd:
{"dc.va":, disk:"raid"}
{"dc.gto":, disk:"ssd", ssd:
{"dc.gto":, disk:"raid"}
{"dc.va":, disk:"ssd", ssd:
To target a read operation to a member of the replica set with a disk type ofssd, you could use the following tag set:
{ disk:
However, to create comparable write concern modes, you would specify a different set ofgetLastErrorModes
(page 598) conguration. Consider the following sequence of operations in themongoshell:
1. conf:
conf
2. getLastErrorModes(page 598) value to congure two write concern modes:
conf.settings
"getLastErrorModes"
"ssd"
"ssd"
},
"MultipleDC"
"dc.va",
"dc.gto"
}
}
}
3. confconguration object:
rs.reconfig(conf)
Now you can specify theMultipleDCwrite 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 forwrite operations(page 737) integrates write concerns with the write
operations. Previous versions used thegetLastErrorcommand to specify the write concerns.
db.users.insert( { id:, status:::
Additionally, you can specify thessdwrite concern mode to ensure that a write operation propagates to at least one
instance with an SSD.
Recongure a Replica Set with Unavailable Members
To recongure areplica setwhen aminorityof members are unavailable, use thers.reconfig()operation on
the currentprimary, following the example in theReplica Set Reconguration Procedure.
This document provides the following options for re-conguring a replica set when amajorityof members arenot
accessible:
Recongure by Forcing the Reconguration(page 581)
Recongure by Replacing the Replica Set(page 581)
You may need to use one of these procedures, for example, in a geographically distributed replica set, wherenolocal
group of members can reach a majority. SeeReplica Set Elections(page 523) for more information on this situation.
580 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Recongure by Forcing the Reconguration
Changed in version 2.0.
This procedure lets you recover while a majority ofreplica setmembers are down or unreachable. You connect to any
surviving member and use theforceoption to thers.reconfig()method.
Theforceoption forces a new conguration onto the member. Use this procedure only to recover from catastrophic
interruptions. Do not useforceevery time you recongure. Also, do not use theforceoption in any automatic
scripts and do not useforcewhen there is still aprimary.
To force reconguration:
1.
2.
for saving the conguration:
cfg
printjson(cfg)
3. members
(page 595) array by setting the array equal to the surviving members alone. Consider the following example,
which uses thecfgvariable created in the previous step:
cfg.members0] , cfg.members[4] , cfg.members[7]]
4. rs.reconfig()command with theforceoption set
totrue:
rs.reconfig(cfg, {force true})
This operation forces the secondary to use the new conguration. The conguration is then propagated to all the
surviving members listed in themembersarray. The replica set then elects a new primary.
Note:When you useforce : true, the version number in the replica set conguration increases signif-
icantly, by tens or hundreds of thousands. This is normal and designed to prevent set version collisions if you
accidentally force re-congurations on both sides of a network partition and then the network partitioning ends.
5.
possible.
Recongure by Replacing the Replica Set
Use the following procedureonlyfor versions of MongoDB prior to version 2.0. If you're running MongoDB 2.0 or
later, use the above procedure,Recongure by Forcing the Reconguration(page 581).
These procedures are for situations where amajorityof thereplica setmembers are down or unreachable. If a majority
isrunning, then skip these procedures and instead use thers.reconfig()command according to the examples in
replica-set-reconguration-usage.
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.
Recongure by Turning Off ReplicationThis option replaces thereplica setwith astandaloneserver.
9.3. Replica Set Tutorials 581

MongoDB Documentation, Release 2.6.4
1. mongodinstances. To ensure a clean shutdown, use an existingcontrol scriptor use the
db.shutdownServer() method.
For example, to use thedb.shutdownServer() method, connect to the server using themongoshell and
issue the following sequence of commands:
use admin
db.shutdownServer()
2. dbPath) of the surviving members of the set.
Optional
If you have a backup of the database you may instead remove this data.
3. mongodinstanceswithoutthe--replSetparameter.
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 inter-
ruption.
Recongure by Breaking the MirrorThis option selects a survivingreplica setmember to be the newprimary
and to seed a new replica set. In the following procedure, the new primary isdb0.example.net. MongoDB
copies the data fromdb0.example.netto all the other members.
1. mongodinstances. To ensure a clean shutdown, use an existingcontrol scriptor use the
db.shutdownServer() method.
For example, to use thedb.shutdownServer() method, connect to the server using themongoshell and
issue the following sequence of commands:
use admin
db.shutdownServer()
2. dbPath) for all the members exceptdb0.example.net, so that all the
members exceptdb0.example.nethave empty data directories. For example:
mv /data/db /data/db-old
3. localdatabase (i.e.local.*) so thatdb0.example.nethas no local database.
For example
mkdir /data/local-old
mv /data/db/local*/data/local-old/
4.
5. db0.example.netin amongoshell and runrs.initiate()to initiate the replica set.
6. rs.add(). For example, to add a member running ondb1.example.net
at port27017, issue the following command:
rs.add("db1.example.net:27017")
MongoDB performs an initial sync on the added members by copying all data fromdb0.example.netto
the added members.
See also:
Resync a Member of a Replica Set(page 575)
582 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Manage Chained Replication
Starting in version 2.0, MongoDB supports chained replication. A chained replication occurs when asecondary
member replicates from another secondary member instead of from theprimary. 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 thechainingAllowed(page 597) setting inReplica Set Conguration(page 594) 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 usereplSetSyncFromto specify that a secondary replicates
from another secondary. But that conguration will last only until the secondary recalculates which member to sync
from.
Disable Chained Replication
To disable chained replication, set thechainingAllowed(page 597) eld inReplica Set Conguration(page 594)
tofalse.
You can use the following sequence of commands to setchainingAllowed(page 597) tofalse:
1. cfgobject:
cfg
2. settingssub-document. If they do, skip
this step.
Warning:To avoid data loss, skip this step if the conguration settings contain thesettingssub-
document.
If the current conguration settingsdo notcontain thesettingssub-document, create the sub-document by
issuing the following command:
cfg.settings
3. chainingAllowed(page 597) tofalse:
cfg.settings.chainingAllowed false
rs.reconfig(cfg)
Re-enable Chained Replication
To re-enable chained replication, setchainingAllowed(page 597) totrue. You can use the following sequence
of commands:
cfg
cfg.settings.chainingAllowed true
rs.reconfig(cfg)
9.3. Replica Set Tutorials 583

MongoDB Documentation, Release 2.6.4
Change Hostnames in a Replica Set
For mostreplica sets, the hostnames in thehost(page 595) eld 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 thehost(page 595) eld in the replica set conguration to
avoid confusion and complexity.
Overview
This document provides two separate procedures for changing the hostnames in thehost(page 595) eld. Use either
of the following approaches:
Change hostnames without disrupting availability(page 585). 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 rst procedure, you must congure your applications to connect to the replica set at both the old
and new locations, which often requires a restart and reconguration at the application layer and which may
affect the availability of your applications. Re-conguring applications is beyond the scope of this document.
Stop all members running on the old hostnames at once(page 586). This approach has a shorter maintenance
window, but the replica set will be unavailable during the operation.
See also:
Replica Set Reconguration Process,Deploy a Replica Set(page 545), andAdd Members to a Replica Set(page 557).
Assumptions
Given areplica setwith three members:
database0.example.com:27017 (theprimary)
database1.example.com:27017
database2.example.com:27017
And with the followingrs.conf()output:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
584 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
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 aboveassumptions(page 584).
1. secondaryin the replica set, perform the following sequence of operations:
(a)
(b)
(c) mongoshell connected to the replica set's primary. In our example, the primary runs on port
27017so you would issue the following command:
mongo --port 27017
(d) rs.reconfig()to update thereplica set conguration document(page 594) with the new host-
name.
For example, the following sequence of commands updates the hostname for the secondary at the array
index1of themembersarray (i.e.members[1]) in the replica set conguration document:
cfg
cfg.members[1].host
rs.reconfig(cfg)
For more information on updating the conguration document, seereplica-set-reconguration-usage.
(e)
a chance to catch up with the other members of the set.
Repeat the above steps for each non-primary member of the set.
2. mongoshell connected to the primary and step down the primary using thers.stepDown()method:
rs.stepDown()
The replica set elects another member to the become primary.
3.
4. mongodinstance that will become the new primary in the new location.
5. replica set conguration document
(page 594) with the hostname of the node that is to become the new primary.
For example, if the old primary was at position 0and the new primary's hostname is
mongodb0.example.net:27017 , you would run:
cfg
cfg.members[0].host
rs.reconfig(cfg)
6. mongoshell connected to the new primary.
9.3. Replica Set Tutorials 585

MongoDB Documentation, Release 2.6.4
7. rs.conf()in themongoshell.
Your output should resemble:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
Change All Hostnames at the Same Time
This procedure uses the aboveassumptions(page 584).
1. replica set.
2. on a different portandwithoutusing the--replSetrun-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
3.
(a) mongoshell connected to themongodrunning on the new, temporary port. For example, for a
member running on a temporary port of37017, you would issue this command:
mongo --port 37017
(b)
system.replsetcollection in thelocaldatabase. Edit the replica set conguration 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:
cfg.members[0].host
cfg.members[1].host
cfg.members[2].host
db.system.replset.update( {:
586 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
(c) mongodprocess on the member.
4. mongodinstance in the normal way: use the usual port
number and use the--replSetoption. For example:
mongod --dbpath /data/db1/ --port 27017 --replSet rs
5. mongodinstances using themongoshell. For example:
mongo --port 27017
6. rs.conf()in themongoshell.
Your output should resemble:
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host"
}
]
}
Congure 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. SeeReplica Set Data Synchronization(page 536)
andManage Chained Replication(page 583) 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 congure asecondarymember's sync target to
temporarily pulloplogentries. The following provide access to this functionality:
replSetSyncFromcommand, or
rs.syncFrom()helper in themongoshell
Considerations
Sync LogicOnly 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, runrs.syncFrom()
operationbeforeinitial sync.
9.3. Replica Set Tutorials 587

MongoDB Documentation, Release 2.6.4
If you runrs.syncFrom()during initial sync, MongoDB produces no error messages, but the sync target will not
change until after the initial sync operation.
PersistencereplSetSyncFrom andrs.syncFrom()provide a temporary override of default behavior.
mongodwill revert to the default sync behavior in the following situations:
mongodinstance restarts.
mongodand 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
mongodwill revert to the default sync target.
TargetThe member to sync from must be a valid source for data in the set. To sync from a member, the member
must:

buildIndexes(page 595) setting.

If you attempt to replicate from a member that is more than 10 seconds behind the current member,mongodwill log
a warning but will still replicate from the lagging member.
If you runreplSetSyncFromduring initial sync, MongoDB produces no error messages, but the sync target will
not change until after the initial sync operation.
Procedure
To use thereplSetSyncFromcommand in themongoshell:
db.adminCommand( { replSetSyncFrom:
To use thers.syncFrom()helper in themongoshell:
rs.syncFrom("hostname<:port>");
9.3.4
This section describes common strategies for troubleshootingreplica setdeployments.
Check Replica Set Status
To display the current state of the replica set and current state of each member, run thers.status()method in a
mongoshell connected to the replica set'sprimary. For descriptions of the information displayed byrs.status(),
seehttp://docs.mongodb.org/manualreference/command/replSetGetStatus .
Note:Thers.status()method is a wrapper that runs thereplSetGetStatusdatabase command.
588 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Check the Replication Lag
Replication lag is a delay between an operation on theprimaryand the application of that operation from theoplogto
thesecondary. Replication lag can be a signicant issue and can seriously affect MongoDBreplica setdeployments.
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:
mongoshell connected to the primary, call thers.printSlaveReplicationInfo() method.
Returns thesyncedTovalue 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
Adelayed member(page 513) may show as0seconds behind the primary when the inactivity period on the
primary is greater than theslaveDelay(page 597) value.
Note:Thers.status()method is a wrapper around thereplSetGetStatusdatabase command.

Service
12
. For more information see the
13
.
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 includingpingto test latency between set members andtracerouteto expose the routing of
packets network endpoints.
Disk Throughput
If the le system and disk device on the secondary is unable to ush data to disk as quickly as the primary, then
the secondary will have difculty 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, includingiostatorvmstat.
Concurrency
In some cases, long-running operations on the primary can block replication on secondaries. For best results,
congurewrite concern(page 72) to require conrmation of replication to secondaries, as described inreplica
set write concern(page 75). This prevents write operations from returning if replication cannot keep up with
the write load.
Use thedatabase prolerto see if there are slow queries or long-running operations that correspond to the
incidences of lag.
12
http://mms.mongodb.com/
13
http://mms.mongodb.com/help/
9.3. Replica Set Tutorials 589

MongoDB Documentation, Release 2.6.4
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 withunacknowledged write concern(page 73), the secondaries will not be able to read the
oplog fast enough to keep up with changes.
To prevent this, requirewrite acknowledgment or journaled write concern(page 72) 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(page 75)
Replica Set Write Concern(page 77)
Oplog Size(page 535)
Test Connections Between all Members
All members of areplica setmust be able to connect to every other member of the set to support replication. Al-
ways verify connections in both directions. Networking topologies and rewall congurations 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
1. 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
2. m2.example.netto 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 betweenm2.example.netandm1.example.netin both directions.
3. m3.example.netto the other two hosts with the following operation set from the
m3.example.nethost, 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 rewall conguration and recongure your envi-
ronment to allow these connections.
590 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
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(page 597) are available.
When a set's active members can no longer form a majority, the set'sprimarysteps down and becomes asecondary.
The former primary closes all open connections to client applications. Clients attempting to write to the former primary
receive socket exceptions andConnection reseterrors 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, seeReplica Set Elections(page 523). For related information on connection errors,
seeDoes TCP keepalive time affect sharded clusters and replica sets?(page 720).
Check the Size of the Oplog
A largeroplogcan give a replica set a greater tolerance for lag, and make the set more resilient.
To check the size of the oplog for a givenreplica setmember, connect to the member in amongoshell 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 t about 26 hours (94400 seconds) of operations:
configured oplog size:MB
log length start to end:26.22hrs)
oplog first event time::50:38-0400
oplog last event time::59:10-0400
now::00:21-0400
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(page 535),
Delayed Replica Set Members(page 513), and
Check the Replication Lag(page 589).
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 theChange the Size of the Oplog(page 570) tutorial.
Oplog Entry Timestamp Error
Consider the following error inmongodoutput and logs:
replSet error fatal couldnt query the local local.oplog.rs collection. Terminating mongod after 30 seconds.
<timestamp> [rsStart] bad replSet oplog entry?
9.3. Replica Set Tutorials 591

MongoDB Documentation, Release 2.6.4
Often, an incorrectly typed value in thetseld in the lastoplogentry causes this error. The correct data type is
Timestamp.
Check the type of thetsvalue using the following two queries against the oplog collection:
db"local")
db.oplog.rs.find().sort({$natural:-1}).limit(1)
db.oplog.rs.find({ts:{$type:17}}).sort({$natural:-1}).limit(1)
The rst query returns the last document in the oplog, while the second returns the last document in the oplog where
thetsvalue is a Timestamp. The$typeoperator allows you to selectBSON type17, 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 thets
eld.
Example
If the rst query returns this as the last oplog entry:
{:, i:},
"h""8191276672478122996"),
"op",
"ns",
"o",
And the second query returns this as the last entry wheretshas theTimestamptype:
{1347982454000,),
"h""6188469075153256465"),
"op",
"ns",
"o",
Then the value for thetseld 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::1347982456000, i:1
{ $set:: newTimestamp(1347982456000,)}})
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 onlocal.slaves
Theduplicate key on local.slaveserror, occurs when asecondaryorslavechanges its hostname and theprimaryor
mastertries to update itslocal.slavescollection with the new name. The update fails because it contains the
same_idvalue 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 thesecondaryorslave.
To prevent the error from appearing, drop thelocal.slavescollection from theprimaryormaster, with the
following sequence of operations in themongoshell:
use local
db.slaves.drop()
592 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
The next time asecondaryorslavepolls theprimaryormaster, theprimaryormasterrecreates thelocal.slaves
collection.
9.4
9.4.1 mongoShell
Name Description
rs.add() Adds a member to a replica set.
rs.addArb() Adds anarbiterto a replica set.
rs.conf() Returns the replica set conguration document.
rs.freeze() Prevents the current member from seeking election as primary for a period of time.
rs.help() Returns basic help text forreplica setfunctions.
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-congures a replica set by applying a new replica set conguration object.
rs.remove() Remove a member from a replica set.
rs.slaveOk() Sets theslaveOkproperty for the current connection. Deprecated. Use
readPref()andMongo.setReadPref() to setread preference.
rs.status() Returns a document with information about the state of the replica set.
rs.stepDown() Causes the currentprimaryto become a secondary which forces anelection.
rs.syncFrom() Sets the member that this replica set member will sync from, overriding the default
sync target selection logic.
9.4.2
Name Description
applyOps Internal command that appliesoplogentries to the current data set.
getoptime Internal command to support replication, returns the optime.
isMaster Displays information about this member's role in the replica set, including whether it is
the master.
replSetFreeze Prevents the current member from seeking election asprimaryfor a period of time.
replSetGetStatus Returns a document that reports on the status of the replica set.
replSetInitiate Initializes a new replica set.
replSetMaintenanceEnables or disables a maintenance mode, which puts asecondarynode in a
RECOVERINGstate.
replSetReconfig Applies a new conguration to an existing replica set.
replSetStepDown Forces the currentprimarytostep downand become asecondary, forcing an election.
replSetSyncFrom Explicitly override the default logic for selecting a member to replicate from.
resync Forces amongodto re-synchronize from themaster. For master-slave replication only.
9.4.3
Replica Set Conguration(page 594)Complete documentation of thereplica setconguration object returned by
rs.conf().
The local Database(page 598)Complete documentation of the content of thelocaldatabase thatmongodin-
stances use to support replication.
Replica Set Member States(page 600)Reference for the replica set member states.
9.4. Replication Reference 593

MongoDB Documentation, Release 2.6.4
Read Preference Reference(page 602)Complete documentation of the ve read preference modes that the Mon-
goDB drivers support.
Replica Set Conguration
The conguration for a replica set is stored as a document in thesystem.replset(page 600) collection in the
local database(page 598).
Replica Set Conguration Document
The following document provides a representation of a replica set conguration document. The conguration 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>
}
}
Conguration 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
replSetNameor--replSetfor information on setting the replica set name.
local.system.replset. version
An incrementing number used to distinguish revisions of the replica set conguration object from previous
iterations of the conguration.
594 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
replset.members
local.system.replset. members
Type: array
An array of member conguration documents, one for each member of the replica set. Themembers(page 595)
array is a zero-indexed array.
Each member-specic conguration document can contain the following elds:
local.system.replset.members[n]. _id
Type: integer
A numeric identier of every member in the replica set. Once set, you cannot change the_id(page 595)
of a member.
Note:When updating the replica conguration object, access the replica set members in themembers
(page 595) array with thearray index. The array index begins with0. Donotconfuse this index value
with the value of the_id(page 595) eld in each document in themembers(page 595) array.
local.system.replset.members[n]. host
Type: string
The hostname and, if specied, the port number, of the set member.
The hostname name must be resolvable for every host in the replica set.
Warning:host(page 595) cannot hold a value that resolves tolocalhostor the local interface
unlessallmembers of the set are on hosts that resolve tolocalhost.
local.system.replset.members[n]. arbiterOnly
Optional.
Type: boolean
Default: false
A boolean that identies an arbiter. A value oftrueindicates that the member is an arbiter.
When using thers.addArb()method to add an arbiter, the method automatically setsarbiterOnly
(page 595) totruefor the added member.
local.system.replset.members[n]. buildIndexes
Optional.
Type: boolean
Default: true
A boolean that indicates whether themongodbuildsindexeson this member. You can only set this value
when adding a member to a replica set. You cannot changebuildIndexes(page 595) eld after the
member has been added to the set. To add a member, seers.add()andrs.reconfig().
Do not set tofalseformongodinstances that receive queries from clients.
SettingbuildIndexestofalsemay be useful ifallthe following conditions are true:
you are only using this instance to perform backups usingmongodump,and
this member will receive no queries,and
index creation and maintenance overburdens the host system.
9.4. Replication Reference 595

MongoDB Documentation, Release 2.6.4
Even if set tofalse, secondarieswillbuild indexes on the_ideld in order to facilitate operations
required for replication.
Warning:If you setbuildIndexes(page 595) tofalse, you must also setpriority
(page 596) to0. Ifpriority(page 596) is not0, MongoDB will return an error when attempt-
ing to add a member withbuildIndexes(page 595) equal tofalse.
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 wherebuildIndexes(page 595) is false.
local.system.replset.members[n]. hidden
Optional.
Type: boolean
Default: false
When this value istrue, the replica set hides this instance and does not include the member in the output
ofdb.isMaster()orisMaster. This prevents read operations (i.e. queries) from ever reaching this
host by way of secondaryread preference.
See also:
Hidden Replica Set Members(page 513)
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 aprimary.
Specify higher values to make a membermoreeligible to becomeprimary, and lower values to make the
memberlesseligible. 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.
Apriority(page 596) of0makes it impossible for a member to become primary.
See also:
Replica Set Elections(page 523).
local.system.replset.members[n]. tags
Optional.
Type: document
Default: none
A document that contains arbitrary eld and value pairs for describing ortaggingmembers in order to
extendwrite concern(page 118) andread preference(page 602) and thereby allowing congurable data
center awareness.
Usetagsto congure write concerns in conjunction withgetLastErrorModes (page 598) and
getLastErrorDefaults (page 598).
Important:In tag sets, all tag values must be strings.
596 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
For more information on conguring tag sets for read preference and write concern, seeCongure Replica
Set Tag Sets(page 576).
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 createdelayed members(page 513). Delayed members maintain a copy of the data that
reects the state of the data at some time in the past.
See also:
Delayed Replica Set Members(page 513)
local.system.replset.members[n]. votes
Optional.
Type: integer
Default: 1
The number of votes a server will cast in areplica set election(page 523). The number of votes each
member has can be either1or0.
A replica set can have up to 12 members, but can have at most only 7votingmembers. If you need more
than 7 members in one replica set, setvotes(page 597) to0for the additional non-voting members.
Note:Deprecated since version 2.6:votes(page 597) values greater than1.
Earlier versions of MongoDB allowed a member to have more than1vote by settingvotes(page 597)
to a value greater than1. Settingvotes(page 597) to value greater than1now produces a warning
message.
replset.settings
local.system.replset. settings
Optional.
Type: document
A document that contains conguration options that apply to the whole replica set.
Thesettings(page 597) document contain the following elds:
local.system.replset.settings. chainingAllowed
New in version 2.2.4.
Optional.
Type: boolean
Default: true
WhenchainingAllowed(page 597) istrue, the replica set allowssecondarymembers to replicate
from other secondary members. WhenchainingAllowed(page 597) isfalse, secondaries can repli-
cate only from theprimary.
When you runrs.conf()to view a replica set's conguration, thechainingAllowed(page 597)
eld appears only when set tofalse. If not set,chainingAllowed(page 597) istrue.
9.4. Replication Reference 597

MongoDB Documentation, Release 2.6.4
See also:
Manage Chained Replication(page 583)
local.system.replset.settings. getLastErrorDefaults
Optional.
Type: document
A document that species thewrite concern(page 528) for the replica set. The replica set will use this
write concern only whenwrite operations(page 743) orgetLastErrorspecify no other write concern.
IfgetLastErrorDefaults (page 598) is not set, the default write concern for the replica set only
requires conrmation from the primary.
local.system.replset.settings. getLastErrorModes
Optional.
Type: document
A document used to dene an extendedwrite concernthrough the use oftags(page 596). The extended
write concerncan providedata-center awareness.
For example, the following document denes an extended write concern namedeastCoastand asso-
ciates with a write to a member that has theeasttag.
{ getLastErrorModes: { eastCoast: { "east": 1 } } }
Write operations to the replica set can use the extended write concern, e.g.{ w: "eastCoast" } .
SeeCongure Replica Set Tag Sets(page 576) 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 Conguration
To view the current conguration for a replica set, use thers.conf()method. Seers.conf()for more informa-
tion.
Modify Replica Set Conguration
To modify the conguration for a replica set, use thers.reconfig()method, passing a conguration document to
the method. Seers.reconfig()for more information.
ThelocalDatabase
Overview
Everymongodinstance has its ownlocaldatabase, which stores data used in the replication process, and other
instance-specic data. Thelocaldatabase is invisible to replication: collections in thelocaldatabase are not
replicated.
598 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
In replication, thelocaldatabase store stores internal replication data for each member of areplica set. Thelocal
stores the following collections:
Changed in version 2.4: When running with authentication (i.e.authorization), authenticating to thelocal
database isnotequivalent to authenticating to theadmindatabase. In previous versions, authenticating to thelocal
database provided access to all databases.
Collection on allmongodInstances
local.startup_log
On startup, eachmongodinstance inserts a document intostartup_log(page 599) with diagnostic informa-
tion about themongodinstance itself and host information.startup_log(page 599) is a capped collection.
This information is primarily useful for diagnostic purposes.
Example
Consider the following prototype of a document from thestartup_log(page 599) collection:
{
"_id",
"hostname",
"startTime""<date>"),
"startTimeLocal",
"cmdLine"
"dbpath",
"<option>"value>
},
"pid"number>,
"buildinfo"
"version",
"gitVersion",
"sysInfo",
"loaderFlags",
"compilerFlags",
"allocator",
"versionArray"num>,num>,...>
"javascriptEngine",
"bits"number>,
"debug" boolean>,
"maxBsonObjectSize"number>
}
}
Documents in thestartup_log(page 599) collection contain the following elds:
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 UTCISODatevalue that reects when the server started.
local.startup_log.startTimeLocal
A string that reports thestartTime(page 599) in the system's local time zone.
local.startup_log.cmdLine
A sub-document that reports themongodruntime options and their values.
9.4. Replication Reference 599

MongoDB Documentation, Release 2.6.4
local.startup_log.pid
The process identier for this process.
local.startup_log.buildinfo
A sub-document that reports information about the build environment and settings used to compile this
mongod. This is the same output asbuildInfo. SeebuildInfo.
Collections on Replica Set Members
local.system.replset
local.system.replset (page 600) holds the replica set's conguration object as its single document. To
view the object's conguration information, issuers.conf()from themongoshell. You can also query this
collection directly.
local.oplog.rs
local.oplog.rs(page 600) is the capped collection that holds theoplog. You set its size at creation using
theoplogSizeMBsetting. To resize the oplog after replica set initiation, use theChange the Size of the Oplog
(page 570) procedure. For additional information, see theOplog Size(page 535) 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
Inmaster/slavereplication, thelocaldatabase contains the following collections:

local.oplog.$main
This is the oplog for the master-slave conguration.
local.slaves
This contains information about each slave.

local.sources
This contains information about the slave's master server.
Replica Set Member States
Members of replica sets have states that reect the startup process, basic operations, and potential error states.
600 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Num-
ber
Name State Description
0 STARTUP
(page 601)
Cannot vote. All members start up in this state. Themongodparses thereplica set
conguration document(page 562) while inSTARTUP(page 601).
1 PRIMARY
(page 601)
Can vote. Theprimary(page 508) is the only member to accept write operations.
2 SECONDARY
(page 601)
Can vote. Thesecondary(page 508) replicates the data store.
3 RECOVERING
(page 602)
Can vote. Members either perform startup self-checks, or transition from completing a
rollback(page 527) orresync(page 575).
4 FATAL
(page 602)
Cannot vote. Has encountered an unrecoverable error.
5 STARTUP2
(page 601)
Cannot vote. Forks replication and election threads before becoming a secondary.
6 UNKNOWN
(page 602)
Cannot vote. Has never connected to the replica set.
7 ARBITER
(page 601)
Can vote.Arbiters(page??) do not replicate data and exist solely to participate in
elections.
8 DOWN
(page 602)
Cannot vote. Is not accessible to the set.
9 ROLLBACK
(page 602)
Can vote. Performs arollback(page 527).
10 REMOVED
(page 602)
Cannot vote. Was once in the replica set but has now been removed.
States
Core States
PRIMARY
Members inPRIMARY(page 601) state accept write operations. A replica set has only one primary at a time.
ASECONDARY(page 601) member becomes primary after anelection(page 523). Members in thePRIMARY
(page 601) state are eligible to vote.
SECONDARY
Members inSECONDARY(page 601) state replicate the primary's data set and can be congured to accept read
operations. Secondaries are eligible to vote in elections, and may be elected to thePRIMARY(page 601) state if
the primary becomes unavailable.
ARBITER
Members inARBITER(page 601) 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 theARBITER
(page 601) state if the set would otherwise have an even number of members, and could suffer from tied elec-
tions. Like primaries, there should only be at most one arbiter in any replica set.
SeeReplica Set Members(page 507) for more information on core states.
Initialization States
STARTUP
Each member of a replica set starts up inSTARTUP(page 601) state.mongodthen loads that member's
replica set conguration, and transitions the member's state toSTARTUP2(page 601). Members inSTARTUP
(page 601) are not eligible to vote.
STARTUP2
Each member of a replica set enters theSTARTUP2(page 601) state as soon asmongodnishes loading
that member's conguration. While in theSTARTUP2(page 601) state, the member creates threads to handle
9.4. Replication Reference 601

MongoDB Documentation, Release 2.6.4
internal replication operations. Members are in theSTARTUP2(page 601) state for a short period of time before
entering theRECOVERING(page 602) state. Members in theSTARTUP2(page 601) state are not eligible to
vote.
RECOVERING
A member of a replica set entersRECOVERING(page 602) state when it is not ready to accept reads. The
RECOVERING(page 602) state can occur during normal operation, and doesn't necessarily reect an error
condition. Members in theRECOVERING(page 602) state are eligible to vote in elections, but is not eligible to
enter thePRIMARY(page 601) state.
During startup, members transition throughRECOVERING(page 602) afterSTARTUP2(page 601) and before
becomingSECONDARY(page 601).
During normal operation, if asecondaryfalls behind the other members of the replica set, it may need toresync
(page 575) with the rest of the set. While resyncing, the member enters theRECOVERING(page 602) state.
Whenever the replica set replaces aprimaryin an election, the old primary's data collection may contain doc-
uments that did not have time to replicate to thesecondarymembers. In this case the member rolls back those
writes. Duringrollback(page 527), the member will haveRECOVERING(page 602) state.
On secondaries, thecompactandreplSetMaintenance commands force the secondary to enter
RECOVERING(page 602) state. This prevents clients from reading during those operations.
Error StatesMembers in any error state can't vote.
FATAL
Members that encounter an unrecoverable error enter theFATAL(page 602) state. Members in this state requires
administrator intervention.
UNKNOWN
Members that have never communicated status information to the replica set are in theUNKNOWN(page 602)
state.
DOWN
Members that lose their connection to the replica set enter theDOWN(page 602) state.
REMOVED
Members that are removed from the replica set enter theREMOVED(page 602) state. When members enter the
REMOVED(page 602) state, the logs will mark this event with areplSet REMOVEDmessage entry.
ROLLBACK
When aSECONDARY(page 601) rolls back a write operation after transitioning fromPRIMARY(page 601), it
enters theROLLBACK(page 602) state. SeeRollbacks During Replica Set Failover(page 527).
Read Preference Reference
Read preference describes how MongoDB clients route read operations to members of areplica set.
By default, an application directs its read operations to theprimarymember in areplica set. Reading from the primary
guarantees that read operations reect 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.
602 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
Read Preference
Mode
Description
primary(page 603)Default mode. All operations read from the current replica setprimary.
primaryPreferred
(page 603)
In most situations, operations read from theprimarybut if it is unavailable, operations
read fromsecondarymembers.
secondary
(page 603)
All operations read from thesecondarymembers of the replica set.
secondaryPreferred
(page 603)
In most situations, operations read fromsecondarymembers but if nosecondary
members are available, operations read from theprimary.
nearest(page 604)Operations read from member of thereplica setwith the least network latency,
irrespective of the member's type.
Read Preference Modes
primary
All read operations use only the current replica setprimary. This is the default. If the primary is unavailable,
read operations produce an error or throw an exception.
Theprimary(page 603) read preference mode is not compatible with read preference modes that usetag sets
(page 532). If you specify a tag set withprimary(page 603), the driver will produce an error.
primaryPreferred
In most situations, operations read from theprimarymember of the set. However, if the primary is unavailable,
as is the case duringfailoversituations, operations read from secondary members.
When the read preference includes atag set(page 532), the client reads rst from the primary, if available, and
then fromsecondariesthat match the specied 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 theprimaryPreferred
(page 603) mode may return stale data in some situations.
Warning:Changed in version 2.2:mongosadded full support for read preferences.
When connecting to amongosinstance older than 2.2, using a client that supports read preference modes,
primaryPreferred(page 603) will send queries to secondaries.
secondary
Operations readonlyfrom thesecondarymembers 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 anarbitermay not have any secondaries if a member is in
recovering state or unavailable.
When the read preference includes atag set(page 532), the client attempts to nd secondary members that
match the specied tag set and directs reads to a random secondary from among thenearest group(page 533).
If no secondaries have matching tags, the read operation produces an error.
14
Read operations using thesecondary(page 603) mode may return stale data.
secondaryPreferred
In most situations, operations read fromsecondarymembers, but in situations where the set consists of a single
primary(and no other members), the read operation will use the set's primary.
14
If your set has more than one secondary, and you use thesecondary(page 603) read preference mode, consider the following effect. If
you have athree member replica set(page 518) with a primary and two secondaries, and if one secondary becomes unavailable, allsecondary
(page 603) queries must target the remaining secondary. This will double the load on this secondary. Plan and provide capacity to support this as
needed.
9.4. Replication Reference 603

MongoDB Documentation, Release 2.6.4
When the read preference includes atag set(page 532), the client attempts to nd a secondary member that
matches the specied tag set and directs reads to a random secondary from among thenearest group(page 533).
If no secondaries have matching tags, the client ignores tags and reads from the primary.
Read operations using thesecondaryPreferred (page 603) mode may return stale data.
nearest
The driver reads from thenearestmember of thesetaccording to themember selection(page 533) process.
Reads in thenearest(page 604) mode do not consider the member'stype. Reads innearest(page 604)
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 atag set(page 532), the client attempts to nd a replica set member that matches the specied
tag set and directs reads to an arbitrary member from among thenearest group(page 533).
Read operations using thenearest(page 604) mode may return stale data.
Note:All operations read from a member of the nearest group of the replica set that matches the specied
read preference mode. Thenearest(page 604) mode prefers low latency reads over a member'sprimaryor
secondarystatus.
Fornearest(page 604), 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. SeeMember Selection(page 533) for more information.
Use Cases
Depending on the requirements of an application, you can congure different applications to use different read prefer-
ences, or use different read preferences for different queries in the same application. Consider the following applica-
tions for different read preference strategies.
Maximize ConsistencyTo avoidstalereads under all circumstances, useprimary(page 603). This prevents all
queries when the set has noprimary, which happens during elections, or when a majority of the replica set is not
accessible.
Maximize AvailabilityTo permit read operations when possible, UseprimaryPreferred(page 603). When
there's a primary you will get consistent reads, but if there is no primary you can still querysecondaries.
Minimize LatencyTo always read from a low-latency node, usenearest(page 604). The driver ormongoswill
read from the nearest member and those no more than 15 milliseconds
15
further away than the nearest member.
nearest(page 604) doesnotguarantee consistency. If the nearest member to your application server is a secondary
with some replication lag, queries could return stale data.nearest(page 604) only reects network distance and
does not reect I/O or CPU load.
Query From Geographically Distributed MembersIf the members of a replica set are geographically distributed,
you can create replica tags based that reect the location of the instance and then congure your application to query
the members nearby.
15
This threshold is congurable. SeelocalPingThresholdMs formongosor your driver documentation for the appropriate setting.
604 Chapter 9. Replication

MongoDB Documentation, Release 2.6.4
For example, if members in east and west data centers aretagged(page 576){'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:,
tags:dc:} ] } )
Althoughnearest(page 604) already favors members with low network latency, including the tag makes the choice
more predictable.
Reduce load on the primaryTo shift read load from the primary, use modesecondary(page 603). Although
secondaryPreferred (page 603) is tempting for this use case, it carries some risk: if all secondaries are unavail-
able and your set has enougharbitersto prevent the primary from stepping down, then the primary will receive all
trafc from clients. If the primary is unable to handle this load, queries will compete with writes. For this reason, use
secondary(page 603) to distribute read load to replica sets, notsecondaryPreferred (page 603).
Read Preferences for Database Commands
Because somedatabase commandsread and return data from the database, all of the ofcial drivers support fullread
preference mode semantics(page 603) for the following commands:
group
mapReduce
16
aggregate
17
collStats
dbStats
count
distinct
geoNear
geoSearch
geoWalk
parallelCollectionScan
New in version 2.4:mongosadds support for routing commands to shards using read preferences. Previously
mongossent all commands to shards' primaries.
16
Only inlinemapReduceoperations that do not write data support read preference, otherwise these operations must run on theprimary
members.
17
Using the$outpipeline operator forces the aggregation pipeline to run on the primary.
9.4. Replication Reference 605

MongoDB Documentation, Release 2.6.4
606 Chapter 9. Replication

CHAPTER10
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 sufcient 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(page 607)A high-level introduction to horizontal scaling, data partitioning, and sharded
clusters in MongoDB.
Sharding Concepts(page 613)The core documentation of sharded cluster features, conguration, architecture and
behavior.
Sharded Cluster Components(page 613)A sharded cluster consists of shards, cong servers, andmongos
instances.
Sharded Cluster Architectures(page 617)Outlines the requirements for sharded clusters, and provides exam-
ples of several possible architectures for sharded clusters.
Sharded Cluster Behavior(page 620)Discusses the operations of sharded clusters with regards to the auto-
matic balancing of data in a cluster and other related availability and security considerations.
Sharding Mechanics(page 628)Discusses the internal operation and behavior of sharded clusters, including
chunk migration, balancing, and the cluster metadata.
Sharded Cluster Tutorials(page 634)Tutorials that describe common procedures and administrative operations rel-
evant to the use and maintenance of sharded clusters.
Sharding Reference(page 678)Reference for sharding-related functions and operations.
10.1
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.
10.1.1
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 scalingandsharding.
607

MongoDB Documentation, Release 2.6.4
Vertical scalingadds more CPU and storage resources to increase capacity. Scaling by adding capacity has lim-
itations: high performance systems with large numbers of CPUs and large amount of RAM are disproportionately
more expensivethan smaller systems. Additionally, cloud-based providers may only allow users to provision smaller
instances. As a result there is apractical maximumcapability for vertical scaling.
Sharding, orhorizontal 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.
Figure 10.1: Diagram of a large collection with data distributed across 4 shards.
Sharding addresses the challenge of scaling to support high throughput and large data sets:

cluster grows. As a result, a cluster can increase capacity and throughputhorizontally.
For example, to insert data, the application only needs to access the shard responsible for that record.

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.
608 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
10.1.2
MongoDB supports sharding through the conguration of asharded clusters.
Figure 10.2: Diagram of a sample sharded cluster for production purposes. Contains exactly 3 cong servers, 2 or
moremongosquery routers, and at least 2 shards. The shards are replica sets.
Sharded cluster has the following components:shards,query routersandcong servers.
Shardsstore the data. To provide high availability and data consistency, in a production sharded cluster, each shard is
areplica set
1
. For more information on replica sets, seeReplica Sets(page 507).
Query Routers, ormongosinstances, 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 cluster have many query routers.
Cong serversstore 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 specic shards. Production sharded clusters haveexactly3
cong servers.
10.1.3
MongoDB distributes data, or shards, at the collection level. Sharding partitions a collection's data by theshard key.
1
For development and testing purposes only, eachshardcan be a singlemongodinstead of a replica set. Donotdeploy production clusters
without 3 cong servers.
10.1. Sharding Introduction 609

MongoDB Documentation, Release 2.6.4
Shard Keys
To shard a collection, you need to select ashard key. Ashard keyis either an indexed eld or an indexed compound
eld that exists in every document in the collection. MongoDB divides the shard key values intochunksand distributes
thechunksevenly across the shards. To divide the shard key values into chunks, MongoDB uses eitherrange based
partitioningorhash based partitioning. See theShard Key(page 620) documentation for more information.
Range Based Sharding
Forrange-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
innity to positive innity, each value of the shard key falls at some point on that line. MongoDB partitions this line
into smaller, non-overlapping ranges calledchunkswhere 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.
Figure 10.3: Diagram of the shard key value space segmented into smaller ranges or chunks.
Hash Based Sharding
Forhash based partitioning, MongoDB computes a hash of a eld's value, and then uses these hashes to create chunks.
With hash based partitioning, two documents with close shard key values areunlikelyto 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 efcient 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 benets
of sharding. For example, if the shard key is a linearly increasing eld, 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.
610 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Figure 10.4: Diagram of the hashed based segmentation.
Hash based partitioning, by contrast, ensures an even distribution of data at the expense of efcient 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 usingtag 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.
SeeTag Aware Sharding(page 671) for more information.
10.1.4
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 signicantly more chunks than another shard or a size of a chunk is signicantly
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 aspecied
chunk size(page 633), MongoDB splits the chunk in half. Inserts and updates triggers splits. Splits are a efcient
meta-data change. To create splits, MongoDB doesnotmigrate any data or affect the shards.
10.1. Sharding Introduction 611

MongoDB Documentation, Release 2.6.4
Figure 10.5: Diagram of a shard with a chunk that exceeds the default chunk size of 64 MB and triggers a split of the
chunk into two chunks.
Balancing
Thebalancer(page 629) is a background process that manages chunk migrations. The balancer runs in all of 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 collectionusershas 100 chunks onshard 1and 50 chunks onshard 2, the balancer will migrate
chunks fromshard 1toshard 2until the collection achieves balance.
The shards managechunk migrationsas a background operation between anorigin shardand adestination shard.
During a chunk migration, thedestination shardis sent all the current documents in the chunk from theorigin 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 oncong serveris 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 shardafterthe migration completes successfully.
Figure 10.6: Diagram of a collection distributed across three shards. For this collection, the difference in the number
of chunks between the shards reaches themigration thresholds(in this case, 2) and triggers migration.
612 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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.
10.2
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, seeSharding Introduction
(page 607).
Sharded Cluster Components(page 613)A sharded cluster consists of shards, cong servers, andmongosin-
stances.
Shards(page 614)A shard is amongodinstance that holds a part of the sharded collection's data.
Cong Servers(page 616)Cong servers hold the metadata about the cluster, such as the shard location of the
data.
Sharded Cluster Architectures(page 617)Outlines the requirements for sharded clusters, and provides examples of
several possible architectures for sharded clusters.
Sharded Cluster Requirements(page 617)Discusses the requirements for sharded clusters in MongoDB.
Production Cluster Architecture(page 618)Sharded cluster for production has component requirements to
provide redundancy and high availability.
Continue reading fromSharded Cluster Architectures(page 617) for additional descriptions of sharded cluster
deployments.
Sharded Cluster Behavior(page 620)Discusses the operations of sharded clusters with regards to the automatic bal-
ancing of data in a cluster and other related availability and security considerations.
Shard Keys(page 620)MongoDB uses the shard key to divide a collection's data across the cluster's shards.
Sharded Cluster High Availability(page 623)Sharded clusters provide ways to address some availability con-
cerns.
Sharded Cluster Query Routing(page 624)The cluster's routers, ormongosinstances, send reads and writes
to the relevant shard or shards.
Sharding Mechanics(page 628)Discusses the internal operation and behavior of sharded clusters, including chunk
migration, balancing, and the cluster metadata.
Sharded Collection Balancing(page 629)Balancing distributes a sharded collection's data cluster to all of the
shards.
Sharded Cluster Metadata(page 634)The cluster maintains internal metadata that reects the location of data
within the cluster.
Continue reading fromSharding Mechanics(page 628) for more documentation of the behavior and operation
of sharded clusters.
10.2.1
Sharded clustersimplementsharding. A sharded cluster consists of the following components:
10.2. Sharding Concepts 613

MongoDB Documentation, Release 2.6.4
ShardsA shard is a MongoDB instance that holds a subset of a collection's data. Each shard is either a single
mongodinstance or areplica set. In production, all shards are replica sets. For more information seeShards
(page 614).
Cong ServersEachcong server(page 616) is amongodinstance that holds metadata about the cluster. The
metadata mapschunksto shards. For more information, seeCong Servers(page 616).
Routing InstancesEach router is amongosinstance that routes the reads and writes from applications to the shards.
Applications do not access the shards directly. For more information seeSharded Cluster Query Routing
(page 624).
Figure 10.7: Diagram of a sharded cluster.
Enable sharding in MongoDB on a per-collection basis. For each collection you shard, you will specify ashard key
for that collection.
Deploy a sharded cluster, seeDeploy a Sharded Cluster(page 635).
Shards
A shard is areplica setor a singlemongodthat contains a subset of the data for the sharded cluster. Together, the
cluster's shards hold the entire data set for the cluster.
614 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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 aper collectionbasis. Youmustaccess all data in a sharded cluster via the
mongosinstances. 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 specic shard. MongoDB does not guarantee that any two contiguous chunks will
reside on a single shard.
Primary Shard
Every database has a primary
2
shard that holds all the un-sharded collections in that database.
Figure 10.8: Diagram of a primary shard. A primary shard contains non-sharded collections as well as chunks of
documents from sharded collections. Shard A is the primary shard.
To change the primary shard for a database, use themovePrimarycommand. The process of migrating the primary
shard may take signicant time to complete, and you should not access the collections until it completes.
When you deploy a newsharded clusterwith 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.
Shard Status
Use thesh.status()method in themongoshell to see an overview of the cluster. This reports includes which
shard is primary for the database and thechunkdistribution across the shards. Seesh.status()method for more
2
The term primary shard has nothing to do with the termprimaryin the context ofreplica sets.
10.2. Sharding Concepts 615

MongoDB Documentation, Release 2.6.4
details.
Cong Servers
Cong servers are specialmongodinstances that store themetadata(page 634) for a sharded cluster. Cong servers
use a two-phase commit to ensure immediate consistency and reliability. Cong serversdo notrun as replica sets. All
cong servers must be available to deploy a sharded cluster or to make any changes to cluster metadata.
A production sharded cluster hasexactly threecong servers. For testing purposes you may deploy a cluster with a
single cong server. But to ensure redundancy and safety in production, you should always use three.
Warning:If your cluster has a single cong server, then the cong server is a single point of failure. If the cong
server is inaccessible, the cluster is not accessible. If you cannot recover the data on a cong server, the cluster
will be inoperable.
Alwaysuse three cong servers for production deployments.
Each sharded cluster must have its own cong servers. Do not use the same cong servers for different sharded
clusters.
Tip
Use CNAMEs to identify your cong servers to the cluster so that you can rename and renumber your cong servers
without downtime.
Cong Database
Cong servers store the metadata in thecong database(page 679). Themongosinstances cache this data and use it
to route reads and writes to shards.
Read and Write Operations on Cong Servers
MongoDB only writes data to the cong server in the following cases:
chunk splitting(page 632).
chunk migration(page 630).
MongoDB reads data from the cong server data in the following cases:
mongosstarts for the rst time, or an existingmongosrestarts.
mongosinstances update themselves with the new cluster metadata.
MongoDB also uses the cong server to manage distributed locks.
Cong Server Availability
If one or two cong servers become unavailable, the cluster's metadata becomesread 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 cong servers are unavailable, you can still use the cluster if you do not restart themongosinstances
until after the cong servers are accessible again. If you restart themongosinstances before the cong servers are
available, themongoswill be unable to route reads and writes.
616 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Clusters become inoperable without the cluster metadata.Always,ensure that the cong servers remain available and
intact. As such, backups of cong servers are critical. The data on the cong server is small compared to the data
stored in a cluster. This means the cong server has a relatively low activity load, and the cong server does not need
to be always available to support a sharded cluster. As a result, it is easy to back up the cong servers.
If the name or address that a sharded cluster uses to connect to a cong server changes, you must restarteverymongod
andmongosinstance in the sharded cluster. Avoid downtime by using CNAMEs to identify cong servers within the
MongoDB deployment.
SeeRenaming Cong Servers and Cluster Availability(page 623) for more information.
10.2.2
The following documents introduce deployment patterns for sharded clusters.
Sharded Cluster Requirements(page 617)Discusses the requirements for sharded clusters in MongoDB.
Production Cluster Architecture(page 618)Sharded cluster for production has component requirements to provide
redundancy and high availability.
Sharded Cluster Test Architecture(page 618)Sharded clusters for testing and development can have fewer compo-
nents.
Sharded Cluster Requirements
While sharding is a powerful and compelling feature, sharded clusters have signicant 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 theonlysolution for some classes of deployments. Usesharded clustersif:

working set will soonexceed the capacity of your system'smaximumRAM.

not reduced contention.
If these attributes are not present in your system, sharding will only add complexity to your system without adding
much benet.
Important:It takes time and resources to deploy sharding. If your system hasalreadyreached or exceeded its
capacity, it will be difcult to deploy sharding without impacting your application.
As a result, if you think you will need to partition your database in the future,do notwait until your system is
overcapacity 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 defaultchunksize is 64
megabytes. And thebalancer(page 629) will not begin moving data across shards until the imbalance of chunks among
the shards exceeds themigration threshold(page 630). In practical terms, unless your cluster has many hundreds of
megabytes of data, your data will remain on a single shard.
10.2. Sharding Concepts 617

MongoDB Documentation, Release 2.6.4
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 congured single MongoDB instance or a replica set will usually be enough for your persistence layer
needs.
Chunksize isuser configurable. For most deployments, the default value is of 64 megabytes is ideal. See
Chunk Size(page 633) 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
Cong ServersThreecong servers(page 616). Each cong server must be on separate machines. A singlesharded
clustermust have exclusive use of itscong servers(page 616). If you have multiple sharded clusters, you will need
to have a group of cong servers for each cluster.
ShardsTwo or morereplica sets. These replica sets are theshards. For information on replica sets, seeReplication
(page 503).
Query Routers (mongos)One or moremongosinstances. Themongosinstances are the routers for the cluster.
Typically, deployments have onemongosinstance on each application server.
You may also deploy a group ofmongosinstances and use a proxy/load balancer between the application and the
mongos. In these deployments, youmustcongure the load balancer forclient afnityso that every connection from
a single client reaches the samemongos.
Because cursors and other resources are specic to an singlemongosinstance, each client must interact with only
onemongosinstance.
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. Thesenon-productionclusters have
the following components:
cong server(page 616).
replica setsor a standalonemongodinstances.
mongosinstance.
See
Production Cluster Architecture(page 618)
618 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Figure 10.9: Diagram of a sample sharded cluster for production purposes. Contains exactly 3 cong servers, 2 or
moremongosquery routers, and at least 2 shards. The shards are replica sets.
10.2. Sharding Concepts 619

MongoDB Documentation, Release 2.6.4
Figure 10.10: Diagram of a sample sharded cluster for testing/development purposes only. Contains only 1 cong
server, 1mongosrouter, and at least 1 shard. The shard can be either a replica set or a standalonemongodinstance.
10.2.3
These documents address the distribution of data and queries to a sharded cluster as well as specic security and
availability considerations for sharded clusters.
Shard Keys(page 620)MongoDB uses the shard key to divide a collection's data across the cluster's shards.
Sharded Cluster High Availability(page 623)Sharded clusters provide ways to address some availability concerns.
Sharded Cluster Query Routing(page 624)The cluster's routers, ormongosinstances, send reads and writes to the
relevant shard or shards.
Shard Keys
The shard key determines the distribution of the collection'sdocumentsamong the cluster'sshards. The shard key is
either an indexedeldor an indexed compound eld that exists in every document in the collection.
MongoDB partitions data in the collection using ranges of shard key values. Each range, orchunk, denes 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 thechunk size(page 633), MongoDBsplitsthe chunk into smaller chunks, always based
on ranges in the shard key.
Considerations
Shard keys are immutable and cannot be changed after insertion. See thesystem limits for sharded clusterfor more
information.
620 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Figure 10.11: Diagram of the shard key value space segmented into smaller ranges or chunks.
The index on the shard keycannotbe amultikey index(page 442).
Hashed Shard Keys
New in version 2.4.
Hashed shard keys use ahashed index(page 468) of a single eld as theshard keyto partition data across your sharded
cluster.
The eld you choose as your hashed shard key should have a good cardinality, or large number of different values.
Hashed keys work well with elds that increase monotonically likeObjectIdvalues 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
numInitialChunksparameter toshardCollectionor by manually creating chunks on the empty collection
using thesplitcommand.
To shard a collection using a hashed shard key, seeShard a Collection Using a Hashed Shard Key(page 641).
Tip
MongoDB automatically computes the hashes when resolving queries using hashed indexes. Applications donotneed
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 themongosinstances can direct operations to the cluster. Consider the following operational
impacts of shard key selection:
Write ScalingSome 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_ideld, which isObjectId.
MongoDB generatesObjectIdvalues upon document creation to produce a unique identier for the object. How-
ever, the most signicant 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 hashigh cardinality(page 640), when using this,any date, or other
10.2. Sharding Concepts 621

MongoDB Documentation, Release 2.6.4
monotonically increasing numberas 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 dene 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 areupdate()operations distributed through your entire data set. Generally, choose shard
keys that havebothhigh cardinality and will distribute write operations across theentire 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 providequery isolation(page 622), 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. SeeShard a Collection Using a Hashed Shard Key(page 641).
QueryingThemongosprovides an interface for applications to interact with sharded clusters that hides the com-
plexity ofdata partitioning. Amongosreceives queries from applications, and uses metadata from thecong server
(page 616), to route queries to themongodinstances with the appropriate data. While themongossucceeds in mak-
ing all querying operational in sharded environments, theshard keyyou select can have a profound affect on query
performance.
See also:
TheSharded Cluster Query Routing(page 624) andcong server(page 616) sections for a more general overview of
querying in sharded environments.
Query IsolationThe fastest queries in a sharded environment are those thatmongoswill route to a single shard,
using theshard keyand the cluster meta data from thecong server(page 616). For queries that don't include the
shard key,mongosmust query all shards, wait for their response and then return the result to the application. These
scatter/gather queries can be long running operations.
If your query includes the rst component of a compound shard key
3
, themongoscan 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, themongoswill route queries directly to specic shards.
To select a shard key for a collection:

If this eld has low cardinality (i.e not sufciently selective) you should add a second eld 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(page 624) for more information on query operations in the context of sharded clusters.
SortingIn sharded systems, themongosperforms a merge-sort of all sorted query results from the shards. See
Sharded Cluster Query Routing(page 624) andUse Indexes to Sort Query Results(page 496) for more information.
3
In many ways, you can think of the shard key a cluster-wide unique index. However, be aware that sharded systems cannot enforce cluster-
wide unique indexesunlessthe unique eld is in the shard key. Consider theIndex Concepts(page 436) page for more information on indexes and
compound indexes.
622 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Sharded Cluster High Availability
Aproduction(page 618)clusterhas 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 ormongosInstances Become Unavailable
If each application server has its ownmongosinstance, other application servers can continue access the database.
Furthermore,mongosinstances do not maintain persistent state, and they can restart and become unavailable without
losing any state or data. When amongosinstance starts, it retrieves a copy of thecong databaseand can begin
routing queries.
A SinglemongodBecomes Unavailable in a Shard
Replica sets(page 503) provide high availability for shards. If the unavailablemongodis aprimary, then the replica
set willelect(page 523) a new primary. If the unavailablemongodis asecondary, 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.
4
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 Cong Databases Become Unavailable
Three distinctmongodinstances provide thecong databaseusing a special two-phase commits to maintain consistent
state between thesemongodinstances. Cluster operation will continue as normal butchunk migration(page 629) and
the cluster can create no newchunk splits(page 666). Replace the cong server as soon as possible. If all cong
databases become unavailable, the cluster can become inoperable.
Note:All cong servers must be running and available when you rst initiate asharded cluster.
Renaming Cong Servers and Cluster Availability
If the name or address that a sharded cluster uses to connect to a cong server changes, you must restarteverymongod
andmongosinstance in the sharded cluster. Avoid downtime by using CNAMEs to identify cong servers within the
MongoDB deployment.
To avoid downtime when renaming cong servers, use DNS names unrelated to physical or virtual hostnames to refer
to yourcong servers(page 616).
4
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
normalreplication process, otherwise it must perform aninitial sync.
10.2. Sharding Concepts 623

MongoDB Documentation, Release 2.6.4
Generally, refer to each cong server using the DNS alias (e.g. a CNAME record). When specifying the cong server
connection string tomongos, use these names. These records make it possible to change the IP address or rename
cong 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 ashard keyare:

mongoscan isolate most queries to a specicmongod.
Furthermore:
replica set, if a specicmongodinstance fails, the replica set members will elect another
to beprimaryand continue operation. However, if an entire shard is unreachable or fails for some reason, that
data will be unavailable.
mongosto isolate most operations to a single shard, then the failure of a single shard
will only rendersomedata unavailable.

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
MongoDBmongosinstances route queries and write operations toshardsin a sharded cluster.mongosprovide the
only interface to a sharded cluster from the perspective of applications. Applications never connect or communicate
directly with the shards.
Themongostracks what data is on which shard by caching the metadata from thecong servers(page 616). The
mongosuses the metadata to route operations from applications and clients to themongodinstances. Amongos
has nopersistentstate and consumes minimal system resources.
The most common practice is to runmongosinstances on the same systems as your application servers, but you can
maintainmongosinstances on the shards or on other dedicated resources.
Note:Changed in version 2.1.
Some aggregation operations using theaggregatecommand (i.e.db.collection.aggregate() ) will cause
mongosinstances to require more CPU resources than in previous versions. This modied performance prole may
dictate alternate architecture decisions if you use theaggregation frameworkextensively in a sharded environment.
Routing Process
Amongosinstance uses the following processes to route queries and return results.
HowmongosDetermines which Shards Receive a QueryAmongosinstance routes a query to aclusterby:
1. shardsthat must receive the query.
2.
624 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
In some cases, when theshard keyor a prex of the shard key is a part of the query, themongoscan route the query
to a subset of the shards. Otherwise, themongosmust direct the query toallshards that hold documents for that
collection.
Example
Given the following shard key:
{ zipcode:, u_id:, c_date:
Depending on the distribution of chunks in the cluster, themongosmay be able to target the query at a subset of
shards, if the query contains the following elds:
{ zipcode:
{ zipcode:, u_id:
{ zipcode:, u_id:, c_date:
HowmongosHandles Query ModiersIf the result of the query is not sorted, themongosinstance 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, themongosexhausted each cursor, one by one.
If the query species sorted results using thesort()cursor method, themongosinstance passes the$orderby
option to the shards. When themongosreceives results it performs an incrementalmerge sortof the results while
returning them to the client.
If the query limits the size of the result set using thelimit()cursor method, themongosinstance 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 species a number of records toskipusing theskip()cursor method, themongoscannotpass 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 alimit(), themongoswill pass
thelimitplus the value of theskip()to the shards to improve the efciency of these operations.
Detect Connections tomongosInstances
To detect if the MongoDB instance that your client is connected to ismongos, use theisMastercommand. When
a client connects to amongos,isMasterreturns a document with amsgeld that holds the stringisdbgrid. For
example:
{
"ismaster" true,
"msg",
"maxBsonObjectSize",
"ok"
}
If the application is instead connected to amongod, the returned document does not include theisdbgridstring.
Broadcast Operations and Targeted Operations
In general, operations in a sharded environment are either:

10.2. Sharding Concepts 625

MongoDB Documentation, Release 2.6.4
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 Operationsmongosinstances broadcast queries to all shards for the collectionunlessthemongoscan
determine which shard or subset of shards stores this data.
Figure 10.12: Read operations to a sharded cluster. Query criteria does not include the shard key. The query router
mongosmust broadcast query to all shards for the collection.
Multi-update operations are always broadcast operations.
Theremove()operation is always a broadcast operation, unless the operation species the shard key in full.
Targeted OperationsAllinsert()operations target to one shard.
All singleupdate()(includingupsertoperations) andremove()operations must target to one shard.
Important:Allupdate()andremove()operations for a sharded collection that specify thejustOneor
multi: false option must include theshard key orthe_ideld in the query specication.update()and
remove()operations specifyingjustOneormulti: false in a sharded collection without theshard key or
the_ideld return an error.
626 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
For queries that include the shard key or portion of the shard key,mongoscan target the query at a specic shard or
set of shards. This is the case only if the portion of the shard key included in the query is aprexof the shard key. For
example, if the shard key is:
{ a:, b:, c:
Themongosprogramcanroute queries that include the full shard key or either of the following shard key prexes at
a specic shard or set of shards:
{ a:
{ a:, b:
Figure 10.13: Read operations to a sharded cluster. Query criteria includes the shard key. The query routermongos
can target the query to the appropriate shard or shards.
Depending on the distribution of data in the cluster and the selectivity of the query,mongosmay still have to contact
multiple shards
5
to fulll these queries.
5
mongoswill route some queries, even some that include the shard key, to all shards, if needed.
10.2. Sharding Concepts 627

MongoDB Documentation, Release 2.6.4
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.
6
However, in production deployments, some databases and collections will use
sharding, while other databases and collections will only reside on a single shard.
Figure 10.14: Diagram of a primary shard. A primary shard contains non-sharded collections as well as chunks of
documents from sharded collections. Shard A is the primary shard.
Regardless of the data architecture of yoursharded cluster, ensure that all queries and operations use themongos
router to access the data cluster. Use themongoseven for operations that do not impact the sharded data.
10.2.4
The following documents describe sharded cluster processes.
Sharded Collection Balancing(page 629)Balancing distributes a sharded collection's data cluster to all of the
shards.
Chunk Migration Across Shards(page 630)MongoDB migrates chunks to shards as part of the balancing process.
Chunk Splits in a Sharded Cluster(page 632)When a chunk grows beyond the congured size, MongoDB splits the
chunk in half.
Shard Key Indexes(page 633)Sharded collections must keep an index that starts with the shard key.
Sharded Cluster Metadata(page 634)The cluster maintains internal metadata that reects the location of data within
the cluster.
6
As you congure sharding, you will use theenableShardingcommand to enable sharding for a database. This simply makes it possible
to use theshardCollectioncommand on a collection within that database.
628 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Figure 10.15: Diagram of applications/drivers issuing queries to mongos for unsharded collection as well as sharded
collection. Cong servers not shown.
Sharded Collection Balancing
Balancing is the process MongoDB uses to distribute data of a sharded collection evenly across asharded cluster.
When ashardhas too many of a sharded collection'schunkscompared to other shards, MongoDB automatically
balances the chunks across the shards. The balancing procedure forsharded clustersis entirely transparent to the user
and application layer.
Cluster Balancer
Thebalancerprocess 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.
Anymongosinstance in the cluster can start a balancing round. When a balancer process is active, the responsible
mongosacquires a lock by modifying a document in thelockcollection in theCong Database(page 679).
Note:Changed in version 2.0: Before MongoDB version 2.0, large differences in timekeeping (i.e. clock skew)
betweenmongosinstances 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 runningntpdon your servers to
minimize clock skew.
To address uneven chunk distribution for a sharded collection, the balancermigrates chunks(page 630) 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. Thebalancerattempts to minimize the impact by:
Chunk Migration Queuing(page 631).
10.2. Sharding Concepts 629

MongoDB Documentation, Release 2.6.4
onlywhen 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 themigration threshold(page 630).
You may disable the balancer temporarily for maintenance. SeeDisable the Balancer(page 661) for details.
You can also limit the window during which the balancer runs to prevent it from impacting production trafc. See
Schedule the Balancing Window(page 660) for details.
Note:The specication of the balancing window is relative to the local time zone of all individualmongosinstances
in the cluster.
See also:
Manage Sharded Cluster Balancer(page 659).
Migration Thresholds
To minimize the impact of balancing on the cluster, thebalancerwill not begin balancing until the distribution of
chunks for a sharded collection has reached certain thresholds. The thresholds apply to the difference in number
ofchunksbetween 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 rst 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 ChunksMigration Threshold
Fewer than 20 2
20-79 4
80 and greater8
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 isless than twoor a chunk migration fails.
Shard Size
By default, MongoDB will attempt to ll 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 thebalancerfrom migrating chunks
to the shard when the value ofmappedexceeds the maximum size. Use themaxSizeparameter of theaddShard
command to set the maximum size for the shard.
See also:
Change the Maximum Storage Size for a Given Shard(page 658) andMonitoring for MongoDB(page 175).
Chunk Migration Across Shards
Chunk migration moves the chunks of a sharded collection from one shard to another and is part of thebalancer
(page 629) process.
630 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Figure 10.16: Diagram of a collection distributed across three shards. For this collection, the difference in the number
of chunks between the shards reaches themigration thresholds(in this case, 2) and triggers migration.
Chunk Migration
MongoDB migrates chunks in asharded clusterto distribute the chunks of a sharded collection evenly among shards.
Migrations may be either:
Migrating
Chunks Manually(page 667) for more details.
balancer(page 629) process automatically migrates chunks when there is an uneven distribution
of a sharded collection's chunks across the shards. SeeMigration Thresholds(page 630) for more details.
All chunk migrations use the following procedure:
1. moveChunkcommand to the source shard.
2. moveChunkcommand. 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.
3.
4.
that it has the changes to the migrated documents that occurred during the migration.
5. cong databaseand updates the cluster metadata
with the new location for the chunk.
6.
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 nish this
deletion step. SeeChunk Migration Queuing(page 631).
The migration process ensures consistency and maximizes the availability of chunks during balancing.
Chunk Migration QueuingChanged 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. SeeChunk
Migration(page 631) for the chunk migration process and the delete phase.
10.2. Sharding Concepts 631

MongoDB Documentation, Release 2.6.4
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 themoveChunkcommand, and migration scripts that use themoveChunkcommand 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 ReplicationBy 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 tofalse. SeeChange Replication Behavior for Chunk Migration (Secondary
Throttle)(page 658) to update the_secondaryThrottle parameter for the balancer.
Independent of thesecondaryThrottlesetting, certain phases of the chunk migration have the following repli-
cation policy:

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 cong servers.

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
7
Chunk Splits in a Sharded Cluster
As chunks grow beyond thespecied chunk size(page 633) amongosinstance 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, themongos
instances will initiate a round of migrations to redistribute chunks across shards. SeeSharded Collection Balancing
(page 629) for more details on balancing chunks across shards.
Figure 10.17: Diagram of a shard with a chunk that exceeds the default chunk size of 64 MB and triggers a split of the
chunk into two chunks.
7
http://docs.mongodb.org/v2.2/tutorial/congure-sharded-cluster-balancer/#sharded-cluster-cong-secondary-throttle
632 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Chunk Size
The defaultchunksize in MongoDB is 64 megabytes. You canincrease or reduce the chunk size(page 671), mindful
of its effect on the cluster's efciency.
1.
expense at the query routing (mongos) layer.
2. andin terms
of internal overhead at the query routing layer. But, these efciencies come at the expense of a potentially more
uneven distribution of data.
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.

chunks to split to the new size.

until they reach the new size.
Note:Chunk ranges are inclusive of the lower boundary and exclusive of the upper boundary.
Shard Key Indexes
All sharded collectionsmusthave an index that starts with theshard key. If you shard a collection without any
documents andwithoutsuch an index, theshardCollectioncommand will create the index on the shard key. If
the collection already has documents, you must create the index before usingshardCollection.
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 acompound indexwhere the shard key is a prex of the index.
Important:The index on the shard keycannotbe amultikey index(page 442).
A sharded collection namedpeoplehas for its shard key the eldzipcode. It currently has the index{
zipcode: 1 }. You can replace this index with a compound index{ zipcode: 1, username: 1 } ,
as follows:
1. { zipcode: 1, username: 1 } :
db.people.ensureIndex( { zipcode:, username:
2. { zipcode: 1 } :
db.people.dropIndex( { zipcode:
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 theusernameeld.
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, seelimits-shard-keys.
10.2. Sharding Concepts 633

MongoDB Documentation, Release 2.6.4
Sharded Cluster Metadata
Cong servers(page 616) store the metadata for a sharded cluster. The metadata reects state and organization of the
sharded data sets and system. The metadata includes the list of chunks on every shard and the ranges that dene the
chunks. Themongosinstances cache this data and use it to route read and write operations to shards.
Cong servers store the metadata in theCong Database(page 679).
Important:Always back up theconfigdatabase before doing any maintenance on the cong server.
To access theconfigdatabase, issue the following command from themongoshell:
use config
In general, you shouldneveredit the content of theconfigdatabase directly. Theconfigdatabase contains the
following collections:
changelog(page 680)
chunks(page 681)
collections(page 682)
databases(page 682)
lockpings(page 682)
locks(page 682)
mongos(page 683)
settings(page 683)
shards(page 684)
version(page 684)
For more information on these collections and their role in sharded clusters, seeCong Database(page 679). SeeRead
and Write Operations on Cong Servers(page 616) for more information about reads and updates to the metadata.
10.3
The following tutorials provide instructions for administeringsharded clusters. For a higher-level overview, seeShard-
ing(page 607).
Sharded Cluster Deployment Tutorials(page 635)Instructions for deploying sharded clusters, adding shards, select-
ing shard keys, and the initial conguration of sharded clusters.
Deploy a Sharded Cluster(page 635)Set up a sharded cluster by creating the needed data directories, starting
the required MongoDB instances, and conguring the cluster settings.
Considerations for Selecting Shard Keys(page 639)Choose the eld that MongoDB uses to parse a collec-
tion'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(page 641)Shard a collection based on hashes of a eld's val-
ues in order to ensure even distribution over the collection's shards.
Add Shards to a Cluster(page 642)Add a shard to add capacity to a sharded cluster.
Continue reading fromSharded Cluster Deployment Tutorials(page 635) for additional tutorials.
634 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Sharded Cluster Maintenance Tutorials(page 650)Procedures and tasks for common operations on active sharded
clusters.
View Cluster Conguration(page 650)View status information about the cluster's databases, shards, and
chunks.
Remove Shards from an Existing Sharded Cluster(page 663)Migrate a single shard's data and remove the
shard.
Migrate Cong Servers with Different Hostnames(page 652)Migrate a cong server to a new system that
uses a new hostname. If possible, avoid changing the hostname and instead use theMigrate Cong Servers
with the Same Hostname(page 652) procedure.
Manage Shard Tags(page 672)Use tags to associate specic ranges of shard key values with specic shards.
Continue reading fromSharded Cluster Maintenance Tutorials(page 650) for additional tutorials.
Sharded Cluster Data Management(page 665)Practices that address common issues in managing large sharded
data sets.
Troubleshoot Sharded Clusters(page 677)Presents solutions to common issues and concerns relevant to the admin-
istration and use of sharded clusters. Refer toFAQ: MongoDB Diagnostics(page 720) for general diagnostic
information.
10.3.1
The following tutorials provide information on deploying sharded clusters.
Deploy a Sharded Cluster(page 635)Set up a sharded cluster by creating the needed data directories, starting the
required MongoDB instances, and conguring the cluster settings.
Considerations for Selecting Shard Keys(page 639)Choose the eld that MongoDB uses to parse a collection's doc-
uments 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(page 641)Shard a collection based on hashes of a eld's values in
order to ensure even distribution over the collection's shards.
Add Shards to a Cluster(page 642)Add a shard to add capacity to a sharded cluster.
Deploy Three Cong Servers for Production Deployments(page 643)Convert a test deployment with one cong
server to a production deployment with three cong servers.
Convert a Replica Set to a Replicated Sharded Cluster(page 643)Convert a replica set to a sharded cluster in which
each shard is its own replica set.
Convert Sharded Cluster to Replica Set(page 649)Replace your sharded cluster with a single replica set.
See also:
Enable Authentication in a Sharded Cluster(page 318)
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 or127.0.0.1as the hostname portion of any host identier, for example as the
hostargument toaddShardor the value to the--configdbrun time option, then you must use localhost
or127.0.0.1forallhost settings for any MongoDB instances in the cluster. If you mix localhost addresses and
remote host address, MongoDB will error.
10.3. Sharded Cluster Tutorials 635

MongoDB Documentation, Release 2.6.4
Start the Cong Server Database Instances
The cong server processes aremongodinstances that store the cluster's metadata. You designate amongodas a
cong server using the--configsvroption. Each cong server stores a complete copy of the cluster's metadata.
In production deployments, you must deploy exactly three cong 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 toallother members of a sharded cluster,
including all shards and all cong servers. Ensure that the network and security systems including all interfaces and
rewalls, allow these connections.
1.
les in the/data/congdbdirectory. You can choose a different location. To create a data directory, issue a
command similar to the following:
mkdir /data/configdb
2.
mongod --configsvr --dbpath <path> --port <port>
The default port for cong servers is27019. You can specify a different port. The following example starts a
cong server using the default port and default data directory:
mongod --configsvr --dbpath /data/configdb --port 27019
For additional command options, seehttp://docs.mongodb.org/manualreference/program/mongod
orhttp://docs.mongodb.org/manualreference/configuration-options .
Note:All cong servers must be running and available when you rst initiate asharded cluster.
Start themongosInstances
Themongosinstances are lightweight and do not require data directories. You can run amongosinstance on a
system that runs other cluster components, such as on an application server or a server running amongodprocess. By
default, amongosinstance runs on port27017.
When you start themongosinstance, specify the hostnames of the three cong servers, either in the conguration le
or as command line parameters.
Tip
To avoid downtime, give each cong server a logical DNS name (unrelated to the server's physical or virtual host-
name). Without logical DNS names, moving or renaming a cong server requires shutting down everymongodand
mongosinstance in the sharded cluster.
To start amongosinstance, issue a command using the following syntax:
mongos --configdb <config server hostnames>
For example, to start amongosthat connects to cong server instance running on the following hosts and on the
default ports:
cfg0.example.net
cfg1.example.net
636 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
cfg2.example.net
You would issue the following command:
mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019
Eachmongosin a sharded cluster must use the sameconfigDBstring, with identical host names listed in identical
order.
If you start amongosinstance with a string thatdoes notexactly match the string used by the othermongosinstances
in the cluster, themongosreturn aCong Database String Error(page 677) error and refuse to start.
Add Shards to the Cluster
Ashardcan be a standalonemongodor areplica set. In a production environment, each shard should be a replica set.
Use the procedure inDeploy a Replica Set(page 545) to deploy replica sets for each shard.
1. mongoshell, connect to themongosinstance. Issue a command using the following syntax:
mongo --host <hostname of machine running mongos> --port <port mongos listens on>
For example, if amongosis accessible atmongos0.example.net on port27017, issue the following
command:
mongo --host mongos0.example.net --port 27017
2. 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 theaddSharddatabase 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, seeaddShard.
The following are examples of adding a shard withsh.addShard():
rs1with a member running on port27017on
mongodb0.example.net , issue the following command:
sh.addShard(
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(
mongodon port27017ofmongodb0.example.net , issue the fol-
lowing command:
sh.addShard(
Note:It might take some time forchunksto migrate to the new shard.
10.3. Sharded Cluster Tutorials 637

MongoDB Documentation, Release 2.6.4
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 aprimary shardfor that database where MongoDB stores
all data before sharding begins.
1. mongoshell, connect to themongosinstance. Issue a command using the following syntax:
mongo --host <hostname of machine running mongos> --port <port mongos listens on>
2. 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 theenableShardingcommand, which uses the following
syntax:
db.runCommand( { enableSharding:database>
Enable Sharding for a Collection
You enable sharding on a per-collection basis.
1. shard key. Your selection of the shard key affects the efciency of sharding.
See the selection considerations listed in theConsiderations for Selecting Shard Key(page 639).
2. shard keyusingensureIndex(). If
the collection is empty then MongoDB will create the index as part of thesh.shardCollection() step.
3. sh.shardCollection() method in themongoshell. 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. Theshard-key-pattern
represents your shard key, which you specify in the same form as you would anindexkey pattern.
Example
The following sequence of commands shards four collections:
sh.shardCollection("records.people", {:,:
sh.shardCollection("people.addresses", {:,:
sh.shardCollection("assets.chairs", {:,:
sh.shardCollection("events.alerts", {:
In order, these operations shard:
(a) peoplecollection in therecordsdatabase using the shard key{ "zipcode": 1, "name":
1 }.
This shard key distributes documents by the value of thezipcodeeld. If a number of documents have
the same value for this eld, then thatchunkwill besplittable(page 640) by the values of thenameeld.
638 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
(b) addressescollection in thepeopledatabase using the shard key{ "state": 1, "_id":
1 }.
This shard key distributes documents by the value of thestateeld. If a number of documents have the
same value for this eld, then thatchunkwill besplittable(page 640) by the values of the_ideld.
(c) chairscollection in theassetsdatabase using the shard key{ "type": 1, "_id": 1
}.
This shard key distributes documents by the value of thetypeeld. If a number of documents have the
same value for this eld, then thatchunkwill besplittable(page 640) by the values of the_ideld.
(d) alertscollection in theeventsdatabase using the shard key{ "_id": "hashed" } .
New in version 2.4.
This shard key distributes documents by a hash of the value of the_ideld. MongoDB computes the hash
of the_ideld for thehashed index(page 468), 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:
1.
the_ideld.
2.
cardinality with scalable write operations and query isolation.
3.

4. hashed shard key. Choose a eld that has high cardinality and create ahashed index
(page 468) on that eld. 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
notneed to compute hashes.
Considerations for Selecting Shard KeyChoosing the correct shard key can have a great impact on the perfor-
mance, 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.
10.3. Sharded Cluster Tutorials 639

MongoDB Documentation, Release 2.6.4
See also:
Cardinality(page 640)
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(page 621)
Create a Shard Key that Targets a Single Shard
A shard key that targets a single shard makes it possible for themongosprogram to return most query operations
directly from a singlespecicmongodinstance. Your shard key should be the primary eld used by your queries.
Fields with a high degree of randomness make it difcult to target operations to specic shards.
See also:
Query Isolation(page 622)
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 eld in your
collection may not be the optimal key. In those situations, computing a special purpose shard key into an additional
eld 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 topartitiondata intochunks. For example,
consider a collection of data such as an address book that stores address records:
stateeld as a shard key:
The state key's value holds the US state for a given address document. This eld has alow cardinalityas all
documents that have the same value in thestateeldmustreside 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 thestateeld, MongoDB may distribute data unevenly
among a small number of xed 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 involv-
ing these un-splittable chunks will take longer than other migrations, and it will be more difcult for your
data to stay balanced.
If you have a xed maximum number of chunks, you will never be able to use more than that number of
shards for this collection.
zipcodeeld as a shard key:
While this eld 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.
640 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
In these cases, cardinality depends on the data. If your address book stores records for a geographically dis-
tributed contact list (e.g. Dry cleaning businesses in America,) then a value like zipcode would be sufcient.
However, if your address book is more geographically concentrated (e.g ice cream stores in Boston Mas-
sachusetts,) then you may have a much lower cardinality.
phone-numbereld as a shard key:
Phone number has ahigh cardinality,because users will generally have a unique value for this eld, 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 sufcientquery isolation(page 622) or appropriatewrite scaling(page 621).
Shard a Collection Using a Hashed Shard Key
New in version 2.4.
Hashed shard keys(page 621) use ahashed index(page 468) of a eld as theshard keyto partition data across your
sharded cluster.
For suggestions on choosing the right eld as your hashed shard key, seeHashed Shard Keys(page 621). For limita-
tions on hashed indexes, seeCreate a Hashed Index(page 468).
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 themongothat resembles the following:
sh.shardCollection(, { a:
This operation shards theactivecollection in therecordsdatabase, using a hash of theaeld 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
shardCollectionwith thenumInitialChunksparameter.
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 highermongosandmongodinstances in your sharded cluster.
Warning:MongoDBhashedindexes truncate oating point numbers to 64-bit integers before hashing. For
example, ahashedindex would store the same value for a eld that held a value of2.3,2.2, and2.9. To
prevent collisions, do not use ahashedindex for oating point numbers that cannot be reliably converted to
64-bit integers (and then back to oating point). MongoDBhashedindexes do not support oating point values
larger than 2
53
.
10.3. Sharded Cluster Tutorials 641

MongoDB Documentation, Release 2.6.4
Add Shards to a Cluster
You add shards to asharded clusterafter you create the cluster or any time that you need to add capacity to the cluster.
If you have not created a sharded cluster, seeDeploy a Sharded Cluster(page 635).
In production environments, all shards should bereplica sets.
Considerations
BalancingWhen you add a shard to a sharded cluster, you affect the balance ofchunksamong the shards of a cluster
for all existing sharded collections. The balancer will begin migrating chunks so that the cluster will achieve balance.
SeeSharded Collection Balancing(page 629) for more information.
Capacity PlanningWhen 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 trafc.
Add a Shard to a Cluster
You interact with a sharded cluster by connecting to amongosinstance.
1. mongoshell, connect to themongosinstance. For example, if amongosis accessible at
mongos0.example.net on port27017, issue the following command:
mongo --host mongos0.example.net --port 27017
2. 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 theaddSharddatabase 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, seeaddShard.
The following are examples of adding a shard withsh.addShard():
rs1with a member running on port27017on
mongodb0.example.net , issue the following command:
sh.addShard(
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(
mongodon port27017ofmongodb0.example.net , issue the fol-
lowing command:
sh.addShard(
Note:It might take some time forchunksto migrate to the new shard.
642 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Deploy Three Cong Servers for Production Deployments
This procedure converts a test deployment with only onecong server(page 616) to a production deployment with
three cong servers.
Tip
Use CNAMEs to identify your cong servers to the cluster so that you can rename and renumber your cong servers
without downtime.
For redundancy, all productionsharded clusters(page 607) should deploy three cong servers on three different
machines. Use a single cong server only for testing deployments, never for production deployments. When you shift
to production, upgrade immediately to three cong servers.
To convert a test deployment with one cong server to a production deployment with three cong servers:
1.
mongodinstances orreplica setsthat provide your shards.
mongosinstances in your cluster.
2. dbPathle system tree from the existing cong server to the two machines that will provide the
additional cong servers. These commands, issued on the system with the existingCong Database(page 679),
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
3.
mongod --configsvr
4. mongodandmongosprocesses.
Convert a Replica Set to a Replicated Sharded Cluster
Overview
Following this tutorial, you will convert a single 3-member replica set to a cluster that consists of 2 shards. Each shard
will consist of an independent 3-member replica set.
The tutorial uses a test environment running on a local system UNIX-like system. You should feel encouraged to
follow along at home. If you need to perform this process in a production environment, notes throughout the
document indicate procedural differences.
The procedure, from a high level, is as follows:
1.
2.
3. mongodinstances.
4.
5.
10.3. Sharded Cluster Tutorials 643

MongoDB Documentation, Release 2.6.4
Process
Install MongoDB according to the instructions in theMongoDB Installation Tutorial(page 5).
Deploy a Replica Set with Test DataIf have an existing MongoDBreplica setdeployment, you can omit the this
step and continue fromDeploy Sharding Infrastructure(page 645).
Use the following sequence of steps to congure and deploy a replica set and to insert test data.
1. firstset:
/data/example/firstset1
/data/example/firstset2
/data/example/firstset3
To create directories, issue the following command:
mkdir -p /data/example/firstset1 /data/example/firstset2 /data/example/firstset3
2. mongodinstances by running each of the
following commands:
mongod --dbpath /data/example/firstset1 --port 10001 --replSet firstset --oplogSize 700 --rest
mongod --dbpath /data/example/firstset2 --port 10002 --replSet firstset --oplogSize 700 --rest
mongod --dbpath /data/example/firstset3 --port 10003 --replSet firstset --oplogSize 700 --rest
Note:The--oplogSize 700option restricts the size of the operation log (i.e. oplog) for eachmongod
instance to 700MB. Without the--oplogSizeoption, eachmongodreserves approximately 5% of the free
disk space on the volume. By limiting the size of the oplog, each instance starts more quickly. Omit this setting
in production environments.
3. mongoshell session in a new terminal, connect to the mongodb instance on port 10001 by running the
following command. If you are in a production environment, rst read the note below.
mongo localhost:10001/admin
Note:Above and hereafter, if you are running in a production environment or are testing this process with
mongodinstances on multiple systems, replace localhost with a resolvable domain, hostname, or the IP
address of your system.
4. mongoshell, initialize the rst replica set by issuing the following command:
db.runCommand({"replSetInitiate"
{"_id","_id",},
{"_id",},
{"_id",}
]}})
{
"info",
"ok"
}
5. mongoshell, create and populate a new collection by issuing the following sequence of JavaScript
operations:
644 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
use test
switched to db test
people"Marc",,,,,,,,,,,];
for(vari=0; i<1000000; i++){
nameMath.floor(Math.random() *people.length)];
user_id
boolean=true,false][Math.floor(Math.random() *2)];
added_at newDate();
number.floor(Math.random() *10001);
db.test_collection.save({"name":name,:user_id,: boolean,:added_at,:number });
}
The above operations add one million documents to the collectiontest_collection. This can take several
minutes, depending on your system.
The script adds the documents in the following form:
{"4ed5420b8fc1dd1df5886f70"),,, true,"2011-11-29T20:35:23.121Z"),
Deploy Sharding InfrastructureThis procedure creates the three cong databases that store the cluster's metadata.
Note:For development and testing environments, a single cong database is sufcient. In production environments,
use three cong databases. Because cong instances store only themetadatafor the sharded cluster, they have minimal
resource requirements.
1. cong databaseinstances:
/data/example/config1
/data/example/config2
/data/example/config3
Issue the following command at the system prompt:
mkdir -p /data/example/config1 /data/example/config2 /data/example/config3
2.
commands:
mongod --configsvr --dbpath /data/example/config1 --port 20001
mongod --configsvr --dbpath /data/example/config2 --port 20002
mongod --configsvr --dbpath /data/example/config3 --port 20003
3. mongosinstance by running the following com-
mand:
mongos --configdb localhost:20001,localhost:20002,localhost:20003 --port 27017 --chunkSize 1
Note:If you are using the collection created earlier or are just experimenting with sharding, you can use a
small--chunkSize(1MB works well.) The defaultchunkSizeof 64MB means that your cluster must
have 64MB of data before the MongoDB's automatic sharding begins working.
In production environments, do not use a small shard size.
TheconfigDBoptions specify theconguration databases(e.g. localhost:20001,
localhost:20002, andlocalhost:2003). Themongosinstance runs on the default Mon-
goDB port (i.e.27017), while the databases themselves are running on ports in the30001series. In the this
example, you may omit the--port 27017option, as27017is the default port.
10.3. Sharded Cluster Tutorials 645

MongoDB Documentation, Release 2.6.4
4. mongos. In a new terminal window or GNU Screen session, add the rst shard, according
to the following procedure:
(a) mongoswith the following command:
mongo localhost:27017/admin
(b) addShardcommand:
db.runCommand( { addShard
(c)
{,
Deploy a Second Replica SetThis procedure deploys a second replica set. This closely mirrors the process used to
establish the rst replica set above, omitting the test data.
1. secondset:
/data/example/secondset1
/data/example/secondset2
/data/example/secondset3
2. mongodwith the following commands:
mongod --dbpath /data/example/secondset1 --port 10004 --replSet secondset --oplogSize 700 --rest
mongod --dbpath /data/example/secondset2 --port 10005 --replSet secondset --oplogSize 700 --rest
mongod --dbpath /data/example/secondset3 --port 10006 --replSet secondset --oplogSize 700 --rest
Note:As above, the second replica set uses the smalleroplogSizeMBconguration. Omit this setting in
production environments.
3. mongoshell, connect to one mongodb instance by issuing the following command:
mongo localhost:10004/admin
4. mongoshell, initialize the second replica set by issuing the following command:
db.runCommand({"replSetInitiate"
{"_id",
"members""_id",},
{"_id",},
{"_id",}
]}})
{
"info",
"ok"
}
5. mongosinstance created in the previous procedure and
issue the following sequence of commands:
use admin
db.runCommand( { addShard
This command returns the following success message:
646 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
{,
6. listShardscommand. View this and example
output below:
db.runCommand({listShards:1})
{
"shards"
{
"_id",
"host"
},
{
"_id",
"host"
}
],
"ok"
}
Enable ShardingMongoDB must haveshardingenabled onboththe database and collection levels.
Enabling Sharding on the Database LevelIssue theenableShardingcommand. The following example en-
ables sharding on the test database:
db.runCommand( { enableSharding
{
Create an Index on the Shard KeyMongoDB uses the shard key to distribute documents between shards. Once
selected, you cannot change the shard key. Good shard keys:

Typically shard keys are compound, comprising of some sort of hash and some sort of other primary key. Selecting
a shard key depends on your data set, application architecture, and usage pattern, and is beyond the scope of this
document. For the purposes of this example, we will shard the number key. This typically wouldnotbe a good
shard key for production deployments.
Create the index with the following procedure:
use test
db.test_collection.ensureIndex({number:1})
See also:
TheShard Key Overview(page 620) andShard Key(page 620) sections.
Shard the CollectionIssue the following command:
use admin
db.runCommand( { shardCollection, key"number":1} })
{,
10.3. Sharded Cluster Tutorials 647

MongoDB Documentation, Release 2.6.4
The collectiontest_collectionis now sharded!
Over the next few minutes the Balancer begins to redistribute chunks of documents. You can conrm this activity by
switching to thetestdatabase and runningdb.stats()ordb.printShardingStatus() .
As clients insert additional documents into this collection,mongosdistributes the documents evenly between the
shards.
In themongoshell, issue the following commands to return statics against each cluster:
use test
db.stats()
db.printShardingStatus()
Example output of thedb.stats()command:
{
"raw"
"firstset/localhost:10001,localhost:10003,localhost:10002"
"db",
"collections",
"objects",
"avgObjSize",
"dataSize",
"storageSize",
"numExtents",
"indexes",
"indexSize",
"fileSize",
"nsSizeMB",
"ok"
},
"secondset/localhost:10004,localhost:10006,localhost:10005"
"db",
"collections",
"objects",
"avgObjSize",
"dataSize",
"storageSize",
"numExtents",
"indexes",
"indexSize",
"fileSize",
"nsSizeMB",
"ok"
}
},
"objects",
"avgObjSize",
"dataSize",
"storageSize",
"numExtents",
"indexes",
"indexSize",
"fileSize",
"ok"
}
Example output of thedb.printShardingStatus() command:
648 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
----
sharding version:,
shards:
{,
{,
databases:
{, false,
{, true,
test.test_collection chunks:
secondset
firstset
[...]
In a few moments you can run these commands for a second time to demonstrate thatchunksare migrating from
firstsettosecondset.
When this procedure is complete, you will have converted a replica set into a cluster where each shard is itself a replica
set.
Convert Sharded Cluster to Replica Set
This tutorial describes the process for converting asharded clusterto a non-shardedreplica set. To convert a replica set
into a sharded clusterConvert a Replica Set to a Replicated Sharded Cluster(page 643). See theSharding(page 607)
documentation for more information on sharded clusters.
Convert a Cluster with a Single Shard into a Replica Set
In the case of asharded clusterwith only one shard, that shard contains the full data set. Use the following procedure
to convert that cluster into a non-shardedreplica set:
1.
system will be the new replica set.
2. --shardsrvoption, if yourmongodstarted with this option.
Tip
Changing the--shardsrvoption will change the port thatmongodlistens for incoming connections on.
The single-shard cluster is now a non-shardedreplica setthat 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 asharded clusterwith more than one shard to an entirely newreplica
set.
1. sharded clusterrunning,deploy a new replica set(page 545) in addition to your sharded cluster. The
replica set must have sufcient capacity to hold all of the data les from all of the current shards combined. Do
not congure the application to connect to the new replica set until the data transfer is complete.
2. sharded cluster. You may recongure your application or stop allmongosinstances.
If you stop allmongosinstances, the applications will not be able to read from the database. If you stop all
10.3. Sharded Cluster Tutorials 649

MongoDB Documentation, Release 2.6.4
mongosinstances, start a temporarymongosinstance on that applications cannot access for the data migration
procedure.
3. mongodump and mongorestore(page 234) to migrate the data from themongosinstance to the newreplica
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.
4. replica setinstead of themongosinstance.
The application will now use the un-shardedreplica setfor reads and writes. You may now decommission the remain-
ing unused sharded cluster infrastructure.
10.3.2
The following tutorials provide information in maintaining sharded clusters.
View Cluster Conguration(page 650)View status information about the cluster's databases, shards, and chunks.
Migrate Cong Servers with the Same Hostname(page 652)Migrate a cong server to a new system while keeping
the same hostname. This procedure requires changing the DNS entry to point to the new system.
Migrate Cong Servers with Different Hostnames(page 652)Migrate a cong server to a new system that uses a
new hostname. If possible, avoid changing the hostname and instead use theMigrate Cong Servers with the
Same Hostname(page 652) procedure.
Replace Disabled Cong Server(page 653)Replaces a cong server that has become inoperable. This procedure
assumes that the hostname does not change.
Migrate a Sharded Cluster to Different Hardware(page 654)Migrate a sharded cluster to a different hardware sys-
tem, for example, when moving a pre-production environment to production.
Backup Cluster Metadata(page 657)Create a backup of a sharded cluster's metadata while keeping the cluster op-
erational.
Congure Behavior of Balancer Process in Sharded Clusters(page 657)Manage the balancer's behavior by
scheduling a balancing window, changing size settings, or requiring replication before migration.
Manage Sharded Cluster Balancer(page 659)View balancer status and manage balancer behavior.
Remove Shards from an Existing Sharded Cluster(page 663)Migrate a single shard's data and remove the shard.
View Cluster Conguration
List Databases with Sharding Enabled
To list the databases that have sharding enabled, query thedatabasescollection in theCong Database(page 679).
A database has sharding enabled if the value of thepartitionedeld istrue. Connect to amongosinstance
with amongoshell, and run the following operation to get a full list of databases with sharding enabled:
use config
db.databases.find( {: true} )
Example
You can use the following sequence of commands when to return a list of all databases in the cluster:
650 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
use config
db.databases.find()
If this returns the following result set:
{, false,
{, true,
{, false,
Then sharding is only enabled for theanimalsdatabase.
List Shards
To list the current set of congured shards, use thelistShardscommand, as follows:
use admin
db.runCommand( { listShards
View Cluster Details
To view cluster details, issuedb.printShardingStatus() orsh.status(). Both methods return the same
output.
Example
In the following example output fromsh.status()
sharding versiondisplays the version number of the shard metadata.
shardsdisplays a list of themongodinstances used as shards in the cluster.
databasesdisplays all databases in the cluster, including database that do not have sharding enabled.
chunksinformation for thefoodatabase displays how many chunks are on each shard and displays the
range of each chunk.
----
sharding version:,
shards:
{,
{,
databases:
{, false,
{, true,
foo.contacts
shard key:
chunks:
shard0001
shard0002
shard0000
{>>,
{>>,
{>>,
{>>,
{>>,
{>>,
10.3. Sharded Cluster Tutorials 651

MongoDB Documentation, Release 2.6.4
{>>,
{, false,
Migrate Cong Servers with the Same Hostname
This procedure migrates acong server(page 616) in asharded cluster(page 613) to a new system that usesthe same
hostname.
To migrate all the cong servers in a cluster, perform this procedure for each cong server separately and migrate the
cong servers in reverse order from how they are listed in themongosinstances'configDBstring. Start with the
last cong server listed in theconfigDBstring.
1.
This renders all cong data for the sharded cluster read only.
2. samehostname
points to the new system. How you do this depends on how you organize your DNS and hostname resolution
services.
3. dbPathfrom the old cong server to the new cong server.
For example, to copy the contents ofdbPathto a machine namedmongodb.config2.example.net ,
you might issue a command similar to the following:
rsync -az /data/configdb/ mongodb.config2.example.net:/data/configdb
4.
mongod --configsvr
When you start the third cong server, your cluster will become writable and it will be able to create new splits and
migrate chunks as needed.
Migrate Cong Servers with Different Hostnames
Overview
Sharded clusters use a group of three cong servers to store cluster meta data, and all three cong servers must be
available to support cluster metadata changes that include chunk splits and migrations. If one of the cong servers is
unavailable or inoperable you must replace it as soon as possible.
This procedure migrates acong server(page 616) in asharded cluster(page 613) to a new server that uses a different
hostname. Use this procedure only if the cong serverwill notbe accessible via the same hostname. If possible, avoid
changing the hostname so that you can instead use the procedure tomigrate a cong server and use the same hostname
(page 652).
Considerations
Changing acong server's(page 616) hostnamerequires downtimeand requires restarting every process in the
sharded cluster.
While migrating cong servers always make sure that allmongosinstances have three cong servers specied in the
configDBsetting at all times. Also ensure that you specify the cong servers in the same order for eachmongos
instance'sconfigDBsetting.
652 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Procedure
1. Disable the Balancer(page 661) for more information.
2.
This renders all cong data for the sharded cluster read only.
3. dbPathfrom the old cong server to the new cong server.
Example
To copy the contents ofdbPathto a machine namedmongodb.config2.example.net , use a command
that resembles the following:
rsync -az /data/configdb mongodb.config2.example.net:/data/configdb
4.
mongod --configsvr
5.
mongodinstances orreplica setsthat provide your shards.
mongodinstances that provide your existingcong databases(page 679).
mongosinstances.
6. mongodprocesses that provide the shard servers.
7. configDBsetting for eachmongosinstances.
8. mongosinstances.
9. Disable the Balancer
(page 661) section for more information on managing the balancer process.
Replace Disabled Cong Server
Overview
Sharded clusters use a group of three cong servers to store cluster meta data, and all three cong servers must be
available to support cluster metadata changes that include chunk splits and migrations. If one of the cong servers is
unavailable or inoperable you must replace it as soon as possible.
This procedure replaces an inoperablecong server(page 616) in asharded cluster(page 613). Use this procedure
only to replace a cong 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 tomigrate a cong server and use a new hostname(page 652).
Considerations
In the course of this procedureneverremove a cong server from theconfigDBparameter on any of themongos
instances.
10.3. Sharded Cluster Tutorials 653

MongoDB Documentation, Release 2.6.4
Procedure
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 replacingoryou will need to modify
the DNS records and wait for them to propagate.
Step 2: Shut downoneof the remaining cong servers.Copy all of this host'sdbPathpath from the current
system to the system that will provide the new cong server. This command, issued on the system with the data les,
may resemble the following:
rsync -az /data/configdb mongodb.config2.example.net:/data/configdb
Step 3: If necessary, update DNS and/or networking.Ensure the new cong server is accessible by the same
name as the previous cong server.
Step 4: Start thenewcong server.
mongodconfigsvr
Migrate a Sharded Cluster to Different Hardware
This procedure moves the components of thesharded clusterto a new hardware system without downtime for reads
and writes.
Important:While the migration is in progress, do not attempt to change to thecluster metadata(page 634). Do not
use any operation that modies the cluster metadatain 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 astandalonemongodinstance, considerconverting the standalone to a
replica set(page 556) 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 stopchunk migration(page 630) and do not perform any metadata write operations until the
process nishes. 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'smongosinstances and issue the following method:
sh.stopBalancer()
To check the balancer state, issue thesh.getBalancerState() method.
For more information, seeDisable the Balancer(page 661).
Migrate Each Cong Server Separately
Migrate eachcong server(page 616) by starting with thelastcong server listed in theconfigDBstring. Proceed
in reverse order of theconfigDBstring. Migrate and restart a cong server before proceeding to the next. Do not
rename a cong server during this process.
654 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Note:If the name or address that a sharded cluster uses to connect to a cong server changes, you must restartevery
mongodandmongosinstance in the sharded cluster. Avoid downtime by using CNAMEs to identify cong servers
within the MongoDB deployment.
SeeMigrate Cong Servers with Different Hostnames(page 652) for more information.
Important:Start with thelastcong server listed inconfigDB.
1.
This renders all cong data for the sharded cluster read only.
2. samehostname
points to the new system. How you do this depends on how you organize your DNS and hostname resolution
services.
3. dbPathfrom the old cong server to the new cong server.
For example, to copy the contents ofdbPathto a machine namedmongodb.config2.example.net ,
you might issue a command similar to the following:
rsync -az /data/configdb/ mongodb.config2.example.net:/data/configdb
4.
mongod --configsvr
Restart themongosInstances
If theconfigDBstring will change as part of the migration, you must shut downallmongosinstances before
changing theconfigDBstring. This avoids errors in the sharded cluster overconfigDBstring conicts.
If theconfigDBstring will remain the same, you can migrate themongosinstances sequentially or all at once.
1. mongosinstances using theshutdowncommand. If theconfigDBstring is changing, shut
downallmongosinstances.
2. configDBstring for eachmongos
instance. Themongosinstances must all use the sameconfigDBstring. The strings must list identical host
names in identical order.
Tip
To avoid downtime, give each cong server a logical DNS name (unrelated to the server's physical or virtual
hostname). Without logical DNS names, moving or renaming a cong server requires shutting down every
mongodandmongosinstance in the sharded cluster.
3. mongosinstances being sure to use the updatedconfigDBstring if hostnames have changed.
For more information, seeStart the mongos Instances(page 636).
Migrate the Shards
Migrate the shards one at a time. For each shard, follow the appropriate procedure in this section.
10.3. Sharded Cluster Tutorials 655

MongoDB Documentation, Release 2.6.4
Migrate a Replica Set ShardTo migrate a sharded cluster, migrate each member separately. First migrate the
non-primary members, and then migrate theprimarylast.
If the replica set has two voting members, add anarbiter(page 515) 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
1. mongodprocess. To ensure a clean shutdown, use theshutdowncommand.
2. dbPath) to the new machine.
3. mongodprocess at the new location.
4.
5. rs.reconfig()to update thereplica set conguration
document(page 594) with the new hostname.
For example, the following sequence of commands updates the hostname for the instance at position2in the
membersarray:
cfg
cfg.members[2].host
rs.reconfig(cfg)
For more information on updating the conguration document, seereplica-set-reconguration-usage.
6. rs.conf().
7. rs.status().
Migrate the Primary in a Replica Set ShardWhile 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.
1. failover(page 523) process. To step down the primary, connect to
the primary and issue the either thereplSetStepDowncommand or thers.stepDown()method. The
following example shows thers.stepDown()method:
rs.stepDown()
2. PRIMARY(page 601) state. To migrate
the stepped-down primary, follow theMigrate a Member of a Replica Set Shard(page 656) procedure
You can check the output ofrs.status()to conrm the change in status.
Migrate a Standalone ShardThe ideal procedure for migrating a standalone shard is toconvert the standalone to a
replica set(page 556) and then use the procedure formigrating a replica set shard(page 656). 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 theprimary shardfor a database,the process includes themovePrimarycommand. While themovePrimary
runs, you should stop modifying data in that database. To migrate the standalone shard, use theRemove Shards from
an Existing Sharded Cluster(page 663) procedure.
656 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Re-Enable the Balancer
To complete the migration, re-enable the balancer to resumechunk migrations(page 630).
Connect to one of the cluster'smongosinstances and passtrueto thesh.setBalancerState() method:
sh.setBalancerState(true)
To check the balancer state, issue thesh.getBalancerState() method.
For more information, seeEnable the Balancer(page 661).
Backup Cluster Metadata
This procedure shuts down themongodinstance of acong server(page 616) in order to create a backup of asharded
cluster's(page 607) metadata. The cluster's cong servers store all of the cluster's metadata, most importantly the
mapping fromchunkstoshards.
When you perform this procedure, the cluster remains operational
8
.
1. Disable the Balancer(page 661) for more information.
2.
3. dbPathoption for the cong instance.)
4.
5. Disable the Balancer
(page 661) section for more information on managing the balancer process.
See also:
MongoDB Backup Methods(page 172).
Congure Behavior of Balancer Process in Sharded Clusters
The balancer is a process that runs ononeof themongosinstances in a cluster and ensures thatchunksare evenly
distributed throughout a sharded cluster. In most deployments, the default balancer conguration is sufcient 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, seeSharded Collection Balancing(page 629) andCluster Balancer
(page 629).
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(page 660)
Remove a Balancing Window Schedule(page 660).
Themongosinstances use their own local timezones when respecting balancer window.
8
While one of the three cong 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. SeeCong Servers(page 616) for more information.
10.3. Sharded Cluster Tutorials 657

MongoDB Documentation, Release 2.6.4
Congure 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, seeChunk Size
(page 633).
Changing the default chunk size affects chunks that are processes during migrations and auto-splits but does not
retroactively affect all chunks.
To congure default chunk size, seeModify Chunk Size in a Sharded Cluster(page 671).
Change the Maximum Storage Size for a Given Shard
ThemaxSizeeld in theshards(page 684) collection in thecong database(page 679) sets the maximum size
for a shard, allowing you to control whether the balancer will migrate chunks to a shard. Ifmappedsize
9
is above
a shard'smaxSize, the balancer will not move chunks to the shard. Also, the balancer will not move chunks off an
overloaded shard. This must happen manually. ThemaxSizevalue only affects the balancer's selection of destination
shards.
By default,maxSizeis not specied, allowing shards to consume the total amount of available space on their ma-
chines if necessary.
You can setmaxSizeboth when adding a shard and once a shard is running.
To setmaxSizewhen adding a shard, set theaddShardcommand'smaxSizeparameter to the maximum size in
megabytes. For example, the following command run in themongoshell adds a shard with a maximum size of 125
megabytes:
db.runCommand( { addshard, maxSize
To setmaxSizeon an existing shard, insert or update themaxSizeeld in theshards(page 684) collection in the
cong database(page 679). Set themaxSizein megabytes.
Example
Assume you have the following shard without amaxSizeeld:
{,
Run the following sequence of commands in themongoshell to insert amaxSizeof 125 megabytes:
use config
db.shards.update( { _id
To later increase themaxSizesetting to 250 megabytes, run the following:
use config
db.shards.update( { _id
Change Replication Behavior for Chunk Migration (Secondary Throttle)
The_secondaryThrottle parameter of the balancer and themoveChunkcommand affects the replication be-
havior duringchunk migration(page 632). By default,_secondaryThrottle istrue, which means each doc-
ument move during chunk migration propagates to at least one secondary before the balancer proceeds with its next
9
This value includes the mapped size of all data les including the``local`` andadmindatabases. Account for this when settingmaxSize.
658 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
operation. For more information on the replication behavior during various steps of chunk migration, seeChunk
Migration and Replication(page 632).
To change the balancer's_secondaryThrottle value, connect to amongosinstance and directly update the
_secondaryThrottle value in thesettings(page 683) collection of thecong database(page 679). For
example, from amongoshell connected to amongos, issue the following command:
use config
db.settings.update(
{
{ $set 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. SeeManage Sharded Cluster
Balancer(page 659) for details.
Manage Sharded Cluster Balancer
This page describes common administrative procedures related to balancing. For an introduction to balancing, see
Sharded Collection Balancing(page 629). For lower level information on balancing, seeCluster Balancer(page 629).
See also:
Congure Behavior of Balancer Process in Sharded Clusters(page 657)
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 yourcluster, issue the following command, which returns a boolean:
sh.getBalancerState()
Check the Balancer Lock
To see if the balancer process is active in yourcluster, do the following:
1. mongosin the cluster using themongoshell.
2. Cong Database(page 679):
use config
3.
db.locks.find( { _id
When this command returns, you will see output like the following:
{,
"process",
"state",
"ts""4d0f872630c42d1978be8a2e"),
"when",
10.3. Sharded Cluster Tutorials 659

MongoDB Documentation, Release 2.6.4
"who",
"why"
This output conrms that:
mongosrunning on the system with the hostname
mongos0.example.net.
stateeld indicates that amongoshas the lock. For version 2.0 and later, the value of an
active lock is2; for earlier versions the value is1.
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 thebalancerwill be able to migrate chunks:
1. mongosin the cluster using themongoshell.
2. Cong Database(page 679):
use config
3. stoppedstate:
sh.setBalancerState(
The balancer will not activate if in thestoppedstate or outside theactiveWindowtimeframe.
4. update()operation to modify the balancer's window:
db.settings.update({ _id, stop 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 individualmongosinstance in the sharded cluster. If yourmongosinstances
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, stop true)
Note:The balancer window must be sufcient tocompletethe 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 sufcient to support the needs of your deployment.
Do not use thesh.startBalancer() method when you have set anactiveWindow.
Remove a Balancing Window Schedule
If you haveset the balancing window(page 660) 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 true} })
660 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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:
1. mongosin the cluster using themongoshell.
2.
sh.stopBalancer()
If a migration is in progress, the system will complete the in-progress migration before stopping.
3. falseif the balancer is
disabled:
sh.getBalancerState()
Optionally, to verify no migrations are in progress after disabling, issue the following operation in themongo
shell:
use config
while( sh.isBalancerRunning() ) {
print("waiting...");
sleep(1000);
}
Note: To disable the balancer from a driver that does not have thesh.stopBalancer() or
sh.setBalancerState() helpers, issue the following command from theconfigdatabase:
db.settings.update( { _id:: true} } ,true)
Enable the Balancer
Use this procedure if you have disabled the balancer and are ready to re-enable it:
1. mongosin the cluster using themongoshell.
2.
From themongoshell, issue:
sh.setBalancerState(true)
From a driver that does not have thesh.startBalancer() helper, issue the following from theconfig
database:
db.settings.update( { _id:: false} } ,true)
Disable Balancing During Backups
If MongoDB migrates achunkduring abackup(page 172), you can end with an inconsistent snapshot of yoursharded
cluster. Never run a backup while the balancer is active. To ensure that the balancer is inactive during your backup
operation:
balancing window(page 660) so that the balancer is inactive during the backup. Ensure that the backup
can complete while you have the balancer disabled.
10.3. Sharded Cluster Tutorials 661

MongoDB Documentation, Release 2.6.4
manually disable the balancer(page 661) 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, conrm 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 specic collection with thesh.disableBalancing() method. You may want
to disable the balancer for a specic 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 amongoswith themongoshell and call the
sh.disableBalancing() method.
For example:
sh.disableBalancing("students.grades")
Thesh.disableBalancing() method accepts as its parameter the fullnamespaceof the collection.
Enable Balancing on a Collection
You can enable balancing for a specic collection with thesh.enableBalancing() method.
When you enable balancing for a collection, MongoDB will notimmediatelybegin 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 amongoswith themongoshell and call the
sh.enableBalancing() method.
For example:
sh.enableBalancing("students.grades")
Thesh.enableBalancing() method accepts as its parameter the fullnamespaceof the collection.
Conrm Balancing is Enabled or Disabled
To conrm whether balancing for a collection is enabled or disabled, query thecollectionscollection in the
configdatabase for the collectionnamespaceand check thenoBalanceeld. For example:
db.getSiblingDB("config").collections.findOne({_id}).noBalance;
This operation will return a null error,true,false, or no output:

true, balancing is disabled.
662 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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.

collection. Balancing of this collection will begin the next time the balancer runs.
Remove Shards from an Existing Sharded Cluster
To remove ashardyou 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 asingleshard.Do notuse 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, rst connect to one of the cluster'smongosinstances usingmongoshell. 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, thebalancerprocessmustbe enabled. Check the balancer state using
thesh.getBalancerState() helper in themongoshell. For more information, see the section onbalancer
operations(page 661).
Determine the Name of the Shard to Remove
To determine the name of the shard, connect to amongosinstance with themongoshell and either:
listShardscommand, as in the following:
db.adminCommand( { listShards:
sh.status()or thedb.printShardingStatus() method.
Theshards._ideld lists the name of each shard.
Remove Chunks from the Shard
From theadmindatabase, run theremoveShardcommand. This begins draining chunks from the shard you are
removing to other shards in the cluster. For example, for a shard namedmongodb0, run:
use admin
db.runCommand( { removeShard:
This operation returns immediately, with the following response:
{
"msg",
"state",
"shard",
"ok"
}
Depending on your network capacity and the amount of data, this operation can take from a few minutes to several
days to complete.
10.3. Sharded Cluster Tutorials 663

MongoDB Documentation, Release 2.6.4
Check the Status of the Migration
To check the progress of the migration at any stage in the process, runremoveShardfrom theadmindatabase
again. For example, for a shard namedmongodb0, run:
use admin
db.runCommand( { removeShard:
The command returns output similar to the following:
{
"msg",
"state",
"remaining"
"chunks",
"dbs"
},
"ok"
}
In the output, theremainingdocument 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 theremoveShardcommand until the number of chunks remaining is0. Always run the
command on theadmindatabase. If you are on a database other thanadmin, you can usesh._adminCommand
to run the command onadmin.
Move Unsharded Data
If the shard is theprimary shardfor 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(page 665).
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 nished draining the shard.
1.
the following methods:
sh.status()
db.printShardingStatus()
In the resulting document, thedatabaseseld lists each database and its primary shard. For example, the
followingdatabaseeld shows that theproductsdatabase usesmongodb0as the primary shard:
{, true,
2. movePrimarycommand. For example, to migrate all remaining
unsharded data frommongodb0tomongodb1, issue the following command:
db.runCommand( { movePrimary:, to:
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:
{,
664 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Finalize the Migration
To clean up all metadata information and nalize the removal, runremoveShardagain. For example, for a shard
namedmongodb0, run:
use admin
db.runCommand( { removeShard:
A success message appears at completion:
{
"msg",
"state",
"shard",
"ok"
}
Once the value of thestateeld is completed, you may safely stop the processes comprising themongodb0
shard.
See also:
Backup and Restore Sharded Clusters(page 238)
10.3.3
The following documents provide information in managing data in sharded clusters.
Create Chunks in a Sharded Cluster(page 665)Create chunks, orpre-splitempty collection to ensure an even dis-
tribution of chunks during data ingestion.
Split Chunks in a Sharded Cluster(page 666)Manually create chunks in a sharded collection.
Migrate Chunks in a Sharded Cluster(page 667)Manually migrate chunks without using the automatic balance
process.
Merge Chunks in a Sharded Cluster(page 668)Use themergeChunksto manually combine chunk ranges.
Modify Chunk Size in a Sharded Cluster(page 671)Modify the default chunk size in a sharded collection
Tag Aware Sharding(page 671)Tags associate specic ranges ofshard keyvalues with specic shards for use in
managing deployment patterns.
Manage Shard Tags(page 672)Use tags to associate specic ranges of shard key values with specic shards.
Enforce Unique Keys for Sharded Collections(page 674)Ensure that a eld is always unique in all collections in a
sharded cluster.
Shard GridFS Data Store(page 676)Choose whether to shard GridFS data in a sharded collection.
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 asharded clusterwill create and distribute chunks automatically without user interven-
tion. However, in a limited number of cases, MongoDB cannot create enough chunks or distribute data fast enough to
support required throughput. For example:

10.3. Sharded Cluster Tutorials 665

MongoDB Documentation, Release 2.6.4

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:

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 inefcient or ineffective balancing behavior.
To create chunks manually, use the following procedure:
1. splitcommand on chunks.
Example
To create chunks for documents in themyapp.userscollection using theemaileld as theshard key, use
the following operation in themongoshell:
for(varx=97; x<97+26; x++
for(vary=97; y<97+26; y+=6
varprefix.fromCharCode(x).fromCharCode(y);
db.runCommand( { split
}
}
This assumes a collection size of 100 million documents.
For information on the balancer and automatic distribution of chunks across shards, seeCluster Balancer
(page 629) andChunk Migration(page 631). For information on manually migrating chunks, seeMigrate
Chunks in a Sharded Cluster(page 667).
Split Chunks in a Sharded Cluster
Normally, MongoDB splits achunkafter an insert if the chunk exceeds the maximumchunk size(page 633). However,
you may want to split chunks manually if:
chunks, as is the case after deploying a cluster
using existing data.

plan to insert a large amount of data withshard keyvalues between300and400,butall values of your shard
keys are between250and500are in a single chunk.
Note:New in version 2.6: MongoDB provides themergeChunkscommand to combine contiguous chunk ranges
into a single chunk. SeeMerge Chunks in a Sharded Cluster(page 668) for more information.
Thebalancermay migrate recently split chunks to a new shard immediately ifmongospredicts future insertions will
benet from the move. The balancer does not distinguish between chunks split manually and those split automatically
by the system.
666 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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.
Usesh.status()to determine the current chunk ranges across the cluster.
To split chunks manually, use thesplitcommand with either eldsmiddleorfind. Themongoshell provides
the helper methodssh.splitFind()andsh.splitAt().
splitFind()splits the chunk that contains therstdocument returned that matches this query into two equally
sized chunks. You must specify the full namespace (i.e. <database>.<collection> ) of the sharded collection
tosplitFind(). The query insplitFind()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 of63109for thezipcodeeld in thepeople
collection of therecordsdatabase:
sh.splitFind(, {:
UsesplitAt()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 of63109for thezipcodeeld in thepeople
collection of therecordsdatabase.
sh.splitAt(, {:
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 automaticbalancermigratechunksbetweenshards. However, you may
want to migrate chunks manually in a few cases:
pre-splittingan empty collection, migrate chunks manually to distribute them evenly across the shards.
Use pre-splitting in limited situations to support bulk data ingestion.
balancing window(page 660), then you
will have to migrate chunks manually.
To manually migrate chunks, use themoveChunkcommand. For more information on how the automatic balancer
moves chunks between shards, seeCluster Balancer(page 629) andChunk Migration(page 631).
Example
Migrate a single chunk
The following example assumes that the eldusernameis theshard keyfor a collection namedusersin the
myappdatabase, and that the valuesmithexists within thechunkto migrate. Migrate the chunk using the following
10.3. Sharded Cluster Tutorials 667

MongoDB Documentation, Release 2.6.4
command in themongoshell.
db.adminCommand( { moveChunk,
find},
to
This command moves the chunk that includes the shard key value smith to the shardnamed
mongodb-shard3.example.net . The command will block until the migration is complete.
Tip
To return a list of shards, use thelistShardscommand.
Example
Evenly migrate chunks
To evenly migrate chunks for themyapp.userscollection, put each prex chunk on the next shard from the other
and run the following commands in the mongo shell:
varshServer,,,,
for(varx=97; x<97+26; x++
for(vary=97; y<97+26; y+=6
varprefix.fromCharCode(x).fromCharCode(y);
db.adminCommand({moveChunk, find-97)/6]})
}
}
SeeCreate Chunks in a Sharded Cluster(page 665) for an introduction to pre-splitting.
New in version 2.2: ThemoveChunkcommand has the:_secondaryThrottle parameter. When set totrue,
MongoDB ensures that changes to shards as part of chunk migrations replicate tosecondariesthroughout the migra-
tion operation. For more information, seeChange Replication Behavior for Chunk Migration (Secondary Throttle)
(page 658).
Changed in version 2.4: In 2.4,_secondaryThrottle istrueby default.
Warning:ThemoveChunkcommand may produce the following error message:
The collections metadata lock is already taken.
This occurs when clients have too many opencursorsthat 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
ThemergeChunkscommand allows you to collapse empty chunks into neighboring chunks on the same shard. A
chunkis empty if it has no documents associated with its shard key range.
Important:Emptychunkscan make thebalancerassess the cluster as properly balanced when it is not.
Empty chunks can occur under various circumstances, including:
668 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
pre-split(page 665) creates too many chunks, the distribution of data to chunks may be uneven.

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 auserscollectionin thetestdatabase, using theusernameled as a
shard key.
Identify Chunk RangesIn themongoshell, identify thechunkranges with the following operation:
sh.status()
The output of thesh.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:
10.3. Sharded Cluster Tutorials 669

MongoDB Documentation, Release 2.6.4
chunks:
shard0000 7
shard0001 7
Chunk range:
{ "username" : "user36583" } -->> { "username" : "user43229" } on : shard0000 Timestamp(6, 0)
Verify a Chunk is EmptyThemergeChunkscommand requires at least one empty input chunk. In themongo
shell, check the amount of data in a chunk using an operation that resembles:
db.runCommand({
"dataSize":,
"keyPattern"::
"min"::
"max"::
})
If the input chunk todataSizeis empty,dataSizeproduces output similar to:
{,,,
Merge ChunksMerge two contiguouschunkson the sameshard, where at least one of the contains no data, with an
operation that resembles the following:
db.runCommand( { mergeChunks:,
bounds::
{:
} )
On success,mergeChunksproduces the following output:
{
On any failure condition,mergeChunksreturns a document where the value of theokeld is0.
View Merged Chunks RangesAfter merging all empty chunks, conrm the new chunk, as follows:
sh.status()
The output ofsh.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
670 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
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 rstmongosconnects to a set ofcong 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:
1. mongosin the cluster using themongoshell.
2. Cong Database(page 679):
use config
3. save()operation to store the global chunk size conguration value:
db.settings.save( { _id:"chunksize", value:sizeInMB>
Note:ThechunkSizeand--chunkSizeoptions, passed at runtime to themongos,do notaffect the chunk size
after you have initialized the cluster.
To avoid confusion,alwaysset the chunk size using the above procedure instead of the runtime options.
Modifying the chunk size has several limitations:

size.

Tag Aware Sharding
MongoDB supports tagging a range ofshard keyvalues 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:

This document describes the behavior, operation, and use of tag aware sharding in MongoDB deployments.
10.3. Sharded Cluster Tutorials 671

MongoDB Documentation, Release 2.6.4
Considerations
Shard keyrange tags are distinct fromreplica set member tags(page 532).
Hash-based shardingdoes not support tag-aware sharding.

Behavior and Operations
The balancer migrates chunks of documents in a sharded collections to the shards associated with a tag that has ashard
keyrange with anupperboundgreaterthan the chunk'slowerbound.
During balancing rounds, if the balancer detects that any chunks violate congured tags, the balancer migrates chunks
in tagged ranges to shards associated with those tags.
After conguring 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 congured, the balancer respects tag ranges during futurebalancing rounds(page 629).
See also:
Manage Shard Tags(page 672)
Chunks that Span Multiple Tag Ranges
A single chunk may contain data with ashard keyvalues that falls into ranges associated with more than one tag. To
accommodate these situations, the balancer may migrate chunks to shards that contain shard key values that exceed
the upper bound of the selected tag range.
Example
Given a sharded collection with two congured tag ranges:
Shard keyvalues between100and200have tags to direct corresponding chunks to shards taggedNYC.
200and300have tags to direct corresponding chunks to shards taggedSFO.
For this collection cluster, the balancer will migrate a chunk withshard keyvalues ranging between150and220to
a shard taggedNYC, since150is closer to200than300.
To ensure that your collection has no potentially ambiguously tagged chunks,create splits on your tag boundaries
(page 666). You can then manually migrate chunks to the appropriate shards, or wait for the balancer to automatically
migrate these chunks.
Manage Shard Tags
In a sharded cluster, you can use tags to associate specic ranges of ashard keywith a specicshardor subset of
shards.
672 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Tag a Shard
Associate tags with a particular shard using thesh.addShardTag()method when connected to amongosin-
stance. A single shard may have multiple tags, and multiple shards may also have the same tag.
Example
The following example adds the tagNYCto two shards, and the tagsSFOandNRTto a third shard:
sh.addShardTag("shard0000",)
sh.addShardTag("shard0001",)
sh.addShardTag("shard0002",)
sh.addShardTag("shard0002",)
You may remove tags from a particular shard using thesh.removeShardTag() method when connected to a
mongosinstance, as in the following example, which removes theNRTtag from a shard:
sh.removeShardTag("shard0002",)
Tag a Shard Key Range
To assign a tag to a range of shard keys use thesh.addTagRange()method when connected to amongosinstance.
Any given shard key range may only haveoneassigned tag. You cannot overlap dened ranges, or tag the same range
more than once.
Example
Given a collection namedusersin therecordsdatabase, sharded by thezipcodeeld. The following operations
assign:
NYCtag
SFOtag
sh.addTagRange("records.users", { zipcode::)
sh.addTagRange("records.users", { zipcode::)
sh.addTagRange("records.users", { zipcode::)
Note:Shard ranges are always inclusive of the lower value and exclusive of the upper boundary.
Remove a Tag From a Shard Key Range
Themongoddoes 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 thetags(page 684) collection of theconfigdatabase.
Each document in thetags(page 684) holds thenamespaceof the sharded collection and a minimum shard key
value.
Example
The following example removes theNYCtag assignment for the range of zip codes within Manhattan:
use config
db.tags.remove({ _id::, min:::
10.3. Sharded Cluster Tutorials 673

MongoDB Documentation, Release 2.6.4
View Existing Shard Tags
The output fromsh.status()lists tags associated with a shard, if any, for each shard. A shard's tags exist in the
shard's document in theshards(page 684) collection of theconfigdatabase. To return all shards with a specic
tag, use a sequence of operations that resemble the following, which will return only those shards tagged withNYC:
use config
db.shards.find({ tags:
You can nd tag ranges for allnamespacesin thetags(page 684) collection of theconfigdatabase. The output of
sh.status()displays all tag ranges. To return all shard key ranges tagged withNYC, use the following sequence
of operations:
use config
db.tags.find({ tags:
Enforce Unique Keys for Sharded Collections
Overview
Theuniqueconstraint on indexes ensures that only one document can have a value for a eld in acollection. For
sharded collections these unique indexes cannot enforce uniquenessbecause insert and indexing operations are local
to each shard.
MongoDB does not support creating new unique indexes in sharded clusters and will not allow you to shard collections
with unique indexes on elds other than the_ideld.
If you need to ensure that a eld is always unique in all collections in a sharded environment, there are three options:
1. shard key(page 620).
MongoDBcanenforce uniqueness for theshard key. For compound shard keys, MongoDB will enforce unique-
ness on theentirekey combination, and not for a specic component of the shard key.
You cannot specify a unique constraint on ahashed index(page 455).
2.
Create a minimal collection that only contains the unique eld and a reference to a document in the main
collection. If you always insert into a secondary collectionbeforeinserting 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.
3.
Universally unique identiers (i.e. UUID) like theObjectIdare guaranteed to be unique.
Procedures
Unique Constraints on the Shard Key
ProcessTo shard a collection using theuniqueconstraint, specify theshardCollectioncommand in the
following form:
674 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
db.runCommand( { shardCollection true} );
Remember that the_ideld index is always unique. By default, MongoDB inserts anObjectIdinto the_ideld.
However, you can manually insert your own value into the_ideld and use this as the shard key. To use the_id
eld as the shard key, use the following operation:
db.runCommand( { shardCollection
Limitations

combinationof component keys in
the shard key.
In most cases, the best shard keys are compound keys that include elements that permitwrite scaling(page 621) and
query isolation(page 622), as well ashigh cardinality(page 640). 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 FieldsIf you cannot use a unique eld as the shard key or if you need to enforce
uniqueness over multiple elds, you must create anothercollectionto act as a proxy collection. This collection must
contain both a reference to the original document (i.e. itsObjectId) and the unique key.
If you must shard this proxy collection, then shard on the unique key using theabove procedure(page 674); other-
wise, you can simply create multiple unique indexes on the collection.
ProcessConsider the following for the proxy collection:
{
"_id" : ObjectId("...")
"email" ": "..."
}
The_ideld holds theObjectIdof thedocumentit reects, and theemaileld is the eld on which you want to
ensure uniqueness.
To shard this collection, use the following operation using theemaileld as theshard key:
db.runCommand( { shardCollection
key
unique true} );
If you do not need to shard the proxy collection, use the following command to create a unique index on theemail
eld:
db.proxy.ensureIndex( { true} )
You may create multiple unique indexes on this collection if you do not plan to shard theproxycollection.
To insert documents, use the following procedure in theJavaScript shell:
dbrecords);
varprimary_id
db.proxy.insert({
"_id"
"email"
10.3. Sharded Cluster Tutorials 675

MongoDB Documentation, Release 2.6.4
})
// if: the above operation returns successfully,
// then continue:
db.information.insert({
"_id"
"email":
// additional information...
})
You must insert a document into theproxycollection rst. If this operation succeeds, theemaileld is unique, and
you may continue by inserting the actual document into theinformationcollection.
See
The full documentation of:ensureIndex()andshardCollection.
Considerations

consistency between the two collections.

uniqueness.
oneproxy col-
lection foreveryeld for which to enforce uniqueness. If you create multiple unique indexes on a single proxy
collection, you willnotbe able to shard proxy collections.
Use Guaranteed Unique IdentierThe best way to ensure a eld has unique values is to generate universally
unique identiers (UUID,) such as MongoDB's `ObjectIdvalues.
This approach is particularly useful for the``_id`` eld, whichmustbe unique: for collections where you arenot
sharding by the_ideld the application is responsible for ensuring that the_ideld is unique.
Shard GridFS Data Store
When sharding aGridFSstore, consider the following:
filesCollection
Most deployments will not need to shard thefilescollection. Thefilescollection 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 youmustshard thefilescollection, use the_ideld possibly in combination with an application eld.
Leavingfilesunsharded means that all the le metadata documents live on one shard. For production GridFS stores
youmuststore thefilescollection on a replica set.
chunksCollection
To shard thechunkscollection by{ files_id : 1 , n : 1 } , issue commands similar to the following:
676 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
db.fs.chunks.ensureIndex( { files_id
db.runCommand( { shardCollection
You may also want to shard using just thefile_ideld, as in the following operation:
db.runCommand( { shardCollection
Important:{ files_id : 1 , n : 1 } and{ files_id : 1 } are theonlysupported shard keys
for thechunkscollection of a GridFS store.
Note:Changed in version 2.2.
Before 2.2, you had to create an additional index onfiles_idto shard usingonlythis eld.
The defaultfiles_idvalue is anObjectId, as a result the values offiles_idare always ascending, and applica-
tions 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_idin thefilescollection.
10.3.4
This section describes common strategies for troubleshootingsharded clusterdeployments.
Cong Database String Error
Start allmongosinstances in a sharded cluster with an identicalconfigDBstring. If amongosinstance tries
to connect to the sharded cluster with aconfigDBstring that does notexactlymatch the string used by the other
mongosinstances, 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 themongoswith the correct string.
Cursor Fails Because of Stale Cong Data
A query returns the following warning when one or more of themongosinstances has not yet updated its cache of
the cluster's metadata from thecong database:
could not initialize cursor across all shards because : stale config detected
This warningshouldnot propagate back to your application. The warning will repeat until all themongosinstances
refresh their caches. To force an instance to refresh its cache, run theflushRouterConfigcommand.
Avoid Downtime when Moving Cong Servers
Use CNAMEs to identify your cong servers to the cluster so that you can rename and renumber your cong servers
without downtime.
10.3. Sharded Cluster Tutorials 677

MongoDB Documentation, Release 2.6.4
10.4
10.4.1 mongoShell
Name Description
sh._adminCommand Runs adatabase commandagainst the admin database, likedb.runCommand(), but
can conrm that it is issued against amongos.
sh._checkFullName()Tests a namespace to determine if its well formed.
sh._checkMongos()Tests to see if themongoshell is connected to amongosinstance.
sh._lastMigration()Reports on the lastchunkmigration.
sh.addShard() Adds ashardto a sharded cluster.
sh.addShardTag() Associates a shard with a tag, to supporttag aware sharding(page 671).
sh.addTagRange() Associates range of shard keys with a shard tag, to supporttag aware sharding
(page 671).
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 specic database.
sh.getBalancerHost()Returns the name of amongosthat's responsible for the balancer process.
sh.getBalancerState()Returns a boolean to report if thebalanceris currently enabled.
sh.help() Returns help text for theshmethods.
sh.isBalancerRunning()Returns a boolean to report if the balancer process is currently migrating chunks.
sh.moveChunk() Migrates achunkin asharded cluster.
sh.removeShardTag()Removes the association between a shard and a shard tag.
sh.setBalancerState()Enables or disables thebalancerwhich migrateschunksbetweenshards.
sh.shardCollection()Enables sharding for a collection.
sh.splitAt() Divides an existingchunkinto two chunks using a specic value of theshard keyas the
dividing point.
sh.splitFind() Divides an existingchunkthat contains a document matching a query into two
approximately equal chunks.
sh.startBalancer()Enables thebalancerand waits for balancing to start.
sh.status() Reports on the status of asharded cluster, asdb.printShardingStatus() .
sh.stopBalancer()Disables thebalancerand 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 specied distributedsharded clusterlock.
sh.waitForPingChange()Internal. Waits for a change in ping state from one of themongosin the sharded cluster.
10.4.2
The following database commands supportsharded clusters.
678 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Name Description
addShard Adds ashardto asharded cluster.
checkShardingIndexInternal command that validates index on shard key.
cleanupOrphaned Removes orphaned data with shard key values outside of the ranges of the chunks
owned by a shard.
enableSharding Enables sharding on a specic database.
flushRouterConfig Forces an update to the cluster metadata cached by amongos.
getShardMap Internal command that reports on the state of a sharded cluster.
getShardVersion Internal command that returns thecong serverversion.
isdbgrid Veries that a process is amongos.
listShards Returns a list of congured shards.
medianKey Deprecated internal command. SeesplitVector.
mergeChunks Provides the ability to combine chunks on a single shard.
moveChunk Internal command that migrates chunks between shards.
movePrimary Reassigns theprimary shardwhen removing a shard from a sharded cluster.
removeShard Starts the process of removing a shard from a sharded cluster.
setShardVersion Internal command to sets thecong serverversion.
shardCollection Enables the sharding functionality for a collection, allowing the collection to be
sharded.
shardingState Reports whether themongodis a member of a sharded cluster.
splitChunk Internal command to split chunk. Instead use the methodssh.splitFind()and
sh.splitAt().
splitVector Internal command that determines split points.
split Creates a newchunk.
unsetSharding Internal command that affects connections between instances in a MongoDB
deployment.
10.4.3
Cong Database(page 679)Complete documentation of the content of thelocaldatabase that MongoDB uses to
store sharded cluster metadata.
Cong Database
Theconfigdatabase supportssharded clusteroperation. See theSharding(page 607) section of this manual for full
documentation of sharded clusters.
Important:Consider the schema of theconfigdatabaseinternaland may change between releases of MongoDB.
Theconfigdatabase is not a dependable API, and users should not write data to theconfigdatabase in the course
of normal operation or maintenance.
Warning:Modication of theconfigdatabase on a functioning system may lead to instability or inconsistent
data sets. If you must modify theconfigdatabase, usemongodumpto create a full backup of theconfig
database.
To access theconfigdatabase, connect to amongosinstance 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
10.4. Sharding Reference 679

MongoDB Documentation, Release 2.6.4
Collections
config
config.changelog
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thechangelog(page 680) collection stores a document for each change to the metadata of a sharded collec-
tion.
Example
The following example displays a single record of a chunk split from achangelog(page 680) collection:
{
"_id",
"server",
"clientAddr",
"time""2012-12-11T14:09:21.039Z"),
"what",
"ns",
"details"
"before"
"min"
"<database>"
},
"max"
"<database>"
},
"lastmod"1000,),
"lastmodEpoch""000000000000000000000000")
},
"left"
"min"
"<database>"
},
"max"
"<database>"
},
"lastmod"1000,),
"lastmodEpoch"<...>)
},
"right"
"min"
"<database>"
},
"max"
"<database>"
},
"lastmod"1000,),
"lastmodEpoch""<...>")
}
}
}
680 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Each document in thechangelog(page 680) collection contains the following elds:
config.changelog._id
The value ofchangelog._idis:<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, amongosinstance that initiates this change.
config.changelog.time
AISODatetimestamp that reects when the change occurred.
config.changelog.what
Reects 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
Adocumentthat contains additional details regarding the change. The structure of thedetails
(page 681) document depends on the type of change.
config.chunks
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thechunks(page 681) collection stores a document for each chunk in the cluster. Consider the following
example of a document for a chunk namedrecords.pets-animal_\"cat\" :
{
"_id",
"lastmod"1000,),
"lastmodEpoch""5078407bd58b175c5c225fdc"),
"ns",
"min"
"animal"
},
"max"
"animal"
},
10.4. Sharding Reference 681

MongoDB Documentation, Release 2.6.4
"shard"
}
These documents store the range of values for the shard key that describe the chunk in theminandmaxelds.
Additionally theshardeld identies the shard in the cluster that owns the chunk.
config.collections
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thecollections(page 682) collection stores a document for each sharded collection in the cluster. Given
a collection namedpetsin therecordsdatabase, a document in thecollections(page 682) collection
would resemble the following:
{
"_id",
"lastmod""1970-01-16T15:00:58.107Z"),
"dropped" false,
"key"
"a"
},
"unique" false,
"lastmodEpoch""5078407bd58b175c5c225fdc")
}
config.databases
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thedatabases(page 682) collection stores a document for each database in the cluster, and tracks if the
database has sharding enabled.databases(page 682) represents each database in a distinct document. When
a databases have sharding enabled, theprimaryeld holds the name of theprimary shard.
{, false,
{, true,
config.lockpings
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thelockpings(page 682) collection keeps track of the active components in the sharded cluster. Given
a cluster with amongosrunning onexample.com:30000, the document in thelockpings(page 682)
collection would resemble:
{,"2012-10-12T18:32:54.892Z") }
682 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
config.locks
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thelocks(page 682) collection stores a distributed lock. This ensures that only onemongosinstance can
perform administrative tasks on the cluster at once. Themongosacting asbalancertakes a lock by inserting a
document resembling the following into thelockscollection.
{
"_id",
"process",
"state",
"ts""507daeedf40e1879df62e5f3"),
"when""2012-10-16T19:01:01.593Z"),
"who",
"why"
}
If amongosholds the balancer lock, thestateeld has a value of2, which means that balancer is active.
Thewheneld indicates when the balancer began the current operation.
Changed in version 2.0: The value of thestateeld was1before MongoDB 2.0.
config.mongos
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Themongos(page 683) collection stores a document for eachmongosinstance afliated with the cluster.
mongosinstances send pings to all members of the cluster every 30 seconds so the cluster can verify that the
mongosis active. Thepingeld shows the time of the last ping, while theupeld reports the uptime of the
mongosas of the last ping. The cluster maintains this collection for reporting purposes.
The following document shows the status of themongosrunning onexample.com:30000.
{,"2012-10-12T17:08:13.538Z"),, true}
config.settings
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thesettings(page 683) collection holds the following sharding conguration settings:
Chunk size. To change chunk size, seeModify Chunk Size in a Sharded Cluster(page 671).
Balancer status. To change status, seeDisable the Balancer(page 661).
The following is an examplesettingscollection:
10.4. Sharding Reference 683

MongoDB Documentation, Release 2.6.4
{,
{, false}
config.shards
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Theshards(page 684) collection represents each shard in the cluster in a separate document. If the shard
is a replica set, thehosteld displays the name of the replica set, then a slash, then the hostname, as in the
following example:
{,
If the shard hastags(page 671) assigned, this document has atagseld, that holds an array of the tags, as in
the following example:
{,,:
config.tags
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Thetags(page 684) collection holds documents for each tagged shard key range in the cluster. The documents
in thetags(page 684) collection resemble the following:
{
"_id",
"ns",
"min"
"max"
"tag"
}
config.version
Internal MongoDB Metadata
Theconfig(page 680) database is internal: applications and administrators should not modify or depend upon
its content in the course of normal operation.
Theversion(page 684) collection holds the current metadata version number. This collection contains only
one document:
To access theversion(page 684) collection you must use thedb.getCollection() method. For exam-
ple, to display the collection's document:
mongos>"version").find()
{,
684 Chapter 10. Sharding

MongoDB Documentation, Release 2.6.4
Note:Like all databases in MongoDB, theconfigdatabase contains asystem.indexes(page 271) collection
contains metadata for all indexes in the database for information on indexes, seeIndexes(page 431).
10.4. Sharding Reference 685

MongoDB Documentation, Release 2.6.4
686 Chapter 10. Sharding

CHAPTER11
Frequently Asked Questions
11.1
This document addresses basic high level questions about MongoDB and its use.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
1
.
11.1.1
MongoDB is adocument-oriented DBMS. Think of MySQL but withJSON-like objects comprising the data model,
rather than RDBMS tables. Signicantly, 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 usesBSON, a binary object format similar to, but more expressive thanJSON.
11.1.2
Instead of tables, a MongoDB database stores its data incollections, which are the rough equivalent of RDBMS tables.
A collection holds one or moredocuments, which corresponds to a record or a row in a relational database table, and
each document has one or more elds, 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 elds. Documents need not have identical elds. You can add a eld to some documents in a
collection without adding that eld to all documents in the collection.
See
SQL to MongoDB Mapping Chart(page 120)
1
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
687

MongoDB Documentation, Release 2.6.4
11.1.3
MongoDB uses dynamic schemas. You can create collections without dening the structure, i.e. the elds or the types
of their values, of the documents in the collection. You can change the structure of documents simply by adding new
elds or deleting existing ones. Documents in a collection need not have an identical set of elds.
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 exible 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 simplies
and facilitates iterative software development with MongoDB.
See
SQL to MongoDB Mapping Chart(page 120)
11.1.4
MongoDBclient driversexist for all of the most popular programming languages, and many other ones. See the
list of drivers
2
for details.
See also:
http://docs.mongodb.org/manualapplications/drivers .
11.1.5
No.
However, MongoDB does support a rich, ad-hoc query language of its own.
See also:
http://docs.mongodb.org/manualreference/operator
11.1.6
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.
11.1.7
MongoDB does not support multi-document transactions.
However, MongoDB does provide atomic operations on a single document. Often these document-level atomic oper-
ations are sufcient 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 modied before it commits these modications to disk, regard-
less of write concern level or journaling conguration. As a result, applications may observe two classes of behaviors:
2
http://docs.mongodb.org/ecosystem/drivers
688 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4

write operation before the write operation returns.
mongodterminates before the journal commits, even if a write returns successfully, queries may have
read data that will not exist after themongodrestarts.
Other database systems refer to these isolation semantics asread uncommitted. For all inserts and updates, Mon-
goDB modies 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.
Whenmongodreturns a successfuljournaled write concern, the data is fully committed to disk and will be available
aftermongodrestarts.
For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of
the members of the set. MongoDB regularly commits data to the journal regardless of journaled write concern: use
thecommitIntervalMsto control how often amongodcommits the journal.
11.1.8
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 Mon-
goDB will use as much free memory as it can, swapping to disk as needed. Deployments with enough memory to t
the application's working data set in RAM will achieve the best performance.
See also:
FAQ: MongoDB Diagnostics(page 720) for answers to additional questions about MongoDB and Memory use.
11.1.9
MongoDB has no congurable cache. MongoDB uses allfreememory on the system automatically by way of memory-
mapped les. Operating systems use the same approach with their le system caches.
11.1.10
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.
11.1.11
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 ts 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 les.
11.1. FAQ: MongoDB Fundamentals 689

MongoDB Documentation, Release 2.6.4
11.1.12
Writes are physically written to thejournal(page 275) 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
commitIntervalMsfor more information on the journal commit window.
While the journal commit is nearly instant, MongoDB writes to the data les lazily. MongoDB may wait to write
data to the data les 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 les, seesyncPeriodSecs.
11.1.13
MongoDB is implemented in C++.Driversand client libraries are typically written in their respective languages,
although some drivers use C extensions for better performance.
11.1.14
MongoDB usesmemory-mapped les(page 714). 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
3

Note:32-bit builds disablejournalingby default because journaling further limits the maximum amount of data that
the database can store.
11.2
This document answers common questions about application development using MongoDB.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
4
.
11.2.1
A namespace is the concatenation of thedatabasename and thecollectionnames
5
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 les.
6
For an exampleacme.usersnamespace,acmeis the database name andusersis the collection name. Period
characterscanoccur in collection names, so thatacme.user.history is a valid namespace, withacmeas the
database name, anduser.historyas the collection name.
3
http://blog.mongodb.org/post/137788967/32-bit-limitations
4
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
5
Each index also has its own namespace.
6
MongoDB database have a congurable limit on thenumber of namespaces in a database.
690 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
While data models like this appear to support nested collections, the collection namespace is at, and there is no
difference from the perspective of MongoDB betweenacme,acme.users, andacme.records.
11.2.2
In themongoshell, you can use the following operation to duplicate the entire collection:
db.source.copyTo(newCollection)
Warning:When usingdb.collection.copyTo() check eld types to ensure that the operation does
not remove type information from documents during the translation fromBSONtoJSON. Consider using
cloneCollection()to maintain type delity.
Thedb.collection.copyTo() method uses theevalcommand internally. As a result, the
db.collection.copyTo() operation takes a global lock that blocks all other read and write operations until
thedb.collection.copyTo() completes.
Also consider thecloneCollectioncommandthat may provide some of this functionality.
11.2.3
Yes.
When you useremove(), the object will no longer exist in MongoDB's on-disk data storage.
11.2.4
MongoDB ushes writes to disk on a regular interval. In the default conguration, MongoDB writes data to the
main data les on disk every 60 seconds and commits thejournalroughly every 100 milliseconds. These values are
congurable with thecommitIntervalMsandsyncPeriodSecs.
These values represent themaximumamount 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 ushes data to the disk. In many cases MongoDB
and the operating system ush 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 ush this data to disk
once. In addition to the aforementioned conguration options, you can also usefsyncandWrite Concern Reference
(page 118) to modify this strategy.
11.2.5
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 forpartitioned
orreplicatedsystems with a number of database server processes.
MongoDBdoeshave support for atomic operationswithina single document. Given the possibilities provided by
nested documents, this feature provides support for a large number of use-cases.
See also:
TheIsolate Sequence of Operations(page 111) page.
11.2. FAQ: MongoDB for Application Developers 691

MongoDB Documentation, Release 2.6.4
11.2.6
In version 2.1 and later, you can use the newaggregation framework(page 391), with theaggregatecommand.
MongoDB also supportsmap-reducewith themapReducecommand, as well as basic aggregation with thegroup,
count, anddistinct. commands.
See also:
TheAggregation(page 387) page.
11.2.7
If you see a very large number connection and re-connection messages in your MongoDB log, then clients are fre-
quently 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-timequietoption or the command-line
option--quietto suppress these messages from the log.
11.2.8
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
7
11.2.9
MongoDB aggressively preallocates data les to reserve space and avoid le system fragmentation. You can use the
storage.smallFiles setting to modify the le preallocation strategy.
See also:
Why are the les in my data directory larger than the data in my database?(page 716)
11.2.10
Each MongoDB document contains a certain amount of overhead. This overhead is normally insignicant but becomes
signicant if all documents are just a few bytes, as might be the case if the documents in your collection only have one
or two elds.
Consider the following suggestions and strategies for optimizing storage utilization for these collections:
_ideld explicitly.
MongoDB clients automatically add an_ideld to each document and generate a unique 12-byteObjectIdfor
the_ideld. Furthermore, MongoDB always indexes the_ideld. For smaller documents this may account
for a signicant amount of space.
7
http://docs.mongodb.org/ecosystem/platforms/amazon-ec2
692 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
To optimize storage use, users can specify a value for the_ideld explicitly when inserting documents into the
collection. This strategy allows applications to store a value in the_ideld that would have occupied space in
another portion of the document.
You can store any value in the_ideld, but because this value serves as a primary key for documents in the
collection, it must uniquely identify them. If the eld's value is not unique, then it cannot serve as a primary key
as there would be collisions in the collection.

MongoDB stores all eld names in every document. For most documents, this represents a small fraction of the
space used by a document; however, for small documents the eld names may represent a proportionally large
amount of space. Consider a collection of documents that resemble the following:
{ last_name, best_score:
If you shorten the eld namedlast_nametolnameand the eld namedbest_scoretoscore, as follows,
you could save 9 bytes per document.
{ lname, score
Shortening eld names reduces expressiveness and does not provide considerable benet for larger documents
and where document overhead is not of signicant concern. Shorter eld names do not reduce the size of
indexes, because indexes have a predened structure.
In general it is not necessary to use short eld names.

In some cases you may want to embed documents in other documents and save on the per-document overhead.
11.2.11
For documents in a MongoDB collection, you should always useGridFSfor storing les larger than 16 MB.
In some situations, storing large les may be more efcient in a MongoDB database than on a system-level lesystem.

and facilities. When usinggeographically distributed replica sets(page 522) MongoDB can distribute les and
their metadata automatically to a number ofmongodinstances and facilities.

you can use GridFS to recall sections of les without reading the entire le into memory.
Do not use GridFS if you need to update the content of the entire le atomically. As an alternative you can store
multiple versions of each le and specify the current version of the le in the metadata. You can update the metadata
eld that indicates latest status in an atomic update after uploading the new version of the le, and later remove
previous versions if needed.
Furthermore, if your les are all smaller the 16 MBBSON Document Size limit, consider storing the le man-
ually within a single document. You may use the BinData data type to store the binary data. See yourdrivers
documentation for details on using BinData.
For more information on GridFS, seeGridFS(page 138).
11.2. FAQ: MongoDB for Application Developers 693

MongoDB Documentation, Release 2.6.4
11.2.12
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 asBSONobjects. Typicallyclient librariesprovide a convenient, injection free,
process to build these objects. Consider the following C++ example:
BSONObj my_queryname"<
auto_ptr<DBClientCursor>"tutorial.persons", my_query);
Here,my_querythen will have a value such as{ name : "Joe" } . Ifmy_querycontained special charac-
ters, 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--noscriptingoption on the
command line or settingsecurity.javascriptEnabled in a conguration le.
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 elds directly in aBSONeld and
pass JavaScript code to the$whereeld.
$whereclause, you may escape these values with the
CodeWScopemechanism. When you set user-submitted values as variables in the scope document, you can
avoid evaluating them on the database server.
db.eval()with user supplied values, you can either use aCodeWScopeor you can supply
extra arguments to your function. For instance:
db.eval( function(userVal){...},
user_value);
This will ensure that your application sendsuser_valueto 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 representoperators(i.e.$inc.) Thus, you should ensure that your application's users cannot inject operators
into their inputs.
694 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
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 sufcient, but consider using the Unicode full width
equivalents:U+FF04(i.e. $) andU+FF0E(i.e. .).
Consider the following example:
BSONObj my_object<
The user may have supplied a$value in thea_keyvalue. At the same time,my_objectmight 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. Theupdate()operation permits$operators in the update argument but does not support the
$whereoperator. 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.
QueryGenerally 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-Specic Issues
See the PHP MongoDB Driver Security Notes
8
page in the PHP driver documentation for more information
11.2.13
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 andreplica setsthe lock's scope applies to a singlemongodinstance orprimaryinstance. In a sharded
cluster, locks apply to each individual shard, not to the whole cluster.
For more information, seeFAQ: Concurrency(page 702).
11.2.14
MongoDB permits documents within a single collection to have elds with differentBSONtypes. For instance, the
following documents may exist within a single collection.
{ x:
{ x:
When comparing values of differentBSONtypes, MongoDB uses the following comparison order, from lowest to
highest:
1.
2.
3.
4.
8
http://us.php.net/manual/en/mongo.security.php
11.2. FAQ: MongoDB for Application Developers 695

MongoDB Documentation, Release 2.6.4
5.
6.
7.
8.
9.
10.
11.
12.
MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion
before comparison.
The comparison treats a non-existent eld as it would an empty BSON Object. As such, a sort on theaeld 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 eld whose
value is a single-element array (e.g.[ 1 ]) with non-array elds (e.g.2), the comparison is between1and2. A
comparison of an empty array (e.g.[ ]) treats the empty array as less thannullor a missing eld.
MongoDB sortsBinDatain the following order:
1.
2.
3.
Consider the followingmongoexample:
db.test.insert( {x
db.test.insert( {x
db.test.insert( {x newDate() } );
db.test.insert( {x true} );
db.test.find().sort({x:1});
{"4b03155dce8de6586fb002c7"),
{"4b03154cce8de6586fb002c6"),
{"4b031566ce8de6586fb002c9"), true}
{"4b031563ce8de6586fb002c8"),
The$typeoperator provides access toBSON typecomparison in the MongoDB query syntax. See the documentation
onBSON typesand the$typeoperator for additional information.
Warning:Storing values of the different types in the same eld in a collection isstronglydiscouraged.
See also:
Tailable Cursors(page 109) page for an example of a C++ use ofMinKey.
11.2.15
The$mulmultiplies the numeric value of a eld by a number. For multiplication with values of mixed numeric types
(32-bit integer, 64-bit integer, oat), the following type conversion rules apply:
696 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
32-bit Integer 64-bit IntegerFloat
32-bit Integer32-bit or 64-bit Integer64-bit IntegerFloat
64-bit Integer64-bit Integer 64-bit IntegerFloat
Float Float Float Float
Note:

11.2.16
Fields in a document may storenullvalues, as in a notional collection,test, with the following documents:
{ _id:, cancelDate: null}
{ _id:
Different query operators treatnullvalues differently:
{ cancelDate : null } query matches documents that either contains thecancelDateeld
whose value isnullorthat do not contain thecancelDateeld:
db.test.find( { cancelDate: null} )
The query returns both documents:
{, null}
{
{ cancelDate : { $type: 10 } } query matches documents that contains thecancelDate
eld whose value isnullonly; i.e. the value of thecancelDateeld is of BSON TypeNull(i.e.10) :
db.test.find( { cancelDate:
The query returns only the document that contains thenullvalue:
{, null}
{ cancelDate : { $exists: false } } query matches documents that do not contain the
cancelDateeld:
db.test.find( { cancelDate: false} } )
The query returns only the document that doesnotcontain thecancelDateeld:
{
See also:
The reference documentation for the$typeand$existsoperators.
11.2.17
Collection names can be any UTF-8 string with the following exceptions:

"") is not a valid collection name.
11.2. FAQ: MongoDB for Application Developers 697

MongoDB Documentation, Release 2.6.4
$character. (version 2.2 only)
\0
system.prex. MongoDB reservessystem.for system collections,
such as thesystem.indexescollection.

maximum exibility, 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
thedb.getCollection() method or a
9
.
Example
To create a collection_fooand insert the{ a : 1 }document, use the following operation:
db.getCollection("_foo").insert( { a
To perform a query, use thefind()method, in as the following:
db.getCollection("_foo").find()
11.2.18
MongoDB cursors can return the same document more than once in some situations.
10
You can use thesnapshot()
method on a cursor to isolate the operation for a very specic case.
snapshot()traverses the index on the_ideld and guarantees that the query will return each document (with
respect to the value of the_ideld) no more than once.
11
Thesnapshot()does not guarantee that the data returned by the query will reect a single moment in timenor
does it provide isolation from insert or delete operations.
Warning:
cannotusesnapshot()withsharded collections.
cannotusesnapshot()withsort()orhint()cursor methods.
As an alternative, if your collection has a eld or elds that are never modied, you can use auniqueindex on this
eld or these elds to achieve a similar result as thesnapshot(). Query withhint()to explicitly force the query
to use that index.
11.2.19
Whenmodeling data in MongoDB(page 133), embedding is frequently the choice for:

alwaysappear with or are viewed in the context of their
parents.
9
http://api.mongodb.org/
10
As a cursor returns documents other operations may interleave with the query: if some of these operations areupdates(page 67) that cause the
document to move (in the case of a table scan, caused by document growth) or that change the indexed eld on the index used by the query; then
the cursor will return the same document more than once.
11
MongoDB does not permit changes to the value of the_ideld; it is not possible for a cursor that transverses this index to pass the same
document more than once.
698 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
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 relationshipandyou frequently retrieve the doc-
uments by this grouping, you might consider rolling-up the small documents into larger documents that contain an
array of subdocuments. 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 elds to the larger document benet the index on these
elds. There would be fewer copies of the common eldsandthere would be fewer associated key entries in the
corresponding index. SeeIndex Concepts(page 436) for more information on indexes.
11.2.20
Begin by reading the documents in theData Models(page 131) section. These documents contain a high level intro-
duction 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:

12

13

14

15

16
which was the source for much of thedata-modeling-treescontent.
11.2.21
An update can cause a document to move on disk if the document grows in size. Tominimizedocument movements,
MongoDB usespadding.
You should not have to pad manually because MongoDB addspadding automatically(page 83) and can adaptively
adjust the amount of padding added to documents to prevent document relocations following updates. You can change
the defaultpaddingFactorcalculation by using thecollModcommand with theusePowerOf2Sizesag.
TheusePowerOf2Sizesag ensures that MongoDB allocates document space in sizes that are powers of 2, which
helps ensure that MongoDB can efciently reuse free space created by document deletion or relocation.
However,if you mustpad a document manually, you can add a temporary eld to the document and then$unsetthe
eld, 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.
12
http://www.10gen.com/presentations/mongodb-melbourne-2012/schema-design-example
13
http://dmerr.tumblr.com/post/6633338010/schemaless
14
http://docs.mongodb.org/ecosystem/tutorial/model-data-for-ruby-on-rails/
15
http://github.com/banker/newsmonger/blob/master/app/models/comment.rb
16
http://seancribbs.com/tech/2009/09/28/modeling-a-tree-in-a-document-database
11.2. FAQ: MongoDB for Application Developers 699

MongoDB Documentation, Release 2.6.4
varmyTempPadding,
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"];
db.myCollection.insert( { _id:, paddingField:
db.myCollection.update( { _id:
{ $unset::
)
db.myCollection.update( { _id:
{ $set::
)
See also:
Record Allocation Strategies(page 83)
11.3 mongoShell
11.3.1 mongoshell?
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 (']'). Themongoshell waits for the closing parenthesis, closing brace, or the closing bracket
before evaluating the code, as in the following example:
>if( x
... count++;
... print (x);
... }
You can exit the line continuation mode if you enter two blank lines, as in the following example:
>if(x
...
...
>
11.3.2
You can usedb.getSiblingDB()method to access another database without switching databases, as in the fol-
lowing example which rst switches to thetestdatabase and then accesses thesampleDBdatabase from thetest
database:
use test
db.getSiblingDB(sampleDB).getCollectionNames();
11.3.3 mongoshell support tab completion and other keyboard shortcuts?
Themongoshell supports keyboard shortcuts. For example,
700 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
.dbshelldocumentation for more informa-
tion on the.dbshellle.
<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, seeShell Keyboard Shortcuts
11.3.4 mongoshell prompt?
New in version 1.9.
You can change themongoshell prompt by setting thepromptvariable. This makes it possible to display additional
information in the prompt.
Setpromptto any string or arbitrary JavaScript code that returns a string, consider the following examples:

varhost
varprompt function() {returndb+"@"+host+"> "; }
Themongoshell prompt should now reect the new prompt:
[email protected]>

varprompt function() {
return"Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > ";
}
Themongoshell prompt should now reect the new prompt:
Uptime:1052 Documents:25024787 >
You can add the logic for the prompt in the.mongorc.jsle to set the prompt each time you start up themongoshell.
11.3.5
You can use your own editor in themongoshell by setting theEDITORenvironment variable before starting the
mongoshell. Once in themongoshell, you can edit with the specied editor by typingedit <variable>or
edit <function>, as in the following example:
1. EDITORvariable from the command line prompt:
EDITOR=vim
2. mongoshell:
mongo
3. myFunction:
11.3. FAQ: ThemongoShell 701

MongoDB Documentation, Release 2.6.4
functionmyFunction () { }
4.
edit myFunction
The command should open thevimedit session. Remember to save your changes.
5. myFunctionto see the function denition:
myFunction
The result should be the changes from your saved edit:
functionmyFunction() {
print("This was edited");
}
11.4
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 dataandto 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
17
11.4.1
MongoDB uses a readers-writer
18
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 readorwrite 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.
11.4.2
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 permongodinstance.
For example, if you have six databases and one takes a database-level write lock, the other ve are still available for
read and write. A global lock makes all six databases unavailable during the operation.
17
http://www.mongodb.com/presentations/concurrency-internals-mongodb-2-2
18
You may be familiar with a readers-writer lock as multi-reader or shared exclusive lock. See the Wikipedia page on
Locks
702 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.4.3 mongodinstances?
For reporting on lock utilization information on locks, use any of the following methods:
db.serverStatus(),
db.currentOp(),
mongotop,
mongostat, and/or

19
Specically, thelocksdocument in theoutput of serverStatus , or thelockseld in thecurrent
operation reporting provides insight into the type of locks and amount of lock contention in yourmongod
instance.
To terminate an operation, usedb.killOp().
11.4.4
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 modication in write operations that affect
multiple documents likeupdate()with themultiparameter.
MongoDB uses heuristics based on its access pattern to predict whether data is likely in physical memory before
performing a read. If MongoDBpredictsthat 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.
11.4.5
Changed in version 2.2.
The following table lists common database operations and the types of locks they use.
19
http://mms.mongodb.com/
11.4. FAQ: Concurrency 703

MongoDB Documentation, Release 2.6.4
Operation Lock Type
Issue a queryRead lock
Get more data
from acursor
Read lock
Insert data Write lock
Remove data Write lock
Update data Write lock
Map-reduce Read lock and write lock, unless operations are specied as non-atomic. Portions of
map-reduce jobs can run concurrently.
Create an indexBuilding an index in the foreground, which is the default, locks the database for extended
periods of time.
db.eval() Write lock. Thedb.eval()method takes a global write lock while evaluating the JavaScript
function. To avoid taking this global write lock, you can use theevalcommand with
nolock: true.
eval Write lock. By default,evalcommand takes a global write lock while evaluating the
JavaScript function. If used withnolock: true, theevalcommand doesnottake 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
11.4.6
Certain administrative commands can exclusively lock the database for extended periods of time. In some deploy-
ments, for large databases, you may consider taking themongodinstance ofine so that clients are not affected. For
example, if amongodis part of areplica set, take themongodofine 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 issuedwithoutsettingbackgroundtotrue,
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. SeeDoes a MongoDB operation ever lock
more than one database?(page 705).
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().
704 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.4.7
The following MongoDB operations lock multiple databases:
db.copyDatabase()must lock the entiremongodinstance at once.
db.repairDatabase() obtains a global write lock and will block other operations until it nishes.
Journaling, which is an internal operation, locks all databases for short intervals. All databases share a single
journal.
User authentication(page 282) requires a read lock on theadmindatabase for deployments using2.6 user
credentials(page 372). For deployments using the 2.4 schema for user credentials, authentication locks the
admindatabase as well as the database the user is accessing.
primarylock both the database receiving the writes and then thelocaldatabase for
a short time. The lock for thelocaldatabase allows themongodto write to the primary'soplogand accounts
for a small portion of the total time of the operation.
11.4.8
Shardingimproves concurrency by distributing collections over multiplemongodinstances, allowing shard servers
(i.e.mongosprocesses) to perform any number of operations concurrently to the various downstreammongod
instances.
Eachmongodinstance is independent of the others in the shard cluster and uses the MongoDBreaders-writer lock
(page 702). The operations on onemongodinstance do not block the operations on any others.
11.4.9
Inreplication, when MongoDB writes to a collection on theprimary, MongoDB also writes to the primary'soplog,
which is a special collection in thelocaldatabase. Therefore, MongoDB must lock both the collection's database
and thelocaldatabase. Themongodmust 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.
11.4.10
Inreplication, MongoDB does not apply writes serially tosecondaries. 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:
1. preferphase, under a read lock, themongodensures that all documents affected by the opera-
tions are in memory. During this phase, other clients may execute queries against this member.
2.
11.4.11
tions?
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 singlemongodcould only run asingleJavaScript operation at once.
11.4. FAQ: Concurrency 705

MongoDB Documentation, Release 2.6.4
11.5
This document answers common questions about horizontal scaling using MongoDB'ssharding.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
20
.
11.5.1
Sometimes.
If your data set ts on a single server, you should begin with an unsharded deployment.
Converting an unsharded database to asharded clusteris easy and seamless, so there islittle advantagein conguring
sharding while your data set is small.
Still, all production deployments should usereplica setsto provide high availability and disaster recovery.
11.5.2
To use replication with sharding, deploy eachshardas areplica set.
11.5.3
No.
There is no automatic support in MongoDB for changing a shard key after sharding a collection. This reality un-
derscores the importance of choosing a goodshard key(page 620). If youmustchange a shard key after sharding a
collection, the best option is to:

pre-split(page 665) the shard key range to ensure initial even distribution.

SeeshardCollection,sh.shardCollection() , theShard Key(page 620),Deploy a Sharded Cluster
(page 635), and
21
for more information.
11.5.4
In the current implementation, all databases in asharded clusterhave a primaryshard. All unsharded collection
within that database will reside on the same shard.
11.5.5
Sharding must be specically 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.
20
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
21
https://jira.mongodb.org/browse/SERVER-4000
706 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.5.6
Themongosroutes the operation to the old shard, where it will succeed immediately. Then theshardmongodin-
stances will replicate the modication to the new shard before thesharded clusterupdates that chunk's ownership,
which effectively nalizes the migration process.
11.5.7
If ashardis inaccessible or unavailable, queries will return with an error.
However, a client may set thepartialquery bit, which will then return results from all available shards, regardless
of whether a given shard is unavailable.
If a shard is responding slowly,mongoswill merely wait for the shard to return results.
11.5.8
Changed in version 2.0.
The exact method for distributing queries toshardsin aclusterdepends on the nature of the query and the conguration
of the sharded cluster. Consider a sharded collection, using theshard keyuser_id, that haslast_loginand
emailattributes:
user_idkey:
mongosdetermines 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.
user_idand also performs a sort:
mongoscan make a straightforward translation of this operation into a number of queries against the relevant
shards, ordered byuser_id. When the sorted queries return from all shards, themongosmerges the sorted
results and returns the complete result to the client.
last_login:
These queries must run on all shards:mongosmust parallelize the query over the shards and perform a merge-
sort on theemailof the documents found.
11.5.9
If you call thecursor.sort()method on a query in a sharded environment, themongodfor each shard will sort
its results, and themongosmerges each shard's results before returning them to the client.
11.5.10 _ideld values when using a shard
keyotherthan_id?
If you do not use_idas the shard key, then your application/client layer must be responsible for keeping the_id
eld unique. It is problematic for collections to have duplicate_idvalues.
If you're not sharding your collection by the_ideld, then you should be sure to store a globally unique identier in
that eld. The defaultBSON ObjectId(page 165) works well in this case.
11.5. FAQ: Sharding with MongoDB 707

MongoDB Documentation, Release 2.6.4
11.5.11
one server. Why?
First, ensure that you've declared ashard keyfor your collection. Until you have congured the shard key, MongoDB
will not createchunks, andshardingwill 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 superuous migrations. Depend-
ing 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 rundb.printShardingStatus() to see all the chunks present in your cluster.
11.5.12 moveChunkdirectory?
Yes.mongodcreates these les as backups during normalshardbalancing operations.
Once these migrations are complete, you may delete these les.
11.5.13 mongosuse connections?
Each client maintains a connection to amongosinstance. Eachmongosinstance maintains a pool of connections to
the members of a replica set supporting the sharded cluster. Clients use connections betweenmongosandmongod
instances one at a time. Requests are not multiplexed or pipelined. When client requests complete, themongos
returns the connection to the pool.
See theSystem Resource Utilization(page 267) section of theUNIX ulimit Settings(page 266) document.
11.5.14 mongoshold connections open?
mongosuses a set of connection pools to communicate with eachshard. These pools do not shrink when the number
of clients decreases.
This can lead to an unusedmongoswith a large number of open connections. If themongosis no longer in use, it is
safe to restart the process to close existing connections.
11.5.15 mongos?
Connect to themongoswith themongoshell, and run the following command:
db._adminCommand("connPoolStats");
11.5.16 writebacklistenin the log mean?
The writeback listener is a process that opens a long poll to relay writes back from amongodormongosafter
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.
708 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.5.17
Failed migrations require no administrative intervention. Chunk migrations always preserve a consistent state. If a mi-
gration fails to complete for some reason, theclusterretries the operation. When the migration completes successfully,
the data resides only on the new shard.
11.5.18
g servers?
SeeSharded Cluster Tutorials(page 634) for information on migrating and replacing cong servers.
11.5.19 mongosservers detect cong server changes?
mongosinstances maintain a cache of thecong databasethat holds the metadata for thesharded cluster. This
metadata includes the mapping ofchunkstoshards.
mongosupdates 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 theflushRouterConfigcommand against any
mongosto force it to refresh its cache.
11.5.20 mongosservers after updating a replica set
conguration?
Themongosinstances will detect these changes without intervention over time. However, if you want to force the
mongosto reload its conguration, run theflushRouterConfigcommand against to eachmongosdirectly.
11.5.21 maxConnssetting onmongosdo?
ThemaxIncomingConnections option limits the number of connections accepted bymongos.
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 themongoslayer.
SetmaxIncomingConnections 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 themongosfrom causing connection
spikes on the individualshards. Spikes like these may disrupt the operation and memory allocation of thesharded
cluster.
11.5.22
If the query does not include theshard key, themongosmust send the query to all shards as a scatter/gather
operation. Each shard will, in turn, useeitherthe shard key index or another more efcient index to fulll the query.
If the query includes multiple sub-expressions that reference the elds indexed by the shard keyandthe secondary
index, themongoscan route the queries to a specic shard and the shard will use the index that will allow it to fulll
most efciently. See
22
for more information.
22
http://www.slideshare.net/mongodb/how-queries-work-with-sharding
11.5. FAQ: Sharding with MongoDB 709

MongoDB Documentation, Release 2.6.4
11.5.23
Shard keyscan be random. Random keys ensure optimal distribution of data across the cluster.
Sharded clusters, attempt to route queries tospecicshards when queries include the shard key as a parameter, because
these directed queries are more efcient. In many cases, random keys can make it difcult to direct queries to specic
shards.
11.5.24
Yes. There is no requirement that documents be evenly distributed by the shard key.
However, documents that have the same shard keymustreside in the samechunkand 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 distributethose
documents across your sharded cluster.
11.5.25 _ideld?
You can use any eld for the shard key. The_ideld is a common shard key.
Be aware thatObjectId()values, which are the default value of the_ideld, 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 provideshashed shard keys(page 621).
11.5.26 moveChunk commit failed errors mean?
At the end of achunk migration(page 631), theshardmust connect to thecong databaseto update the chunk's record
in the cluster metadata. If theshardfails to connect to thecong 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, theprimarymember of the shard's replica set then terminates to protect data consistency. If a
secondarymember can access the cong 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
23
or
24
to address this issue.
11.5.27
tion?
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:

maining uneven chunk distribution.
23
http://groups.google.com/group/mongodb-user
24
http://www.mongodb.org/about/support
710 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
thenremoves the chunks from
the draining shard.
11.6
This document answers common questions about database replication in MongoDB.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
25
.
11.6.1
MongoDB supports master-slave replication and a variation on master-slave replication known as replica sets. Replica
sets are the recommended replication topology.
11.6.2
Primaryandmasternodes 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 autonomouslyelect
one of the other members of the set to be the new primary.
By default, clients send all reads to the primary; however,read preferenceis congurable at the client level on a
per-connection basis, which makes it possible to send reads to secondary nodes instead.
11.6.3
Secondaryandslavenodes are read-only nodes that replicate from theprimary.
Replication operates by way of anoplog, from which secondary/slave members apply new operations to themselves.
This replication process is asynchronous, so secondary/slave nodes may not always reect 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.
11.6.4
It varies, but a replica set will select a new primary within a minute.
It may take 10-30 seconds for the members of areplica setto declare aprimaryinaccessible. This triggers anelection.
During the election, the cluster is unavailable for writes.
The election itself may take another 10-30 seconds.
Note:Eventually consistentreads, like the ones that will return from a replica set are only possible with awrite
concernthat permits reads fromsecondarymembers.
25
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
11.6. FAQ: Replication and Replica Sets 711

MongoDB Documentation, Release 2.6.4
11.6.5
Yes.
For example, a deployment may maintain aprimaryandsecondaryin an East-coast data center along with asecondary
member for disaster recovery in a West-coast data center.
See also:
Deploy a Geographically Redundant Replica Set(page 550)
11.6.6
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 aps. 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 theprimaryinstance breaks, areplica setwill automatically elect
one of thesecondarymembers of the set as primary.
11.6.7
New in version 1.8.
Replica setsare the preferredreplicationmechanism in MongoDB. However, if your deployment requires more than
12 nodes, you must use master/slave replication.
11.6.8
Deprecated since version 1.6.
Replica setsreplacedreplica pairsin version 1.6.Replica setsare the preferredreplicationmechanism in MongoDB.
11.6.9
Journalingfacilitates faster crash recovery. Prior to journaling, crashes often requireddatabase repairsor full
data resync. Both were slow, and the rst 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 areplica setruns with journaling,mongodinstances 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.
712 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.6.10
writes?
Yes.
However, if you want conrmation that a given write has arrived at the server, usewrite concern(page 72).
After thedefault write concern change(page 808), the default write concern acknowledges
all write operations, and unacknowledged writes must be explicitly congured. See the
http://docs.mongodb.org/manualapplications/drivers documentation for your driver for
more information.
Changed in version 2.6: Themongoshell now defaults to usesafe writes(page 72). SeeWrite Method Acknowledge-
ments(page 743) for more information.
A new protocol forwrite operations(page 737) integrates write concerns with the write operations. Previous versions
issued agetLastErrorcommand after a write to specify a write concern.
11.6.11
Some congurations do not require anyarbiterinstances. Arbiters vote inelectionsforprimarybut do not replicate
the data likesecondarymembers.
Replica setsrequire 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 setarchitectures(page 516).
A replica set with an odd number of voting nodes does not need an arbiter.
A common conguration consists of two replicating nodes that include aprimaryand asecondary, as well as an
arbiterfor the third node. This conguration 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(page 516)
11.6.12
Arbiters never receive the contents of a collection but do exchange the following data with the rest of the replica set:

keyles. These exchanges are encrypted.

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 forCongure mongod and mongos for SSL(page 304) for more infor-
mation. Run all arbiters on secure networks, as with all MongoDB components.
See
The overview ofArbiter Members of Replica Sets(page??).
11.6. FAQ: Replication and Replica Sets 713

MongoDB Documentation, Release 2.6.4
11.6.13
All members of a replica set, unless the value ofvotes(page 597) is equal to0, vote in elections. This includes all
delayed(page 513),hidden(page 513) andsecondary-only(page 512) members, as well as thearbiters(page??).
Additionally, thestateof 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(page 523)
11.6.14
Hidden members(page 513) ofreplica sets dovote in elections. To exclude a member from voting in anelection,
change the value of the member'svotes(page 597) conguration to0.
See also:
Replica Set Elections(page 523)
11.6.15
Yes.
Factors including: different oplog sizes, different levels of storage fragmentation, and MongoDB's data le pre-
allocation can lead to some variation in storage utilization between nodes. Storage use disparities will be most pro-
nounced when you add members at different times.
11.7
This document addresses common questions regarding MongoDB's storage system.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
26
.
11.7.1
A memory-mapped le is a le with data that the operating system places in memory by way of themmap()system
call.mmap()thusmapsthe le to a region of virtual memory. Memory-mapped les are the critical piece of the
storage engine in MongoDB. By using memory mapped les MongoDB can treat the contents of its data les as if they
were in memory. This provides MongoDB with an extremely fast and simple method for accessing and manipulating
data.
26
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
714 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.7.2
Memory mapping assigns les to a block of virtual memory with a direct byte-for-byte correlation. Once mapped, the
relationship between le and memory allows MongoDB to interact with the data in the le as if it were memory.
11.7.3
MongoDB uses memory mapped les for managing and interacting with all data. MongoDB memory maps data les
to memory as it accesses documents. Data that isn't accessed isnotmapped to memory.
11.7.4
Page faults can occur as MongoDB reads from or writes data to parts of its data les 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 nd the page on disk and load it to memory directly. However,
if there is no free memory, the operating system must:

This process, particularly on an active system can take a long time, particularly in comparison to reading a page that
is already in memory.
SeePage Faults(page 179) for more information.
11.7.5
Page faultsoccur 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 le cache. In production, MongoDB
will rarely encounter soft page faults.
SeePage Faults(page 179) for more information.
11.7.6
Thedb.stats()method in themongoshell, returns the current state of the active database. ThedbStats
commanddocument describes the elds in thedb.stats()output.
11.7.7
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 specic 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.
11.7. FAQ: MongoDB Storage 715

MongoDB Documentation, Release 2.6.4
If you run a query that requires MongoDB to scan everydocumentin a collection, the working set includes every
active document in memory.
For best performance, the majority of youractiveset should t in RAM.
11.7.8
The data les in your data directory, which is the/data/dbdirectory in default congurations, might be larger than
the data set inserted into the database. Consider the following possible causes:

In the data directory, MongoDB preallocates data les to a particular size, in part to prevent le system frag-
mentation. MongoDB names the rst data le<databasename>.0, the next<databasename>.1, etc.
The rst lemongodallocates is 64 megabytes, the next 128 megabytes, and so on, up to 2 gigabytes, at which
point all subsequent les are 2 gigabytes. The data les include les with allocated space but that hold no data.
mongodmay allocate a 1 gigabyte data le that may be 90% empty. For most larger databases, unused allocated
space is small compared to the database.
On Unix-like systems,mongodpreallocates an additional data le and initializes the disk space to0. Preallo-
cating data les in the background prevents signicant delays when a new database le is next allocated.
You can disable preallocation by settingpreallocDataFiles tofalse. However do not disable
preallocDataFilesfor production environments: only usepreallocDataFilesfor testing and with
small data sets where you frequently drop databases.
On Linux systems you can usehdparmto get an idea of how costly allocation might be:
time $((1024*1024))testfile
oplog.
If thismongodis a member of a replica set, the data directory includes theoplog.rsle, which is a preallocated
capped collectionin thelocaldatabase. The default allocation is approximately 5% of disk space on 64-bit
installations, seeOplog Sizing(page 535) for more information. In most cases, you should not need to resize
the oplog. However, if you do, seeChange the Size of the Oplog(page 570).
journal.
The data directory contains the journal les, which store write operations on disk prior to MongoDB applying
them to databases. SeeJournaling Mechanics(page 275).

MongoDB maintains lists of empty records in data les 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, usecompact, which de-fragments allocated space. By de-fragmenting stor-
age, MongoDB can effectively use the allocated space.compactrequires up to 2 gigabytes of extra disk space
to run. Do not usecompactif you are critically low on disk space.
Important:compactonly removes fragmentation from MongoDB data les and does not return any disk
space to the operating system.
To reclaim deleted space, userepairDatabase, which rebuilds the database which de-fragments the storage
and may release space to the operating system.repairDatabaserequires up to 2 gigabytes of extra disk
space to run. Do not userepairDatabaseif you are critically low on disk space.
716 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
Warning:repairDatabaserequires enough free disk space to hold both the old and new database les
while the repair is running. Be aware thatrepairDatabasewill block all other operations and may take
a long time to complete.
11.7.9
To view the size of a collection and other information, use thedb.collection.stats() method from themongo
shell. The following example issuesdb.collection.stats() for theorderscollection:
db.orders.stats();
To view specic 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._adminCommand("listDatabases").databases.forEach( function(d) {mdb function(c) {s
11.7.10
To view the size of the data allocated for an index, use one of the following procedures in themongoshell:
db.collection.stats() method using the index namespace. To retrieve a list of namespaces,
issue the following command:
db.system.namespaces.find()
indexSizesin the output of thedb.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"}
{"name"}
{"name"}
View the size of the data allocated for theorders.$_id_index with the following sequence of operations:
use test
db.orders.$_id_.stats().indexSizes
11.7. FAQ: MongoDB Storage 717

MongoDB Documentation, Release 2.6.4
11.7.11
If your server runs out of disk space for data les, 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 thecompactcommand, you must restart the server rst.
If your server runs out of disk space for journal les, the server process will exit. By default,mongodcreates journal
les in a sub-directory ofdbPathnamedjournal. You may elect to put the journal les on another storage device
using a lesystem mount or a symlink.
Note:If you place the journal les on a separate storage device you will not be able to use a le system snapshot tool
to capture a valid snapshot of your data les and journal les.
11.8
This document addresses common questions regarding MongoDB indexes.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
27
. See alsoIndexing Tutorials(page 464).
11.8.1 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 runningensureIndex()is usually ok, if an index doesn't exist because of ongoing administrative work,
a call toensureIndex()may disrupt database availability. RunningensureIndex()can render a replica set
inaccessible as the index creation is happening. SeeBuild Indexes on Replica Sets(page 469).
11.8.2
To list a collection's indexes, use thedb.collection.getIndexes() method or a similar
driver
28
.
11.8.3
To check the sizes of the indexes on a collection, usedb.collection.stats() .
27
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
28
http://api.mongodb.org/
718 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.8.4
When an index is too large to t into RAM, MongoDB must read the index from disk, which is a much slower operation
than reading from RAM. Keep in mind an index ts into RAM when your server has RAM available for the index
combined with the rest of theworking set.
In certain cases, an index does not need to tentirelyinto RAM. For details, seeIndexes that Hold Only Recent Values
in RAM(page 498).
11.8.5
To inspect how MongoDB processes a query, use theexplain()method in themongoshell, or in your application
driver.
11.8.6
A number of factors determine what elds to index, includingselectivity(page 498), tting indexes into RAM, reusing
indexes in multiple queries when possible, and creating indexes that can support all the elds in a given query. For
detailed documentation on choosing which elds to index, seeIndexing Tutorials(page 464).
11.8.7
Any write operation that alters an indexed eld 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.
11.8.8
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. SeeIndex Creation(page 460).
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:

db.killOp()). The partial index will be deleted.
11.8.9
You can use themin()andmax()methods to constrain the results of the cursor returned fromfind()by using
index keys.
11.8.10 $neand$ninin a query is slow. Why?
The$neand$ninoperators are not selective. SeeCreate Queries that Ensure Selectivity(page 498). If you need to
use these, it is often best to make sure that an additional, more selective criterion is part of the query.
11.8. FAQ: Indexes 719

MongoDB Documentation, Release 2.6.4
11.8.11
Not entirely. The index can partially support these queries because it can speed the selection of the rst element of
the array; however, comparing all subsequent items in the array cannot use the index and must scan the documents
individually.
11.8.12
For simple attribute lookups that don't require sorted result sets or range queries, consider creating a eld that contains
an array of documents where each document has a eld (e.g.attrib) that holds a specic type of attribute. You can
index thisattribeld.
For example, theattribeld in the following document allows you to add an unlimited number of attributes types:
{ _id
attrib
{ k:, v:
{ k:::
{ k:::
{ k::: true}
]
}
Bothof the following queries could use the same{ "attrib.k": 1, "attrib.v": 1 } index:
db.mycollection.find( { attrib::, v:
db.mycollection.find( { attrib::, v: true} } } )
11.9
This document provides answers to common diagnostic questions and issues.
If you don't nd the answer you're looking for, check thecomplete list of FAQs(page 687) or post your question to
the
29
.
11.9.1 mongodprocess that stopped running
unexpectedly?
Ifmongodshuts down unexpectedly on a UNIX or UNIX-based platform, and ifmongodfails 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
11.9.2 keepalivetime 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 reason-
able causes, check the TCP keep alive value, which Linux systems store as thetcp_keepalive_time value. A
common keep alive period is7200seconds (2 hours); however, different distributions and OS X may have different
29
https://groups.google.com/forum/?fromgroups#!forum/mongodb-user
720 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
settings. For MongoDB, you will have better experiences with shorter keepalive periods, on the order of300seconds
(ve minutes).
On Linux systems you can use the following operation to check the value oftcp_keepalive_time:
cat /proc/sys/net/ipv4/tcp_keepalive_time
You can change thetcp_keepalive_time value with the following operation:
echo
The newtcp_keepalive_time value takes effect without requiring you to restart themongodormongos
servers. When you reboot or restart your system you will need to set the newtcp_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
hostingmongosormongodservers.
Windows users should consider the
30
for more
information on setting keep alive for MongoDB deployments on Windows systems.
11.9.3
TheMongoDB Management Services <http://mms.mongodb.com>includes monitoring. MMS Monitoring is a free,
hosted services for monitoring MongoDB deployments. A full list of third-party tools is available as part of the
Monitoring for MongoDB(page 175) documentation. Also consider the
31
.
11.9.4
Do I need to congure swap space?
Always congure 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 MongoDBdo notneed swap for routine operation. Database les arememory-mapped
(page 714) and should constitute most of your MongoDB memory use. Therefore, it is unlikely thatmongodwill ever
use any swap space in normal operation. The operating system will release memory from the memory mapped les
without needing swap and MongoDB can write data to the data les without needing the swap system.
30
http://technet.microsoft.com/en-us/library/dd349797.aspx#BKMK_2
31
http://mms.mongodb.com/help/
11.9. FAQ: MongoDB Diagnostics 721

MongoDB Documentation, Release 2.6.4
What is working set and how can I estimate its size?
Theworking setfor a MongoDB database is the portion of your data that clients access most often. You can es-
timate size of the working set, using theworkingSetdocument in the output ofserverStatus. To return
serverStatuswith theworkingSetdocument, issue a command in the following form:
db.runCommand( { serverStatus:, workingSet:
Must my working set size t 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 specically 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 contin-
ually 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 ne 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:
database storage(page 714) and working set.

journaling(page 275)

MongoDB defers to the operating system when loading data into memory from disk. It simplymemory maps
(page 714) all its data les 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 ts 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 UNIXtopcommand
Becausemongodusesmemory-mapped les(page 714), the memory statistics intoprequire interpretation in a
special way. On a large database,VSIZE(virtual bytes) tends to be the size of the entire database. If themongod
doesn't have other processes running,RSIZE(resident bytes) is the total memory of the machine, as this counts le
system cache contents.
For Linux systems, use thevmstatcommand to help determine how the system uses memory. On OS X systems use
vm_stat.
722 Chapter 11. Frequently Asked Questions

MongoDB Documentation, Release 2.6.4
11.9.5
The two most important factors in maintaining a successful sharded cluster are:
choosing an appropriate shard key(page 620) and
sufcient capacity to support current and future operations(page 617).
You can prevent most issues encountered with sharding by ensuring that you choose the best possibleshard keyfor
your deployment and ensure that you are always adding additional capacity to your cluster well before the current
resources become saturated. Continue reading for specic 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 sufcient 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 themigration threshold(page 630). While the default chunk size is congurable with thechunkSize
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 sufcient data to create more than eight 64 megabyte chunks, then all data will remain on one shard. Either
lower thechunk size(page 633) 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 congure
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 dataor (page 666).
Finally, if your shard key has a lowcardinality(page 640), MongoDB may not be able to create sufcient splits among
the data.
Why would one shard receive a disproportion amount of trafc in a sharded cluster?
In some situations, a single shard or a subset of the cluster will receive a disproportionate portion of the trafc and
workload. In almost all cases this is the result of a shard key that does not effectively allowwrite scaling(page 621).
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 andchoosing a different shard key(page 639) 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 thetroubleshooting suggestions for a new
cluster where data remains on a single shard(page 723).
If the cluster was initially balanced, but later developed an uneven distribution of data, consider the following possible
causes:

may have a different distribution with regards to its shard key.
shard keyhas lowcardinality(page 640) and MongoDB cannot split the chunks any further.
11.9. FAQ: MongoDB Diagnostics 723

MongoDB Documentation, Release 2.6.4

typically is the result of:
abalancing window(page 660) that is too short, given the rate of data growth.
an uneven distribution ofwrite operations(page 621) 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 conguration 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:
1. balancing window(page 660) to prevent
balancing activity during peak hours. Ensure that there is enough time remaining to keep the data from becoming
out of balance again.
2.
decreasing the chunk size(page 671) to limit the size of the migration.
add one or two shards(page 642) 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 betterwrite scaling(page 621).
724 Chapter 11. Frequently Asked Questions

CHAPTER12
Release Notes
Always install the latest, stable version of MongoDB. SeeMongoDB Version Numbers(page 808) for more informa-
tion.
See the following release notes for an account of the changes in major versions. Release notes also include instructions
for upgrade.
12.1
(2.6-series)
12.1.1
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
tation
1
and the
2
for more information.
Minor Releases
2.6 Changelog
2.6.4 Changes
Security

3
The backup auth role should allow running the collstats command for all resources

4
Allow disabling hostname validation for SSL

5
Potential information leak
1
https://mms.mongodb.com/help-hosted/v1.4/
2
https://mms.mongodb.com/help-hosted/v1.4/management/changelog/
3
https://jira.mongodb.org/browse/SERVER-14701
4
https://jira.mongodb.org/browse/SERVER-14518
5
https://jira.mongodb.org/browse/SERVER-14268
725

MongoDB Documentation, Release 2.6.4

6
Cannot read from secondary if both audit and auth are enabled in a sharded cluster

7
userAdminAnyDatabase role should be able to create indexes on admin.system.users and
admin.system.roles

8
Add role-based, selective audit logging.

9
Add build ag for sslFIPSMode
Querying

10
Query planner can construct incorrect bounds for negations inside $elemMatch

11
hash intersection of fetched and non-fetched data can discard data from a result

12
Improve logging in the case of plan ranker ties

13
Server crash when $centerSphere has non-positive radius

14
Dead code in IDHackRunner::applyProjection

15
skipping of index keys is not accounted for in plan ranking by the index scan stage

16
some operations can create BSON object larger than the 16MB limit

17
Sorted $in query with large number of elements can't use merge sort

18
do not aggressively pre-fetch data for parallelCollectionScan
Replication

19
Build failure for v2.6 in closeall.js caused by access violation reading _me

20
cannot dropAllIndexes when index builds in progress assertion failure

21
Dropping collection during active background index build on secondary triggers segfault

22
Running resync before replset cong is loaded can crashmongod

23
Replication `isself' check should allow mapped ports
Sharding

24
Runner yield during migration cleanup (removeRange) results in fassert
6
https://jira.mongodb.org/browse/SERVER-14170
7
https://jira.mongodb.org/browse/SERVER-13833
8
https://jira.mongodb.org/browse/SERVER-12512
9
https://jira.mongodb.org/browse/SERVER-9482
10
https://jira.mongodb.org/browse/SERVER-14625
11
https://jira.mongodb.org/browse/SERVER-14607
12
https://jira.mongodb.org/browse/SERVER-14532
13
https://jira.mongodb.org/browse/SERVER-14350
14
https://jira.mongodb.org/browse/SERVER-14317
15
https://jira.mongodb.org/browse/SERVER-14311
16
https://jira.mongodb.org/browse/SERVER-14123
17
https://jira.mongodb.org/browse/SERVER-14034
18
https://jira.mongodb.org/browse/SERVER-13994
19
https://jira.mongodb.org/browse/SERVER-14665
20
https://jira.mongodb.org/browse/SERVER-14505
21
https://jira.mongodb.org/browse/SERVER-14494
22
https://jira.mongodb.org/browse/SERVER-13822
23
https://jira.mongodb.org/browse/SERVER-11776
24
https://jira.mongodb.org/browse/SERVER-14551
726 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4

25
Invalid chunk data after splitting on a key that's too large

26
stepdown during migration range delete can abortmongod

27
v2.6mongosdoesn't verify _id is present for cong server upserts

28
better stats from migration cleanup

29
mongosshouldn't accept initial query with exhaust ag set

30
mongosdoes not re-evaluate read preference once a valid replica set member is chosen

31
Log messages regarding chunks not very informative when the shard key is of type BinData
Storage

32
Std::set<pointer> and Windows Heap Allocation Reuse produces non-deterministic results

33
Creating index on collection named system can cause server to abort

34
Reads & Writes are blocked during data le allocation on Windows

35
mongodB stalls during background ush on Windows
IndexingSERVER-14494
36
Dropping collection during active background index build on secondary triggers seg-
fault
Write Ops

37
remove command can cause process termination by throwing unhandled exception if pro-
ling is enabled

38
Update fails when query contains part of a DBRef and results in an insert (upsert:true)

39
debug mechanisms report incorrect nscanned / nscannedObjects for updates
NetworkingSERVER-13734
40
Remove catch (...) from handleIncomingMsg
Geo

41
$nearSphere query with 2d index, skip, and limit returns incomplete results

42
Query using 2d index throws exception when using explain()
25
https://jira.mongodb.org/browse/SERVER-14431
26
https://jira.mongodb.org/browse/SERVER-14261
27
https://jira.mongodb.org/browse/SERVER-14032
28
https://jira.mongodb.org/browse/SERVER-13648
29
https://jira.mongodb.org/browse/SERVER-12750
30
https://jira.mongodb.org/browse/SERVER-9788
31
https://jira.mongodb.org/browse/SERVER-9526
32
https://jira.mongodb.org/browse/SERVER-14198
33
https://jira.mongodb.org/browse/SERVER-13975
34
https://jira.mongodb.org/browse/SERVER-13729
35
https://jira.mongodb.org/browse/SERVER-13681
36
https://jira.mongodb.org/browse/SERVER-14494
37
https://jira.mongodb.org/browse/SERVER-14257
38
https://jira.mongodb.org/browse/SERVER-14024
39
https://jira.mongodb.org/browse/SERVER-13764
40
https://jira.mongodb.org/browse/SERVER-13734
41
https://jira.mongodb.org/browse/SERVER-14039
42
https://jira.mongodb.org/browse/SERVER-13701
12.1. Current Stable Release 727

MongoDB Documentation, Release 2.6.4
Text Search

43
Updates to documents with text-indexed elds may lead to incorrect entries

44
Renaming collection within same database fails if wildcard text index present
Tools

45
mongorestoremay drop system users and roles

46
mongodumpagainstmongoscan't send dump to standard output
Admin

47
Default dbpath formongod--configsvrchanges in 2.6

48
Allow dbAdmin role to manually create system.prole collections
PackagingSERVER-14283
49
Parameters in installed cong le are out of date
JavaScript

50
Do not store native function pointer as a property in function prototype

51
v8 garbage collection can cause crash due to independent lifetime of DBClient and Cursor
objects

52
mongo shell may crash when converting invalid regular expression
Shell

53
negative opcounter values in serverStatus

54
Querying for a document containing a value of either type Javascript or JavascriptWithScope
crashes the shell
UsabilitySERVER-13833
55
userAdminAnyDatabase role should be able to create indexes on admin.system.users
and admin.system.roles
43
https://jira.mongodb.org/browse/SERVER-14738
44
https://jira.mongodb.org/browse/SERVER-14027
45
https://jira.mongodb.org/browse/SERVER-14212
46
https://jira.mongodb.org/browse/SERVER-14048
47
https://jira.mongodb.org/browse/SERVER-14556
48
https://jira.mongodb.org/browse/SERVER-14355
49
https://jira.mongodb.org/browse/SERVER-14283
50
https://jira.mongodb.org/browse/SERVER-14254
51
https://jira.mongodb.org/browse/SERVER-13798
52
https://jira.mongodb.org/browse/SERVER-13707
53
https://jira.mongodb.org/browse/SERVER-14341
54
https://jira.mongodb.org/browse/SERVER-14107
55
https://jira.mongodb.org/browse/SERVER-13833
728 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Logging and Diagnostics

56
Add role-based, selective audit logging.

57
negative opcounter values in serverStatus
Testing

58
plan_cache_ties.js sometimes fails

59
make index_multi.js retry on connection failure

60
sharding_rs2.js intermittent failure due to reliance on opcounters
2.6.3 Changes

61
Fixed: Equality queries on_idwith projection may return no results on sharded collec-
tions

62
Fixed: Equality queries on_idwith projection on_idmay return orphan documents on
sharded collections
2.6.2 Changes
Security

63
Thebackup(page 367) authorization role now includes privileges to run thecollStats
command.

64
The built-in rolerestore(page 367) now has privileges onsystem.rolescollection.

65
Fixed: SSL-enabled server appears not to be sending the list of supported certicate issuers
to the client

66
Fixed: mongodmay terminate if x.509 authentication certicate is invalid

67
Forreplica set/sharded cluster member authentication(page 323), now matches x.509 cluster
certicates by attributes instead of by substring comparison.

68
Now marks V1 users as probed on databases that do not have surrogate user documents.

69
Now ensures that the user cache entry is up to date before using it to determine a user's roles
in user management commands onmongos.

70
Fixed: Shell prints startup warning when auth enabled
56
https://jira.mongodb.org/browse/SERVER-12512
57
https://jira.mongodb.org/browse/SERVER-14341
58
https://jira.mongodb.org/browse/SERVER-14731
59
https://jira.mongodb.org/browse/SERVER-14147
60
https://jira.mongodb.org/browse/SERVER-13615
61
https://jira.mongodb.org/browse/SERVER-14302
62
https://jira.mongodb.org/browse/SERVER-14304
63
https://jira.mongodb.org/browse/SERVER-13727
64
https://jira.mongodb.org/browse/SERVER-13804
65
https://jira.mongodb.org/browse/SERVER-13612
66
https://jira.mongodb.org/browse/SERVER-13753
67
https://jira.mongodb.org/browse/SERVER-13945
68
https://jira.mongodb.org/browse/SERVER-13868
69
https://jira.mongodb.org/browse/SERVER-13850
70
https://jira.mongodb.org/browse/SERVER-13588
12.1. Current Stable Release 729

MongoDB Documentation, Release 2.6.4
Querying

71
Fixed: Stack overow when parsing deeply nested$notquery

72
Fixed: Index bounds builder constructs invalid bounds for multiple negations joined by an
$or

73
Veried assertion on empty$inclause and sort on second eld in a compound index.

74
Re-enabledidhackfor queries with projection.

75
Fixed: Aggregation pipeline execution can fail with $or and blocking sorts

76
Fixed: non-top-level indexable$nottriggers query planning bug

77
Fixed: distinctcommand on indexed eld with geo predicate fails to execute

78
Fixed Plans with differing performance can tie during plan ranking

79
Fixed: `Whole index scan' query solutions can use incompatible indexes, return incorrect
results

80
Fixed IndexBounds::endKeyInclusive not initialized by constructor

81
planSummary no longer truncated at 255 characters

82
Fixed: If ntoreturn is a limit (rather than batch size) extra data gets buffered during plan
ranking

83
Some nested queries no longer trigger an assertion error

84
Added planSummary information forcountcommand log message.

85
Queries containing$orno longer miss results if multiple clauses use the same index.

86
Fixed: Crash with `and' clause,$elemMatch, and nested$modor regex

87
Natural order sort specication no longer ignored if query is specied.

88
Bounds no longer combined for$orqueries that can use merge sort.
GeospatialSERVER-13687
89
Results of$nearquery on compound multi-key 2dsphere index are now sorted by
distance.
Write OperationsSERVER-13802
90
Insert eld validation no longer stops at rstTimestamp()eld.
71
https://jira.mongodb.org/browse/SERVER-13731
72
https://jira.mongodb.org/browse/SERVER-13890
73
https://jira.mongodb.org/browse/SERVER-13752
74
https://jira.mongodb.org/browse/SERVER-13337
75
https://jira.mongodb.org/browse/SERVER-13715
76
https://jira.mongodb.org/browse/SERVER-13714
77
https://jira.mongodb.org/browse/SERVER-13769
78
https://jira.mongodb.org/browse/SERVER-13675
79
https://jira.mongodb.org/browse/SERVER-13899
80
https://jira.mongodb.org/browse/SERVER-13852
81
https://jira.mongodb.org/browse/SERVER-14073
82
https://jira.mongodb.org/browse/SERVER-14174
83
https://jira.mongodb.org/browse/SERVER-13789
84
https://jira.mongodb.org/browse/SERVER-14064
85
https://jira.mongodb.org/browse/SERVER-13960
86
https://jira.mongodb.org/browse/SERVER-14180
87
https://jira.mongodb.org/browse/SERVER-14176
88
https://jira.mongodb.org/browse/SERVER-13754
89
https://jira.mongodb.org/browse/SERVER-13687
90
https://jira.mongodb.org/browse/SERVER-13802
730 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Replication

91
Fixed: log a message whenshouldChangeSyncTarget() believes a node should
change sync targets

92
Fixed: Cloner needs to detect failure to create collection
Sharding

93
Resolved: `type 7' (OID) error when acquiring distributed lock for rst time

94
Now catches exception thrown bygetShardsForQueryfor geo query.

95
mongoswill now correctly target multiple shards for nested eld shard key predicates.

96
Fixed: Authentication requests delayed if rst cong server is unresponsive
Map/Reduce

97
Resolved: rs.stepDownduring mapReduce causes fassert in logOp

98
Temporary map/reduce collections are now correctly replicated to secondaries.
Storage

99
convertToCappedon empty collection no longer aborts afterinvariant()failure.

100
Moving large collection across databases with renameCollection no longer triggers fatal
assertion.

101
Fixed: Excessive freelist scanning for MaxBucket

102
CollectionOptions parser now skips non-numeric for size/max elements if values non-
numeric.
Build and Packaging

103
MongoDB Enterprise now includes required dependency list.

104
Support for mongodb-org-server installation 2.6.1-1 on RHEL5 via RPM.

105
Added SCons ag to override treating all warnings as errors.
91
https://jira.mongodb.org/browse/SERVER-13993
92
https://jira.mongodb.org/browse/SERVER-13976
93
https://jira.mongodb.org/browse/SERVER-13616
94
https://jira.mongodb.org/browse/SERVER-13812
95
https://jira.mongodb.org/browse/SERVER-14138
96
https://jira.mongodb.org/browse/SERVER-11332
97
https://jira.mongodb.org/browse/SERVER-14186
98
https://jira.mongodb.org/browse/SERVER-13981
99
https://jira.mongodb.org/browse/SERVER-13750
100
https://jira.mongodb.org/browse/SERVER-14056
101
https://jira.mongodb.org/browse/SERVER-14082
102
https://jira.mongodb.org/browse/SERVER-13737
103
https://jira.mongodb.org/browse/SERVER-13950
104
https://jira.mongodb.org/browse/SERVER-13862
105
https://jira.mongodb.org/browse/SERVER-13724
12.1. Current Stable Release 731

MongoDB Documentation, Release 2.6.4
Diagnostics

106
Resolved: ndeletedinsystem.profiledocuments reports 1 too few documents
removed

107
Improved exposure of timing information incurrentOp.
AdministrationSERVER-13954
108
security.javascriptEnabled option is now available in the YAML
conguration le.
Tools

109
mongodumpcan now queryoplog.$mainandoplog.rswhen using--dbpath.

110
mongoexportcan now handle large timestamps on Windows.
Shell

111
Shell now returns correctWriteResultfor compatibility-mode upsert with non-OID
equality predicate on_ideld.

112
Fixed typo in error message for compatibility mode.
Internal Code

113
Fixed: Unused snapshot history consuming signicant heap space

114
Removed Solaris builds dependency on ILLUMOS libc.

115
MongoDB upgrade 2.4 to 2.6 check no longer returns an error in internal collections.

116
Added new lsb le location for Debian 7.1
Testing

117
Stabilizedtags.jsafter a change in its timeout when it was ported to use write commands.

118
Fixed: setup_multiversion_mongodb.py doesn't download 2.4.10 because of
non-numeric version sorting

119
Fixed: Test suites with options tests fail when run with--nopreallocj

120
Fixed: awaitReplication() failures related to getting a cong version from master
causing test failures
106
https://jira.mongodb.org/browse/SERVER-13587
107
https://jira.mongodb.org/browse/SERVER-13368
108
https://jira.mongodb.org/browse/SERVER-13954
109
https://jira.mongodb.org/browse/SERVER-10464
110
https://jira.mongodb.org/browse/SERVER-13760
111
https://jira.mongodb.org/browse/SERVER-13865
112
https://jira.mongodb.org/browse/SERVER-13037
113
https://jira.mongodb.org/browse/SERVER-13794
114
https://jira.mongodb.org/browse/SERVER-13446
115
https://jira.mongodb.org/browse/SERVER-14092
116
https://jira.mongodb.org/browse/SERVER-14000
117
https://jira.mongodb.org/browse/SERVER-13723
118
https://jira.mongodb.org/browse/SERVER-13494
119
https://jira.mongodb.org/browse/SERVER-13603
120
https://jira.mongodb.org/browse/SERVER-13948
732 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4

121
Fixedsync2.jsfailure.

122
Fixedconnections_opened.js failure.

123
Reduced peak disk usage of test suites.

124
Added tests for querying oplog viamongodumpusing--dbpath

125
Fixed: Windows le locking related buildbot failures
2.6.1 Changes
StabilitySERVER-13739
126
Repair database failure can delete database les
Build and Packaging

127
Addition of debug symbols has doubled compile time

128
Upgrading from 2.4.x to 2.6.0 viayumclobbers conguration le

129
yum and apt stable repositories contain release candidate 2.6.1-rc0 packages

130
Cannot install MongoDB as a service on Windows
Querying

131
Negations over multikey elds do not use index

132
ConcurrentGETMOREandKILLCURSORSoperations can cause race condition and server
crash

133
The$whereoperator should not be allowed under$elemMatch

134
Large skip and and limit values can cause crash in blocking sort stage

135
Incorrect negation of $elemMatch value in 2.6

136
Queries that use tailable cursors do not stream results if skip() is applied

137
Using the OplogReplay ag with extra predicates can yield incorrect results

138
Missing sort order for compound index leads to unnecessary in-memory sort

139
Optimization for sorted $in queries not applied to reverse sort order
121
https://jira.mongodb.org/browse/SERVER-13839
122
https://jira.mongodb.org/browse/SERVER-13972
123
https://jira.mongodb.org/browse/SERVER-13712
124
https://jira.mongodb.org/browse/SERVER-14249
125
https://jira.mongodb.org/browse/SERVER-10462
126
https://jira.mongodb.org/browse/SERVER-13739
127
https://jira.mongodb.org/browse/SERVER-13287
128
https://jira.mongodb.org/browse/SERVER-13563
129
https://jira.mongodb.org/browse/SERVER-13691
130
https://jira.mongodb.org/browse/SERVER-13515
131
https://jira.mongodb.org/browse/SERVER-13066
132
https://jira.mongodb.org/browse/SERVER-13495
133
https://jira.mongodb.org/browse/SERVER-13503
134
https://jira.mongodb.org/browse/SERVER-13537
135
https://jira.mongodb.org/browse/SERVER-13557
136
https://jira.mongodb.org/browse/SERVER-13562
137
https://jira.mongodb.org/browse/SERVER-13566
138
https://jira.mongodb.org/browse/SERVER-13611
139
https://jira.mongodb.org/browse/SERVER-13618
12.1. Current Stable Release 733

MongoDB Documentation, Release 2.6.4

140
Increase the maximum allowed depth of query objects

141
Query with$elemMatchusing a compound multikey index can generate incorrect results

142
Query planner should traverse through $all while handling $elemMatch object predicates

143
Dropping index or collection while $or query is yielding triggers fatal assertion
Geospatial

144
$nearqueries with out-of-bounds points in legacy format can lead to crashes

145
ThegeoNearcommand no longer returns distance in radians for legacy point

146
: ThegeoNearcommand can create too large BSON objects for aggregation.
Replication

147
Changing replica set conguration can crash running members

148
Background index builds from a 2.6.0 primary fail to complete on 2.4.x secondaries

149
Replicated data denition commands will fail on secondaries during background index build

150
Creating index with same name but different spec in mixed version replicaset can abort
replication
Sharding

151
Initial sharding with hashed shard key can result in duplicate split points

152
The_ideld is no longer automatically generated bymongoswhen missing

153
Migrated ranges waiting for deletion do not report cursors still open
Security

154
Log rotation can overwrite previous log les

155
Sensitive credentials in startup options are not redacted and may be exposed

156
Inconsistent error handling in user management shell helpers
140
https://jira.mongodb.org/browse/SERVER-13661
141
https://jira.mongodb.org/browse/SERVER-13664
142
https://jira.mongodb.org/browse/SERVER-13677
143
https://jira.mongodb.org/browse/SERVER-13766
144
https://jira.mongodb.org/browse/SERVER-13666
145
https://jira.mongodb.org/browse/SERVER-13540
146
https://jira.mongodb.org/browse/SERVER-13486
147
https://jira.mongodb.org/browse/SERVER-13500
148
https://jira.mongodb.org/browse/SERVER-13589
149
https://jira.mongodb.org/browse/SERVER-13620
150
https://jira.mongodb.org/browse/SERVER-13496
151
https://jira.mongodb.org/browse/SERVER-12638
152
https://jira.mongodb.org/browse/SERVER-13518
153
https://jira.mongodb.org/browse/SERVER-13777
154
https://jira.mongodb.org/browse/SERVER-9358
155
https://jira.mongodb.org/browse/SERVER-13644
156
https://jira.mongodb.org/browse/SERVER-13441
734 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Write Operations

157
Error message in collection creation failure contains incorrect namespace

158
Yield policy for batch-inserts should be the same as for batch-updates/deletes

159
Array updates on documents with more than 128 BSON elements may crashmongod
2.6.4 August 11, 2014
textindex where under specic circumstances, in-place updates to atext-indexed eld may result in
incorrect/incomplete results
160

161

back to the pool at the end of a query/command
162

14170
163

164
2.6.3 June 19, 2014
_idwith projection may return no results on sharded collections
165
.
_idwith projection on_idmay return orphan documents on sharded collections
14304
166
.

167
.
2.6.2 June 16, 2014

168
.
mongodmay terminate if x.509 authentication certicate is invalid
169
.

170
.
mongosincorrectly targets multiple shards for nested eld shard key predicates
171
.
rs.stepDown()during mapReduce causesfassertwhen writing to op log
172
.
157
https://jira.mongodb.org/browse/SERVER-13466
158
https://jira.mongodb.org/browse/SERVER-13499
159
https://jira.mongodb.org/browse/SERVER-13516
160
https://jira.mongodb.org/browse/SERVER-14738
161
https://jira.mongodb.org/browse/SERVER-14431
162
https://jira.mongodb.org/browse/SERVER-9788
163
https://jira.mongodb.org/browse/SERVER-14170
164
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.6.4%22%20AND%20project%20%3D%20SERVER
165
https://jira.mongodb.org/browse/SERVER-14302
166
https://jira.mongodb.org/browse/SERVER-14304
167
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.6.3%22%20AND%20project%20%3D%20SERVER
168
https://jira.mongodb.org/browse/SERVER-13675
169
https://jira.mongodb.org/browse/SERVER-13753
170
https://jira.mongodb.org/browse/SERVER-13981
171
https://jira.mongodb.org/browse/SERVER-14138
172
https://jira.mongodb.org/browse/SERVER-14186
12.1. Current Stable Release 735

MongoDB Documentation, Release 2.6.4

173
.
2.6.1 May 5, 2014
--installoption
174
.
yumSERVER-13563
175
.

176
and
177
.

178
.
2.6.1 Changelog(page 733).

179
.
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.
db.collection.aggregate() now returns a cursor, which enables the aggregation pipeline to return
result sets of any size.
explainoperation to aid analysis of aggregation operations.

$outstage to output to a collection.
$redactstage to allow additional control to accessing the data.

set expression operators .
$letand$mapoperators to allow for the use of variables.
$literaloperator and$sizeoperator.
$condexpression now accepts either an object or an array.
173
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.6.2%22%20AND%20project%20%3D%20SERVER
174
https://jira.mongodb.org/browse/SERVER-13515
175
https://jira.mongodb.org/browse/SERVER-13563
176
https://jira.mongodb.org/browse/SERVER-13589
177
https://jira.mongodb.org/browse/SERVER-13620
178
https://jira.mongodb.org/browse/SERVER-13644
179
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.6.1%22%20AND%20project%20%3D%20SERVER
736 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Text Search Integration
Text search is now enabled by default, and the query system, including the aggregation pipeline$matchstage,
includes the$textoperator, which resolves text-search queries.
MongoDB 2.6 includes an updatedtext index(page 454) format and deprecates thetextcommand.
Insert and Update Improvements
Improvements to the update and insert systems include additional operations and improvements that increase consis-
tency of modied data.
exceptfor the following cases:
The_ideld is always the rst eld in the document.
Updates that includerenamingof eld names may result in the reordering of elds in the document.

$bitoperator supports bitwisexoroperation.
$minand$maxoperators that perform conditional update depending on the relative size of the specied
value and the current value of a eld.
$pushoperator has enhanced support for the$sort,$slice, and$eachmodiers and supports a new
$positionmodier.
$currentDateoperator to set the value of a eld to the current date.
$muloperator for multiplicative increments for insert and update operations.
See also:
Update Operator Syntax Validation(page 746)
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 commandsinsert,update, anddelete, which provide the basis for the improved
bulk insert. All ofcially supported MongoDB drivers support the new write commands.
Themongoshell now includes methods to perform bulk-write operations. SeeBulk()for more information.
See also:
Write Method Acknowledgements(page 743)
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.
12.1. Current Stable Release 737

MongoDB Documentation, Release 2.6.4
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.
Specically these changes include:
authorization model(page 285) that provides the ability to create customUser-Dened Roles(page 286)
and the ability to specify user privileges at a collection-level granularity.
admindatabase and provides
a new set of commands for managing users and roles.
client authentication(page 320) as well as forinternal authentication
(page 323) of sharded and/or replica set cluster members. x.509 authentication is only available for deploy-
ments using SSL.

Rolling upgrades of clusters(page 311) to use SSL.
MongoDB Tools(page 310) support connections tomongodandmongosinstances using SSL connec-
tions.
Prompt for passphrase(page 306) bymongodormongosat 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.
network exposure(page 288). To enable the interface,
seeenabled.
See also:
New Authorization Model(page 744),SSL Certicate Hostname Validation(page 745), andSecurity Checklist
(page 295).
Query Engine Improvements
index intersection(page 462) to fulll queries supported by more than one index.
Index Filters(page 63) to limit which indexes can become the winning plan for a query.
http://docs.mongodb.org/manualreference/method/js-plan-cache methods to view and
clear thequery plans(page 61) cached by the query optimizer.
count()withhint(). Seecount()for details.
Improvements
Geospatial Enhancements
2dsphere indexes version 2(page 447).
MultiPoint(page 449),MultiLineString(page 450),MultiPolygon(page 450), andGeometryCollec-
tion(page 450).
$orexpressions.
738 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
See also:
2dsphere Index Version 2(page 745),$maxDistance Changes(page 748),Deprecated $uniqueDocs(page 748),
Stronger Validation of Geospatial Queries(page 748)
Index Build Enhancements
Background index build(page 461) allowed on secondaries. If you initiate a background index build on a
primary, the secondaries will replicate the index build in the background.

If a standalone or a primary instance terminates during an index buildwithout 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, themongodinstance will now restart the inter-
rupted index build when the instance restarts.
To disable this behavior, use the--noIndexBuildRetry command-line option.
ensureIndex()now wraps a newcreateIndexcommand.
dropDupsoption toensureIndex()andcreateIndexis deprecated.
See also:
Enforce Index Key Length Limit(page 741)
Enhanced Sharding and Replication Administration
cleanupOrphanedcommand to removeorphaned documentsfrom a shard.
mergeChunkscommand to combine contiguous chunks located on a single shard. SeemergeChunks
andMerge Chunks in a Sharded Cluster(page 668).
rs.printReplicationInfo() andrs.printSlaveReplicationInfo() methods to pro-
vide a formatted report of the status of a replica set from the perspective of the primary and the secondary,
respectively.
Conguration Options YAML File Format
MongoDB 2.6 supports a YAML-based conguration le format in addition to the previous conguration le format.
Seehttp://docs.mongodb.org/manualreference/configuration-options for details.
Operational Changes
Storage
usePowerOf2Sizesis 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 previousexact-t allocation strategy:
collModwithusePowerOf2Sizesset tofalse.
12.1. Current Stable Release 739

MongoDB Documentation, Release 2.6.4
mongodinstance, setnewCollectionsUsePowerOf2Sizes to
false.
SeeStorage(page 82) for more information about MongoDB's storage system.
Networking
maxIncomingConnections formongodandmongos. Previous versions
capped the maximum possiblemaxIncomingConnections setting at20,000connections.
mongosinstance 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.
replica sethealth with theisMastercommand instead of
replSetGetStatus. This allows the C++ driver to support systems that require authentication.
cursor.maxTimeMS() and correspondingmaxTimeMSoption for commands to specify a time limit.
Tool Improvements
mongoshell supports a global/etc/mongorc.js.
executable filesnow support the--quietoption to suppress all logging output except
for error messages.
mongoimportuses the input lename, without the le extension if any, as the collection name if run without
the-cor--collectionspecication.
mongoexportcan now constrain export data using--skipand--limit, as well as order the documents
in an export using the--sortoption.
mongostatcan support the use of--rowcount(-n) with the--discoveroption to produce the specied
number of output lines.
data_numberlongfor use bymongoexportandmongoimport.
MongoDB Enterprise Features
The following changes are specic to MongoDB Enterprise Editions:
MongoDB Enterprise for Windows
MongoDB Enterprise for Windows(page 36) is now available. It includes support for Kerberos, SSL, and SNMP.
MongoDB Enterprise for Windows doesnotinclude 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 addsauditing(page 290) capability formongodandmongosinstances. SeeAuditing
(page 290) for details.
740 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
LDAP Support for Authentication
MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to congure a
MongoDB cluster to authenticate users by proxying authentication requests to a specied Lightweight Directory Ac-
cess Protocol (LDAP) service. SeeAuthenticate Using SASL and LDAP with OpenLDAP(page 329) andAuthenticate
Using SASL and LDAP with ActiveDirectory(page 326) for details.
MongoDB Enterprise for Windows doesnotinclude LDAP support for authentication. However, MongoDB Enterprise
for Linux supports using LDAP authentication with an ActiveDirectory server.
MongoDB doesnotsupport LDAP authentication in mixed sharded cluster deployments that contain both version 2.4
and version 2.6 shards. SeeUpgrade MongoDB to 2.6(page 751) 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 bydb.serverStatus().
See also:
SNMP Changes(page 746)
Additional Information
Changes Affecting Compatibility
Compatibility Changes in MongoDB 2.6The following 2.6 changes can affect the compatibility with older ver-
sions of MongoDB. SeeRelease Notes for MongoDB 2.6(page 725) for the full list of the 2.6 changes.
Index Changes
Enforce Index Key Length Limit
DescriptionMongoDB 2.6 implements a stronger enforcement of the limit onindex key.
Creating indexes will error if an index key in an existing document exceeds the limit:
db.collection.ensureIndex() ,db.collection.reIndex() ,compact, and
repairDatabasewill error and not create the index. Previous versions of MongoDB would
create the index but not index such documents.
db.collection.reIndex() ,compact, andrepairDatabasedropallthe indexes
from a collection and then recreate them sequentially, the error from the index key limit prevents these oper-
ations from rebuilding any remaining indexes for the collection and, in the case of therepairDatabase
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() anddb.collection.update() withupsertthat result in in-
serts) will fail to insert if the new document has an indexed eld whose corresponding index entry exceeds
the limit. Previous versions of MongoDB would insert but not index such documents.
mongorestoreandmongoimportwill fail to insert if the new document has an indexed eld whose
corresponding index entry exceeds the limit.
12.1. Current Stable Release 741

MongoDB Documentation, Release 2.6.4
Updates will error:
db.collection.update() anddb.collection.save() operations on an indexed eld will
error if the updated value causes the index entry to exceed the limit.

elds that result in the relocation of a document on disk will error.
Chunk Migration will fail:

limit.

lection. Or, if chunk splits occur in response to the migration failures, this response would lead to unnec-
essarily large number of chunks and an overly large cong databases.
Secondary members of replica sets will warn:

exceeds the limit on initial sync but will print warnings in the logs.

corresponding index entry exceeds the limit but with warnings in the logs.
mixed versionreplica 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 eld whose corresponding index entry exceeds the limit.
SolutionRundb.upgradeCheckAllDBs() to nd current keys that violate this limit and correct as appropriate.
Preferably, run the test before upgrading; i.e. connect the 2.6mongoshell 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 thefailIndexKeyTooLong parameter.
Index Specications Validate Field Names
DescriptionIn MongoDB 2.6, create and re-index operations fail when the index key refers to an empty eld, e.g.
"a..b" : 1or the eld 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, andrepairDatabasewill error if an index exists with
an invalid or empty key name.

Previous versions of MongoDB allow the index.
SolutionRundb.upgradeCheckAllDBs() to nd current keys that violate this limit and correct as appropriate.
Preferably, run the test before upgrading; i.e. connect the 2.6mongoshell to your MongoDB 2.4 database and
run the method.
ensureIndexand Existing Indexes
Descriptiondb.collection.ensureIndex() now errors:

db.collection.ensureIndex() will error.
742 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
db.mycollection.ensureIndex( { x:
db.mycollection.ensureIndex( { x::

example, the seconddb.collection.ensureIndex() will error.
db.mycollection.ensureIndex( { a::
db.mycollection.ensureIndex( { z::
Previous versions did not create the index but did not error.
Write Method Acknowledgements
DescriptionThemongoshell write methodsdb.collection.insert() ,db.collection.update() ,
db.collection.save() anddb.collection.remove() now integrate thewrite concern(page 72)
directly into the method rather than with a separategetLastErrorcommand to providesafe writes(page 73)
whether run interactively in themongoshell or non-interactively in a script. In previous versions, these methods
exhibited a re-and-forget behavior.
180
mongoshell that used these methods will now observe safe writes which takelonger
than the previous re-and-forget behavior.
WriteResultobject that contains the results of the operation, in-
cluding any write errors and write concern errors, and obviates the need to callgetLastErrorcom-
mand to get the status of the results. Seedb.collection.insert() ,db.collection.update() ,
db.collection.save() anddb.collection.remove() for details.
mongosno longer supports re-and-forget behavior. This limits throughput when
writing data to sharded clusters.
SolutionScripts that used thesemongoshell methods for bulk write operations with re-and-forget behavior should
use theBulk()methods.
In sharded environments, applications using any driver ormongoshell should useBulk()methods for optimal
performance when inserting or modifying groups of documents.
For example, instead of:
for(vari; i; i++) {
db.test.insert( { x
}
In MongoDB 2.6, replace withBulk()operation:
varbulk
for(vari; i; i++) {
bulk.insert( { x
}
bulk.execute( { w:
Bulk method returns aBulkWriteResultobject that contains the result of the operation.
See also:
New Write Operation Protocol (page 737), Bulk(), Bulk.execute(),
db.collection.initializeUnorderedBulkOp() ,db.collection.initializeOrderedBulkOp()
180
In previous versions, when using themongoshell interactively, themongoshell automatically called thegetLastErrorcommand after a
write method to provide safe writes. Scripts, however, would observe re-and-forget behavior in previous versions unless the scripts included
anexplicitcall to thegetLastErrorcommand after a write method.
12.1. Current Stable Release 743

MongoDB Documentation, Release 2.6.4
db.collection.aggregate() Change
DescriptionThedb.collection.aggregate() method in themongoshell 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:
varmyCursor
{
$group:
_id:,
total::
}
}
] );
myCursor.forEach( function(x) { printjson (x); } );
Previous versions returned a single document with a eldresultsthat contained an array of the result set,
subject to theBSON Document sizelimit. Accessing the result set in the previous versions of MongoDB required
accessing theresultseld and iterating the array. For example:
varreturnedDoc
{
$group:
_id:,
total::
}
}
] );
varmyArray // access the result field
myArray.forEach( function(x) { printjson (x); } );
SolutionUpdate scripts that currently expectdb.collection.aggregate() to return a document with a
resultsarray to handle cursors instead.
See also:
Aggregation Enhancements(page 736),db.collection.aggregate() ,
Write Concern Validation
DescriptionSpecifying a write concern that includesj: trueto amongodormongosinstance running with
--nojournaloption now errors. Previous versions would ignore thej: true.
SolutionEither remove thej: truespecication from the write concern when issued against amongodor
mongosinstance with--nojournalor runmongodormongoswith journaling.
Security Changes
New Authorization Model
DescriptionMongoDB 2.6authorization model(page 285) changes how MongoDB stores and manages user privi-
lege information:

744 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
SolutionEnsure 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. SeeUpgrade MongoDB to 2.6
(page 751).
Important:Before upgrading the authorization model, you should rst upgrade MongoDB binaries to 2.6. For
sharded clusters, ensure thatallcluster components are 2.6. If there are users in any database, be sure you have
at least one user in theadmindatabasebeforeupgrading the MongoDB binaries.
See also:
Security Improvements(page 738)
SSL Certicate Hostname Validation
DescriptionThe SSL certicate validation now checks the Common Name (CN) and the Subject Alternative Name
(SAN) elds to ensure that either theCNor one of theSANentries matches the hostname of the server. As a
result, if you currently use SSL andneithertheCNnor any of theSANentries of your current SSL certicates
match the hostnames, upgrading to version 2.6 will cause the SSL connections to fail.
SolutionTo allow for the continued use of these certicates, MongoDB provides the
allowInvalidCertificates setting. The setting is available for:
mongodandmongosto bypass the validation of SSL certicates on other servers in the cluster.
mongoshell,MongoDB tools that support SSL(page 310), and the C++ driver to bypass the validation of
server certicates.
When using theallowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid
certicates.
Warning:TheallowInvalidCertificates setting bypasses the other certicate validation, such as
checks for expiration and valid signatures.
2dsphereIndex Version 2
DescriptionMongoDB 2.6 introduces a version 2 of the2dsphere index(page 447). If a document lacks a2dsphere
index eld (or the eld isnullor an empty array), MongoDB does not add an entry for the document to the
2dsphereindex. For inserts, MongoDB inserts the document but does not add to the2dsphereindex.
Previous version would not insert documents where the2dsphereindex eld is anullor an empty array.
For documents that lack the2dsphereindex eld, previous versions would insert and index the document.
SolutionTo revert to old behavior, create the2dsphereindex with{ "2dsphereIndexVersion" : 1 }
to create a version 1 index. However, version 1 index cannot use the new GeoJSON geometries.
See also:
2dsphere Version 2(page 447)
Log Messages
Timestamp Format Change
DescriptionEach message now starts with the timestamp format given inTime Format Changes(page 751). Previous
versions used thectimeformat.
12.1. Current Stable Release 745

MongoDB Documentation, Release 2.6.4
SolutionMongoDB adds a new option--timeStampFormat which supports timestamp format inctime,
iso8601-utc, andiso8601-local(new default).
Package Conguration Changes
DefaultbindIpfor RPM/DEB Packages
DescriptionIn the ofcial MongoDB packages in RPM (Red Hat, CentOS, Fedora Linux, and derivatives) and DEB
(Debian, Ubuntu, and derivatives), the defaultbindIpvalue attaches MongoDB components to the localhost
interfaceonly. These packages set this default in the default conguration le (i.e./etc/mongodb.conf.)
SolutionIf you use one of these packages and havenotmodied the default/etc/mongodb.confle, you will
need to setbindIpbefore or during the upgrade.
There is no defaultbindIpsetting in any other ofcial MongoDB packages.
SNMP Changes
Description

globalopcountstoglobalOpcounts.
Solution

globalopcountstoglobalOpcounts.
Remove Method Signature Change
Descriptiondb.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.
SolutionFor existingdb.collection.remove() invocations without a query document, modify the invocations
to include an empty documentdb.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::::
Updates Enforce Field Name Restrictions
Description
update operators (e.g $set) to target elds with empty eld names (i.e.
"").
746 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
.) or a eld name that starts with a dollar
sign ($).
Solution
"", replace the whole document. See
db.collection.update() anddb.collection.save() for details on replacing an existing
document.
Unsetorrenameexisting elds with names that contain a dot (.) or that start with a dollar sign ($).
Rundb.upgradeCheckAllDBs() to nd elds whose names contain a dot or starts with a dollar sign.
SeeNew Write Operation Protocol(page 737) for the changes to the write operation protocol, andInsert and Update
Improvements(page 737) 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
DescriptionQueries cannot specify conditions on elds with names that start with a dollar sign ($).
SolutionUnsetorrenameexisting elds whose names start with a dollar sign ($). Run
db.upgradeCheckAllDBs() to nd elds whose names start with a dollar sign.
Sparse Index and Incomplete Results
DescriptionIf asparse index(page 457) results in an incomplete result set for queries and sort operations, MongoDB
will not use that index unless ahint()explicitly species the index.
For example, the query{ x: { $exists: false } } will no longer use a sparse index on thexeld,
unless explicitly hinted.
SolutionTo override the behavior to use the sparse index and return incomplete results, explicitly specify the index
with ahint().
SeeSparse Index On A Collection Cannot Return Complete Results(page 459) for an example that details the new
behavior.
sort()Specication Values
DescriptionThesort()methodonlyaccepts the following values for the sort keys:
1to specify ascending order for a eld,
-1to specify descending order for a eld, or
$metaexpression to specify sort by the text search score.
Any other value will result in an error.
Previous versions also accepted eithertrueorfalsefor ascending.
SolutionUpdate sort key values that usetrueorfalseto1.
skip()and_idQueries
DescriptionEquality match on the_ideld obeysskip().
Previous versions ignoredskip()when performing an equality match on the_ideld.
12.1. Current Stable Release 747

MongoDB Documentation, Release 2.6.4
explain()Retains Query Plan Cache
Descriptionexplain()no longer clears thequery plans(page 61) cached for thatquery shape.
In previous versions,explain()would have the side effect of clearing the query plan cache for that query
shape.
See also:
http://docs.mongodb.org/manualreference/method/js-plan-cache
Geospatial Changes
$maxDistanceChanges
Description
$nearqueries on GeoJSON data, if the queries specify a$maxDistance,$maxDistancemust
be inside of the$neardocument.
In previous version,$maxDistancecould be either inside or outside the$neardocument.
$maxDistancemust be a positive value.
Solution
$nearqueries on GeoJSON data that currently have the$maxDistanceoutside
the$neardocument
$maxDistanceis a negative value.
Deprecated$uniqueDocs
DescriptionMongoDB 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
DescriptionMongoDB 2.6 enforces a stronger validation of geospatial queries, such as validating the options or
GeoJSON specications, and errors if the geospatial query is invalid. Previous versions allowed/ignored invalid
options.
Query Operator Changes
$notQuery Behavior Changes
Description
$notexpressions on an indexed eld now match:
Documents that are missing the indexed eld. Previous versions would not return these documents
using the index.
Documents whose indexed eld value is a different type than that of the specied value. Previous
versions would not return these documents using the index.
For example, if a collectionorderscontains the following documents:
748 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
{ _id:, status:, cust_id:, price:
{ _id:, status:, cust_id:, price:
{ _id:, status:, cust_id:
If the collection has an index on thepriceeld:
db.orders.ensureIndex( { price:
The following query uses the index to search for documents wherepriceis not greater than or equal to
50:
db.orders.find( { price:::
In 2.6, the query returns the following documents:
{,,
{,,,
{,,,
In previous versions, indexed plans would only return matching documents where the type of the eld
matches the type of the query predicate:
{,,,
If using a collection scan, previous versions would return the same results as those in 2.6.
$notexpressions.
nullComparison Queries
Description
$ltand$gtcomparisons tonullno longer match documents that are missing the eld.
nullequality conditions on array elements (e.g."a.b": null) no longer match document missing
the nested elda.b(e.g.a: [ 2, 3 ]).
nullequality queries (i.e.field: null) now match elds with valuesundefined.
$allOperator Behavior Change
Description
$alloperator is now equivalent to an$andoperation of the specied 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,$allcan now match documents where the eld
contains the nested array as an element (e.g.field: [ [ "A" ], ... ] ),orthe eld equals the
nested array (e.g.field: [ "A", "B" ] ). Earlier version could only match documents where the
eld contains the nested array.
$alloperator returns no match if the array eld contains nested arrays (e.g.field: [ "a",
["b"] ]) and$allon the nested eld is the element of the nested array (e.g."field.1": {
$all: [ "b" ] } ). Previous versions would return a match.
$modOperator Enforces Strict Syntax
DescriptionThe$modoperator now only accepts an array with exactly two elements, and errors when passed an
array with fewer or more elements. Seemod-not-enough-elementsandmod-too-many-elementsfor details.
12.1. Current Stable Release 749

MongoDB Documentation, Release 2.6.4
In previous versions, if passed an array with one element, the$modoperator uses0as the second element,
and if passed an array with more than two elements, the$modignores all but the rst two elements. Previous
versions do return an error when passed an empty array.
SolutionEnsure that the array passed to$modcontains exactly two elements:
0as the second element.

$whereMust Be Top-Level
Description$whereexpressions can now only be at top level and cannot be nested within another expression, such
as$elemMatch.
SolutionUpdate existing queries that nest$where.
$existsandnotablescan If the MongoDB server has disabled collection scans, i.e.notablescan, then
$existsqueries that have noindexed solutionwill error.
MinKeyandMaxKeyQueries
DescriptionEquality match for eitherMinKeyorMaxKeyno longer match documents missing the eld.
Nested Array Queries with $elemMatch
DescriptionThe$elemMatchquery operator no longer traverses recursively into nested arrays.
For example, if a collectiontestcontains the following document:
{:,,,
In 2.6, the following$elemMatchquery doesnotmatch the document:
db.test.find( { a:::, $lt:
SolutionUpdate existing queries that rely upon the old behavior.
Text Search CompatibilityMongoDB does not support the use of the$textquery operator in mixed sharded
cluster deployments that contain both version 2.4 and version 2.6 shards. SeeUpgrade MongoDB to 2.6(page 751)
for upgrade instructions.
Replica Set/Sharded Cluster Validation
Shard Name Checks on Metadata Refresh
DescriptionFor 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 chunksfromversion 2.4 shardstoversion 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.
SolutionUpgrade all components of the cluster to 2.6. SeeUpgrade MongoDB to 2.6(page 751).
750 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Replica Set Vote Conguration Validation
DescriptionMongoDB now deprecates giving anyreplica setmember more than a single vote. During conguration,
local.system.replset.members[n].votes (page 597) 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.
SolutionUpdatelocal.system.replset.members[n].votes (page 597) with values other than 1 or 0 to
1 or 0 as appropriate.
Time Format ChangesMongoDB now usesiso8601-localwhen formatting time data in many out-
puts. This format follows the templateYYYY-MM-DDTHH:mm:ss.mmm<+/-Offset> . For example,
2014-03-04T20:13:38.944-0500 .
This change impacts all clients usingExtended JSONinStrict mode, such asmongoexportand the
HTTP Interfaces
181
.
Other Resources

182
.
Release Notes for MongoDB 2.6(page 725).
Upgrade MongoDB to 2.6(page 751) for the upgrade process.
Some changes in 2.6 can affectcompatibility(page 741) and may require user actions. The 2.6mongoshell provides
adb.upgradeCheckAllDBs() method to perform a check for upgrade preparedness for some of these changes.
SeeCompatibility Changes in MongoDB 2.6(page 741) for a detailed list of compatibility changes.
See also:
All Backwards incompatible changes (JIRA)
183
.
Upgrade Process
Upgrade MongoDB to 2.6In the general case, the upgrade from MongoDB 2.4 to 2.6 is a binary-compatible drop-
in upgrade: shut down themongodinstances and replace them withmongodinstances running 2.6.However, before
you attempt any upgrade, familiarize yourself with the content of this document, particularly theUpgrade Recommen-
dations and Checklists(page 751), the procedure forupgrading sharded clusters(page 753), and the considerations
forreverting to 2.4 after running 2.6(page 756).
Upgrade Recommendations and ChecklistsWhen upgrading, consider the following:
Upgrade RequirementsTo 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, youmustupgrade to 2.4 before upgrading to 2.6. SeeUpgrade MongoDB
to 2.4(page 776) for the procedure to upgrade from 2.2 to 2.4.
If you use MMS Backup, ensure that you're runningat leastversionv20131216.1of the Backup agent before
upgrading.
181
http://docs.mongodb.org/ecosystem/tools/http-interfaces
182
https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20xVersion%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
183
https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20xVersion%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
12.1. Current Stable Release 751

MongoDB Documentation, Release 2.6.4
PreparednessBefore 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.6mongoshell to your MongoDB 2.4mongosormongodand run the
db.upgradeCheckAllDBs() to check your data set for compatibility. This is a preliminary automated check.
Assess and resolve all issues identied bydb.upgradeCheckAllDBs() .
Some changes in MongoDB 2.6 require manual checks and intervention. SeeCompatibility Changes in MongoDB 2.6
(page 741) for an explanation of these changes. Resolve all incompatibilities in your deployment before continuing.
AuthenticationMongoDB 2.6 includes signicant 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, youcannotmodify existing user
data until you complete theauthorization user schema upgrade(page 755).
Before beginning the upgrade process for a deployment that uses authentication and authorization:
admindatabase.
<database>.system.users collection or uses a
db.addUser()-like method, then youmustupgrade those drivers (i.e. client libraries)beforemongodor
mongosinstances.
allMongoDB processes before upgrading the authorization
model.
SeeUpgrade User Authorization Data to 2.6 Format(page 755) for a complete discussion of the upgrade procedure
for the authorization model including additional requirements and procedures.
Downgrade LimitationsOnce upgraded to MongoDB 2.6, youcannotdowngrade toanyversion earlier than Mon-
goDB 2.4. If you createdtextor2dsphereindexes while running 2.6, you can only downgrade to MongoDB
2.4.10 or later.
Package UpgradesIf you installed MongoDB from the MongoDBaptoryumrepositories, 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 themongodb-orgpackage, and installed a subset of MongoDB components replace
mongodb-orgin the commands above with the appropriate package names.
See installation instructions forUbuntu(page 9),RHEL(page 6),Debian(page 12), orother Linux Systems(page 14)
for a list of the available packages and complete MongoDB installation instructions.
Upgrade MongoDB Processes
752 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Upgrade StandalonemongodInstance to MongoDB 2.6The following steps outline the procedure to upgrade a
standalonemongodfrom version 2.4 to 2.6. To upgrade from version 2.2 to 2.6,upgrade to version 2.4(page 776)
rst, and then follow the procedure to upgrade from 2.4 to 2.6.
1.
184
. SeeInstall
MongoDB(page 5) for more information.
2. mongodinstance. Replace the existing binary with the 2.6mongodbinary and restart
mongod.
Upgrade a Replica Set to 2.6The 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
(page 776)rst, 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 mem-
bers individually while the other members are available:
Step 1: Upgrade secondary members of the replica set.Upgrade thesecondarymembers of the set one at a time
by shutting down themongodand replacing the 2.4 binary with the 2.6 binary. After upgrading amongodinstance,
wait for the member to recover toSECONDARYstate before upgrading the next instance. To check the member's state,
issuers.status()in themongoshell.
Step 2: Step down the replica set primary.Users.stepDown()in themongoshell to step down theprimary
and force the set tofailover(page 523).rs.stepDown()expedites the failover procedure and is preferable to
shutting down the primary directly.
Step 3: Upgrade the primary.Whenrs.status()shows that the primary has stepped down and another mem-
ber has assumedPRIMARYstate, shut down the previous primary and replace themongodbinary 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.6Only upgrade sharded clusters to 2.6 ifallmembers 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.
ConsiderationsThe 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, donot
do any of the following:
sh.enableSharding()
sh.shardCollection()
sh.addShard()
db.createCollection()
db.collection.drop()
db.dropDatabase()

184
http://www.mongodb.org/downloads
12.1. Current Stable Release 753

MongoDB Documentation, Release 2.6.4
Sharding Reference(page 678) for a com-
plete list of sharding commands. Note, however, that not all commands on theSharding Reference(page 678)
page modies the cluster meta-data.
Upgrade Sharded ClustersOptional but Recommended.As a precaution, take a backup of theconfigdatabase
beforeupgrading the sharded cluster.
Step 1: Disable the Balancer.Turn off thebalancer(page 629) in the sharded cluster, as described inDisable the
Balancer(page 661).
Step 2: Upgrade the cluster's meta data.Start a single 2.6mongosinstance with theconfigDBpointing to the
cluster's cong servers and with the--upgradeoption.
To run amongoswith the--upgradeoption, you can upgrade an existingmongosinstance to 2.6, or if you need
to avoid reconguring a productionmongosinstance, you can use a new 2.6mongosthat can reach all the cong
servers.
To upgrade the meta data, run:
mongos --configdb <configDB string> --upgrade
You can include the--logpathoption to output the log messages to a le instead of the standard output. Also
include any other options required to startmongosinstances in your cluster, such as--sslOnNormalPorts or
--sslPEMKeyFile.
Themongoswill exit upon completion of the--upgradeprocess.
The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If the data les 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 3: Ensuremongos --upgradeprocess completes successfully.Themongoswill 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 themongosinstance. Ifmongosfails to start, check the log for more information.
If themongosinstance loses its connection to the cong servers during the upgrade or if the upgrade is otherwise
unsuccessful, you may always safely retry the upgrade.
Step 4: Upgrade the remainingmongosinstances to v2.6.Upgrade and restartwithoutthe--upgradeoption
the othermongosinstances in the sharded cluster. After upgrading all themongos, seeComplete Sharded Cluster
Upgrade(page 754) for information on upgrading the other cluster components.
Complete Sharded Cluster UpgradeAfter you have successfully upgradedallmongosinstances, you can upgrade
the other instances in your MongoDB deployment.
Warning:Do not upgrademongodinstances until after you have upgradedallmongosinstances.
While the balancer is still disabled, upgrade the components of your sharded cluster in the following order:
754 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
mongodcong server instances, leaving therstsystem in themongos --configdb argu-
ment to upgradelast.
mongodsecondaries before runningreplSetStepDown
and upgrading the primary of each shard.
When this process is complete,re-enable the balancer(page 661).
Upgrade ProcedureOnce upgraded to MongoDB 2.6, youcannotdowngrade toanyversion earlier than MongoDB
2.4. If you havetextor2dsphereindexes, you can only downgrade to MongoDB 2.4.10 or later.
Exceptas described on this page, moving between 2.4 and 2.6 is a drop-in replacement:
Step 1: Stop the existingmongodinstance.For example, on Linux, run 2.4mongodwith the--shutdown
option as follows:
mongod --dbpath /var/mongod/data --shutdown
Replace/var/mongod/datawith your MongoDBdbPath. See also theStop mongod Processes(page 208) for
alternate methods of stopping amongodinstance.
Step 2: Start the newmongodinstance.Ensure you start the 2.6mongodwith the samedbPath:
mongod --dbpath /var/mongod/data
Replace/var/mongod/datawith your MongoDBdbPath.
Upgrade User Authorization Data to 2.6 FormatMongoDB 2.6 includes signicant 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 RequirementsBefore upgrading the authorization model, you should rst upgrade
MongoDB binaries to 2.6. For sharded clusters, ensure thatallcluster components are 2.6. If there are users in any
database, be sure you have at least one user in theadmindatabasebeforeupgrading the MongoDB binaries.
TimingBecause downgrades are more difcult 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 twowithoutupgrading 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,butit will be
impossible to create or modify users or to use user-dened 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 SetsFor a replica set, it is only necessary to run the upgrade process on theprimaryas the changes will
automatically replicate to the secondaries.
12.1. Current Stable Release 755

MongoDB Documentation, Release 2.6.4
Sharded ClustersFor a sharded cluster, connect to amongosand 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 parameterupgradeShards: false . If
you choose to override, you must run the upgrade procedure on themongosrst, and then run the procedure on the
primarymembers of each shard.
For a sharded cluster, donotrun the upgrade process directly against thecong servers(page 616). Instead, perform
the upgrade process using onemongosinstance to interact with the cong database.
RequirementsTo upgrade the authorization model, you must have a user in theadmindatabase with the role
userAdminAnyDatabase (page 368).
Procedure
Step 1: Connect to MongoDB instance.Connect and authenticate to themongodinstance for a single deployment
or amongosfor a sharded cluster as anadmindatabase user with the roleuserAdminAnyDatabase (page 368).
Step 2: Upgrade authorization schema.Use theauthSchemaUpgrade command in theadmindatabase to
update the user data using themongoshell.
RunauthSchemaUpgradecommand.
db.getSiblingDB("admin").runCommand({authSchemaUpgrade:
In case of error, you may safely rerun theauthSchemaUpgradecommand.
Sharded clusterauthSchemaUpgradeconsideration.For a sharded cluster,authSchemaUpgradewill up-
grade the authorization data of the shards as well and the upgrade is complete. You can, however, override this behavior
by includingupgradeShards: false in the command, as in the following example:
db.getSiblingDB("admin").runCommand({authSchemaUpgrade:,
upgradeShards: false});
If you override the behavior, after runningauthSchemaUpgradeon amongosinstance, you will need to connect
to the primary for each shard and repeat the upgrade process after upgrading on themongos.
ResultAll users in a 2.6 system are stored in theadmin.system.users (page 271) collection. To manipulate
these users, use theuser 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.6Before you attempt any downgrade, familiarize yourself with the content of this
document, particularly theDowngrade Recommendations and Checklist(page 756) and the procedure fordowngrading
sharded clusters(page 761).
Downgrade Recommendations and ChecklistWhen downgrading, consider the following:
756 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Downgrade PathOnce upgraded to MongoDB 2.6, youcannotdowngrade toanyversion earlier than MongoDB
2.4. If you createdtextor2dsphereindexes while running 2.6, you can only downgrade to MongoDB 2.4.10 or
later.
Preparedness
Remove or downgrade version 2 text indexes(page 759) before downgrading MongoDB 2.6 to 2.4.
Remove or downgrade version 2 2dsphere indexes(page 760) before downgrading MongoDB 2.6 to 2.4.
Downgrade 2.6 User Authorization Model(page 757). 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.
ProceduresFollow the downgrade procedures:
Downgrade a 2.6 Sharded Cluster(page 761).
Downgrade a 2.6 Replica Set(page 760).
Downgrade 2.6 Standalone mongod Instance(page 760).
Downgrade 2.6 User Authorization ModelIf you have upgraded to the 2.6 user authorization model, youmust
rstdowngrade the user authorization model to 2.4beforebefore downgrading MongoDB 2.6 to 2.4.
Considerations
primaryas the changes will automati-
cally replicate to the secondaries.

may downgrade the authorization data of the cluster or shards rst.
musthave theadmin.system.backup_users andadmin.system.new_users collections cre-
ated 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 PrerequisitesTo 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 appropriateprivileges, create an authorization model downgrade user:
Step 1: Connect as user with privileges to manage users and roles.Connect and authenticate as a user with
userAdminAnyDatabase (page 368).
Step 2: Create a role with required privileges.Using thedb.createRolemethod, create arole(page 286)
with the required privileges.
12.1. Current Stable Release 757

MongoDB Documentation, Release 2.6.4
use admin
db.createRole(
{
role:,
privileges:
{ resource::, collection::,,
{ resource::, collection::
{ resource::, collection::,,] },
{ resource::, collection::,
],
roles:
}
)
Step 3: Create a user with the new role.Create a user and assign the user thedowngradeRole.
use admin
db.createUser(
{
user:,
pwd:,
roles::, db:
}
)
Note: Instead of creating a new user, you can also grant the role to an existing user. See
db.grantRolesToUser() method.
Step 4: Authenticate as the new user.Authenticate as the newly created user.
use admin
db.auth(,
The method returns1upon successful authentication.
ProcedureThe following downgrade procedure requires<database>.system.users collections used in ver-
sion 2.4. to be intact for non-admindatabases.
Step 1: Connect and authenticate to MongoDB instance.Connect and authenticate to themongodinstance for a
single deployment or amongosfor a sharded cluster with the appropriate privileges. SeeAccess Control Prerequisites
(page 757) for details.
Step 2: Create backup of 2.6 admin.system.users collection.Copy all documents in the
admin.system.users (page 271) collection to theadmin.system.new_users collection:
db.getSiblingDB("admin").system.users.find().forEach( function(userDoc) {
status"admin").system.new_users.save( userDoc );
if(status.hasWriteError()) {
print(status.writeError);
}
}
);
758 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Step 3: Update the version document for theauthSchema.
db.getSiblingDB("admin").system.version.update(
{ _id:
{ $set::
);
The method returns aWriteResultobject with the status of the operation. Upon successful update, the
WriteResultobject should have"nModified"equal to1.
Step 4: Remove existing documents from theadmin.system.users collection.
db.getSiblingDB("admin").system.users.remove( {} )
The method returns aWriteResultobject with the number of documents removed in the"nRemoved"eld.
Step 5: Copy documents from theadmin.system.backup_users collection.Copy all documents from the
admin.system.backup_users , created during the 2.6 upgrade, toadmin.system.users.
db.getSiblingDB("admin").system.backup_users.find().forEach(
function(userDoc) {
status"admin").system.users.insert( userDoc );
if(status.hasWriteError()) {
print(status.writeError);
}
}
);
Step 6: Update the version document for theauthSchema.
db.getSiblingDB("admin").system.version.update(
{ _id:
{ $set::
)
For a sharded cluster, repeat the downgrade process by connecting to theprimaryreplica set member for each shard.
Note:The cluster'smongosinstances will fail to detect the authorization model downgrade until the user cache
is refreshed. You can runinvalidateUserCache on eachmongosinstance to refresh immediately, or you can
wait until the cache is refreshed automatically at the end of theuser cache invalidation interval . To
runinvalidateUserCache, you must have privilege withinvalidateUserCache (page 376) action, which
is granted byuserAdminAnyDatabase (page 368) andhostManager(page 366) roles.
ResultThe 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 CheckIf you haveversion 2text indexes (i.e. the default version for text indexes in MongoDB
2.6), drop theversion 2text indexes before downgrading MongoDB. After the downgrade, enable text search and
recreate the dropped text indexes.
To determine the version of yourtextindexes, rundb.collection.getIndexes() to view index specica-
tions. For text indexes, the method returns the version information in the eldtextIndexVersion. For example,
the following shows that thetextindex on thequotescollection is version 2.
12.1. Current Stable Release 759

MongoDB Documentation, Release 2.6.4
{
"v",
"key"
"_fts",
"_ftsx"
},
"name",
"ns",
"weights"
"quote",
"translation.quote"
},
"default_language",
"language_override",
"textIndexVersion"
}
2dsphereIndex Version CheckIf you haveversion 22dsphereindexes (i.e. the default version for2dsphere
indexes in MongoDB 2.6), drop theversion 22dsphereindexes before downgrading MongoDB. After the down-
grade, recreate the2dsphereindexes.
To determine the version of your2dsphereindexes, rundb.collection.getIndexes() to view
index specications. For2dsphereindexes, the method returns the version information in the eld
2dsphereIndexVersion . For example, the following shows that the2dsphereindex on thelocations
collection is version 2.
{
"v",
"key"
"geo"
},
"name",
"ns",
"sparse" true,
"2dsphereIndexVersion"
}
Downgrade MongoDB Processes
Downgrade 2.6 StandalonemongodInstanceThe following steps outline the procedure to downgrade a stan-
dalonemongodfrom version 2.6 to 2.4.
1.
185
. SeeInstall
MongoDB(page 5) for more information.
2. mongodinstance. Replace the existing binary with the 2.4mongodbinary and restart
mongod.
Downgrade a 2.6 Replica SetThe 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:
185
http://www.mongodb.org/downloads
760 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Step 1: Downgrade each secondary member, one at a time.For eachsecondaryin a replica set:
Replace and restart secondarymongodinstances.First, shut down themongod, then replace these binaries with
the 2.4 binary and restartmongod. SeeStop mongod Processes(page 208) for instructions on safely terminating
mongodprocesses.
Allow secondary to recover.Wait for the member to recover toSECONDARYstate before upgrading the next sec-
ondary.
To check the member's state, use thers.status()method in themongoshell.
Step 2: Step down the primary.Users.stepDown()in themongoshell to step down theprimaryand force
the normalfailover(page 523) procedure.
rs.stepDown()
rs.stepDown()expedites the failover procedure and is preferable to shutting down the primary directly.
Step 3: Replace and restart former primarymongod.Whenrs.status()shows that the primary has stepped
down and another member has assumedPRIMARYstate, shut down the previous primary and replace themongod
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 pro-
cess 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
RequirementsWhile the downgrade is in progress, you cannot make changes to the collection meta-data. For
example, during the downgrade, donotdo any of the following:
sh.enableSharding()
sh.shardCollection()
sh.addShard()
db.createCollection()
db.collection.drop()
db.dropDatabase()

Sharding Reference(page 678) for a com-
plete list of sharding commands. Note, however, that not all commands on theSharding Reference(page 678)
page modies the cluster meta-data.
ProcedureThe downgrade procedure for a sharded cluster reverses the order of the upgrade procedure.
1. balancer(page 629) in the sharded cluster, as described inDisable the Balancer(page 661).
2.
(a) mongodsecondariesbeforedowngrading the primary.
12.1. Current Stable Release 761

MongoDB Documentation, Release 2.6.4
(b) replSetStepDownand downgrade.
3. mongodcong server instances, leaving therstsystem in themongos --configdb
argument to downgradelast.
4. mongos, one at a time. The downgrade process is a binary drop-in replacement.
5. Enable the Balancer(page 661).
Downgrade ProcedureOnce upgraded to MongoDB 2.6, youcannotdowngrade toanyversion earlier than Mon-
goDB 2.4. If you havetextor2dsphereindexes, you can only downgrade to MongoDB 2.4.10 or later.
Exceptas described on this page, moving between 2.4 and 2.6 is a drop-in replacement:
Step 1: Stop the existingmongodinstance.For example, on Linux, run 2.6mongodwith the--shutdown
option as follows:
mongod --dbpath /var/mongod/data --shutdown
Replace/var/mongod/datawith your MongoDBdbPath. See also theStop mongod Processes(page 208) for
alternate methods of stopping amongodinstance.
Step 2: Start the newmongodinstance.Ensure you start the 2.4mongodwith the samedbPath:
mongod --dbpath /var/mongod/data
Replace/var/mongod/datawith your MongoDBdbPath.
SeeUpgrade MongoDB to 2.6(page 751) for full upgrade instructions.
Download
To download MongoDB 2.6, go to the
186
.
Other Resources

187
.

188
.
12.2
12.2.1
March 19, 2013
MongoDB 2.4 includes enhanced geospatial support, switch to V8 JavaScript engine, security enhancements, and text
search (beta) and hashed index.
186
http://www.mongodb.org/downloads
187
https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+xVersion+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
188
https://github.com/mongodb/mongo/blob/v2.6/distsrc/THIRD-PARTY-NOTICES
762 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Minor Releases
2.4 Changelog
2.4.11 - Changes
SERVER-14268
189
)
_idwith$prefixeld causes replication failure due to unvalidated insert (SERVER-12209
190
)
SplitChunkCommand::run (SERVER-14342
191
)
_idcan corrupt namespace (SERVER-14833
192
)
SERVER-14738
193
)
SERVER-13724
194
)
SERVER-14336
195
)
SERVER-14254
196
)
2.4.10 - Changes
SERVER-12990
197
)

(SERVER-12956
198
)

(SERVER-12914
199
)

concurrently (SERVER-12662
200
)

(SERVER-12481
201
)
SERVER-12175
202
)

secondaries (SERVER-10231
203
)
SERVER-12908
204
)

collections (SERVER-12548
205
)
189
https://jira.mongodb.org/browse/SERVER-14268
190
https://jira.mongodb.org/browse/SERVER-12209
191
https://jira.mongodb.org/browse/SERVER-14342
192
https://jira.mongodb.org/browse/SERVER-14833
193
https://jira.mongodb.org/browse/SERVER-14738
194
https://jira.mongodb.org/browse/SERVER-13724
195
https://jira.mongodb.org/browse/SERVER-14336
196
https://jira.mongodb.org/browse/SERVER-14254
197
https://jira.mongodb.org/browse/SERVER-12990
198
https://jira.mongodb.org/browse/SERVER-12956
199
https://jira.mongodb.org/browse/SERVER-12914
200
https://jira.mongodb.org/browse/SERVER-12662
201
https://jira.mongodb.org/browse/SERVER-12481
202
https://jira.mongodb.org/browse/SERVER-12175
203
https://jira.mongodb.org/browse/SERVER-10231
204
https://jira.mongodb.org/browse/SERVER-12908
205
https://jira.mongodb.org/browse/SERVER-12548
12.2. Previous Stable Releases 763

MongoDB Documentation, Release 2.6.4

(SERVER-12515
206
)

data (SERVER-9259
207
)
SERVER-
12264
208
)
SERVER-
12170
209
)

result (SERVER-10793
210
)

cycles (SERVER-8375
211
)
SERVER-
12034
212
)

(SERVER-9248
213
)

R2 (SERVER-8480
214
)

(SERVER-13331
215
)
SERVER-12487
216
)
SERVER-
11871
217
)
SERVER-11560
218
)
Previous Releases

219
.

220
.

221
.

222
.
206
https://jira.mongodb.org/browse/SERVER-12515
207
https://jira.mongodb.org/browse/SERVER-9259
208
https://jira.mongodb.org/browse/SERVER-12264
209
https://jira.mongodb.org/browse/SERVER-12170
210
https://jira.mongodb.org/browse/SERVER-10793
211
https://jira.mongodb.org/browse/SERVER-8375
212
https://jira.mongodb.org/browse/SERVER-12034
213
https://jira.mongodb.org/browse/SERVER-9248
214
https://jira.mongodb.org/browse/SERVER-8480
215
https://jira.mongodb.org/browse/SERVER-13331
216
https://jira.mongodb.org/browse/SERVER-12487
217
https://jira.mongodb.org/browse/SERVER-11871
218
https://jira.mongodb.org/browse/SERVER-11560
219
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.9%22%20AND%20project%20%3D%20SERVER
220
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.8%22%20AND%20project%20%3D%20SERVER
221
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.7%22%20AND%20project%20%3D%20SERVER
222
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.6%22%20AND%20project%20%3D%20SERVER
764 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4

223
.

224
.

225
.

226

227
.
2.4.11 August 18, 2014

228
.
_idwith a$prefixeld caused replication failure due to unvalidated insert
12209
229
.

14738
230
.
_idcould corrupt namespace
231
.
2.4.11 Changelog(page 763).

232
.
2.4.10 April 4, 2014

233
.

234
.

235
,
236
.

237
,
238
.
2.4.10 Changelog(page 763).

239
.
2.4.9 January 10, 2014
mongosincorrectly reports a successful write
240
.
223
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.5%22%20AND%20project%20%3D%20SERVER
224
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.4%22%20AND%20project%20%3D%20SERVER
225
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.3%22%20AND%20project%20%3D%20SERVER
226
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.2%22%20AND%20project%20%3D%20SERVER
227
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.1%22%20AND%20project%20%3D%20SERVER
228
https://jira.mongodb.org/browse/SERVER-14268
229
https://jira.mongodb.org/browse/SERVER-12209
230
https://jira.mongodb.org/browse/SERVER-14738
231
https://jira.mongodb.org/browse/SERVER-14833
232
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.11%22%20AND%20project%20%3D%20SERVER
233
https://jira.mongodb.org/browse/SERVER-8480
234
https://jira.mongodb.org/browse/SERVER-10793
235
https://jira.mongodb.org/browse/SERVER-12914
236
https://jira.mongodb.org/browse/SERVER-12175
237
https://jira.mongodb.org/browse/SERVER-12481
238
https://jira.mongodb.org/browse/SERVER-12956
239
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.10%22%20AND%20project%20%3D%20SERVER
240
https://jira.mongodb.org/browse/SERVER-12146
12.2. Previous Stable Releases 765

MongoDB Documentation, Release 2.6.4
slaveOKversioning logic
241
.

242
.

243
.
2.4.8 November 1, 2013

244
.
dbhashcache issue for cong servers
245
.

246
.
2.4.7 October 21, 2013

247
.

248
.

249
.

250
.

251
.
2.4.6 August 20, 2013

SERVER-10478
252
.

253
.

254
.

255
,
256
, and
257
.

258
.
241
https://jira.mongodb.org/browse/SERVER-11971
242
https://jira.mongodb.org/browse/SERVER-7246
243
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.9%22%20AND%20project%20%3D%20SERVER
244
https://jira.mongodb.org/browse/SERVER-11478
245
https://jira.mongodb.org/browse/SERVER-11421
246
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.8%22%20AND%20project%20%3D%20SERVER
247
https://jira.mongodb.org/browse/SERVER-10596
248
https://jira.mongodb.org/browse/SERVER-9907
249
https://jira.mongodb.org/browse/SERVER-11021
250
https://jira.mongodb.org/browse/SERVER-10554
251
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.7%22%20AND%20project%20%3D%20SERVER
252
https://jira.mongodb.org/browse/SERVER-10478
253
https://jira.mongodb.org/browse/SERVER-8891
254
https://jira.mongodb.org/browse/SERVER-10085
255
https://jira.mongodb.org/browse/SERVER-9832
256
https://jira.mongodb.org/browse/SERVER-9786
257
https://jira.mongodb.org/browse/SERVER-7080
258
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.6%22%20AND%20project%20%3D%20SERVER
766 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
2.4.5 July 3, 2013

9983
259
.

260
.

261
.

262
and
263
.

264
.

265
.
2.4.4 June 4, 2013

266

267
.

268
.

269
.
2.4.3 April 23, 2013
mongoshell ignoring modied object's_ideld
270
.

271
.
copydbcommand with authorization in a sharded cluster
272
.

273
.
2.4.2 April 17, 2013

274
and
275
.

276
.
259
https://jira.mongodb.org/browse/SERVER-9983
260
https://jira.mongodb.org/browse/SERVER-9878
261
https://jira.mongodb.org/browse/SERVER-9856
262
https://jira.mongodb.org/browse/SERVER-9864
263
https://jira.mongodb.org/browse/SERVER-5442
264
https://jira.mongodb.org/browse/SERVER-9853
265
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.5%22%20AND%20project%20%3D%20SERVER
266
https://jira.mongodb.org/browse/SERVER-9721
267
https://jira.mongodb.org/browse/SERVER-9661
268
https://jira.mongodb.org/browse/SERVER-8813
269
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.4%22%20AND%20project%20%3D%20SERVER
270
https://jira.mongodb.org/browse/SERVER-9385
271
https://jira.mongodb.org/browse/SERVER-4739
272
https://jira.mongodb.org/browse/SERVER-9093
273
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.3%22%20AND%20project%20%3D%20SERVER
274
https://jira.mongodb.org/browse/SERVER-9267
275
https://jira.mongodb.org/browse/SERVER-9230
276
https://jira.mongodb.org/browse/SERVER-9125
12.2. Previous Stable Releases 767

MongoDB Documentation, Release 2.6.4

277
.

278
2.4.1 April 17, 2013

279

280
.
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 abetafeature. SeeText Indexes(page 454) for more
information.
Geospatial Support Enhancements
2dsphere index(page 447). The new index supports
281
objectsPoint,LineString, and
Polygon. See2dsphere Indexes(page 447) andGeospatial Indexes and Queries(page 444).
$geometry,$geoWithinand$geoIntersectsto work with the GeoJSON data.
Hashed Index
Add newhashed index(page 455) to index documents using hashes of eld values. When used to index a shard key,
the hashed index ensures an evenly distributed shard key. See alsoHashed Shard Keys(page 621).
Improvements to the Aggregation Framework
$geoWithinoperator and the$geoNearpipeline stage.
$sortstage immediately precedes a$limitin the pipeline.
$millisecondand$concatand modify how$minoperator processesnullvalues.
Changes to Update Operators
$setOnInsertoperator for use withupsert.
$pushoperator, supporting its use with the$each, the$sort, and the$slice
modiers.
277
https://jira.mongodb.org/browse/SERVER-9014
278
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.2%22%20AND%20project%20%3D%20SERVER
279
https://jira.mongodb.org/browse/SERVER-9087
280
https://jira.mongodb.org/issues/?jql=xVersion%20%3D%20%222.4.1%22%20AND%20project%20%3D%20SERVER
281
http://geojson.org/geojson-spec.html
768 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Additional Limitations for Map-Reduce and$whereOperations
ThemapReducecommand,groupcommand, and the$whereoperator expressions cannot access certain global
functions or properties, such asdb, that are available in themongoshell. See the individual command or operator for
details.
Improvements toserverStatusCommand
Provide additional metrics and customization for theserverStatuscommand. Seedb.serverStatus()and
serverStatusfor more information.
Security Enhancements

282
using new
http://docs.mongodb.org/manualreference/privilege-documents .

not enforce this requirement, and existing databases may have duplicates.
Congure mongod
and mongos for SSL(page 304).
For more information on security and risk management strategies, seeMongoDB Security Practices and Procedures
(page 279).
Performance Improvements
V8 JavaScript Engine
JavaScript Changes in MongoDB 2.4Consider the following impacts ofV8 JavaScript Engine(page 769) in Mon-
goDB 2.4:
Tip
Use the newinterpreterVersion() method in themongoshell and thejavascriptEngineeld in the
output ofdb.serverBuildInfo() to determine which JavaScript engine a MongoDB binary uses.
Improved ConcurrencyPreviously, MongoDB operations that required the JavaScript interpreter had to acquire
a lock, and a singlemongodcould 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
283
, abbreviated as ES5, adds many
new language features, including:

284
,

285
,
282
http://docs.mongodb.org/v2.4/reference/user-privileges
283
http://www.ecma-international.org/publications/standards/Ecma-262.htm
284
http://www.ecma-international.org/ecma-262/5.1/#sec-15.12.1
285
http://www.ecma-international.org/ecma-262/5.1/#sec-4.2.2
12.2. Previous Stable Releases 769

MongoDB Documentation, Release 2.6.4

286
,

287
, and

With V8, MongoDB supports the ES5 implementation of Javascript with the following exceptions.
Note:The following features do not work as expected on documentsreturned 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.
enumerableproperties, when added to documents returned from MongoDB queries, are not saved during
write operations.
See
288
,
289
,
290
, and
291
for more information.
For objects that have not been returned from MongoDB queries, the features work as expected.
Removed Non-Standard SpiderMonkey FeaturesV8 doesnotsupport the followingnon-standardSpiderMon-
key
292
JavaScript extensions, previously supported by MongoDB's use of SpiderMonkey as its JavaScript engine.
E4X ExtensionsV8 does not support thenon-standardE4X
293
extensions. E4X provides a native
294
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 AssignmentV8 does not support the non-standard destructuring assignments. Destructuring assign-
ment extract[s] data from arrays or objects using a syntax that mirrors the construction of array and object literals. -
Mozilla docs
295
Example
The following destructuring assignment isinvalidwith V8 and throws aSyntaxError:
286
http://www.ecma-international.org/ecma-262/5.1/#sec-15.3.4.5
287
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.16
288
https://jira.mongodb.org/browse/SERVER-8216
289
https://jira.mongodb.org/browse/SERVER-8223
290
https://jira.mongodb.org/browse/SERVER-8215
291
https://jira.mongodb.org/browse/SERVER-8214
292
https://developer.mozilla.org/en-US/docs/SpiderMonkey
293
https://developer.mozilla.org/en-US/docs/E4X
294
https://developer.mozilla.org/en-US/docs/E4X/Processing_XML_with_E4X
295
https://developer.mozilla.org/en-US/docs/JavaScript/New_in_JavaScript/1.7#Destructuring_assignment_(Merge_into_own_page.2Fsection)
770 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
original4,,];
var[b, ,c] // <== destructuring assignment
print(b)// 4
print(c)// 15
Iterator(),StopIteration(), and GeneratorsV8 does not support
ators
296
.
InternalError() V8 does not supportInternalError(). UseError()instead.
for each...inConstructV8 does not support the use of
297
construct. Usefor (var x in
y)construct instead.
Example
The followingfor each (var x in y) construct isinvalidwith V8:
varo:, version:
foreach (varvalueino) {
print(value);
}
Instead, in version 2.4, you can use thefor (var x in y)construct:
varo:, version:
for(varpropino) {
varvalue
print(value);
}
You can also use the arrayinstancemethodforEach()with the ES5 methodObject.keys():
Object.keys(o).forEach( function(key) {
varvalue
print(value);
});
Array ComprehensionV8 does not support
298
.
Use other methods such as theArrayinstance methodsmap(),filter(), orforEach().
Example
With V8, the following array comprehension isinvalid:
vara:, x:, y:, z:
vararr *iforeach (iina)if(i)]
printjson(arr)
296
https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Iterators_and_Generators
297
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Statements/for_each...in
298
https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Predened_Core_Objects#Array_comprehensions
12.2. Previous Stable Releases 771

MongoDB Documentation, Release 2.6.4
Instead, you can implement using theArrayinstancemethodforEach()and the ES5 methodObject.keys()
:
vara:, x:, y:, z:
vararr
Object.keys(a).forEach( function(key) {
varval
if(val) arr.push(val *val);
})
printjson(arr)
Note: The new logic uses theArrayinstancemethodforEach()and not thegenericmethod
Array.forEach(); V8 doesnotsupportArraygenericmethods. SeeArray Generic Methods(page 774) for
more information.
Multiple Catch BlocksV8 does not support multiplecatchblocks and will throw aSyntaxError.
Example
The following multiple catch blocks isinvalidwith V8 and will throw"SyntaxError: Unexpected token
if":
try{
something()
}catch(erriferrinstanceofSomeError) {
print(some error)
}catch(err) {
print(standard error)
}
Conditional Function DenitionV8 will produce different outcomes than SpiderMonkey with
denitions
299
.
Example
The following conditional function denition produces different outcomes in SpiderMonkey versus V8:
functiontest () {
if(false) {
functiongo () {};
}
print(typeofgo)
}
With SpiderMonkey, the conditional function outputsundefined, whereas with V8, the conditional function outputs
function.
If your code denes functions this way, it is highly recommended that you refactor the code. The following example
refactors the conditional function denition to work in both SpiderMonkey and V8.
functiontest () {
vargo;
299
https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Functions
772 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
if(false) {
go function() {}
}
print(typeofgo)
}
The refactored code outputsundefinedin both SpiderMonkey and V8.
Note:ECMAscript prohibits conditional function denitions. To force V8 to throw anError,
300
.
functiontest () {
use strict;
if(false) {
functiongo () {}
}
}
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 MethodsV8 does not support
301
. String generics are a set of methods on the
Stringclass that mirror instance methods.
Example
The following use of the generic methodString.toLowerCase() isinvalidwith V8:
varname;
varlower.toLowerCase(name);
With V8, use theStringinstance methodtoLowerCase()available through aninstanceof theStringclass
instead:
varname;
varlower
print(name
With V8, use theStringinstancemethods instead of followinggenericmethods:
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()
300
http://www.nczonline.net/blog/2012/03/13/its-time-to-start-using-javascript-strict-mode/
301
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String#String_generic_methods
12.2. Previous Stable Releases 773

MongoDB Documentation, Release 2.6.4
Array Generic MethodsV8 does not support
302
. Array generics are a set of methods on the
Arrayclass that mirror instance methods.
Example
The following use of the generic methodArray.every()isinvalidwith V8:
vararr4,,,,,];
functionisEven (val) {
return0;
}
varallEven.every(arr, isEven);
print(allEven);
With V8, use theArrayinstance methodevery()available through aninstanceof theArrayclass instead:
varallEven
print(allEven);
With V8, use theArrayinstancemethods instead of the followinggenericmethods:
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 MethodtoSource()V8 does not support theArrayinstance method
303
. Use the
Arrayinstance methodtoString()instead.
uneval()V8 does not support the non-standard methoduneval(). Use the standardized
304
method instead.
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 fea-
tures, and affects all JavaScript behavior including the commandsmapReduce,group, andevaland the query
operator$where.
SeeJavaScript Changes in MongoDB 2.4(page 769) for more information about all changes .
BSON Document Validation Enabled by Default formongodandmongorestore
Enable basicBSONobject validation formongodandmongorestorewhen writing to MongoDB data les. See
wireObjectCheckfor details.
302
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array#Array_generic_methods
303
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/toSource
304
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify
774 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Index Build Enhancements
mongodinstance. Seebuilding
indexes in the background(page 460) for more information on background index builds.
db.killOp()method to terminate a foreground index build.
Compatibility and Index Type Changes in MongoDB 2.4
(page 782) for more information.
Set Parameters as Command Line Options
Provide--setParameteras a command line option formongosandmongod. Seemongodandmongosfor
list of available options forsetParameter.
Changed Replication Behavior for Chunk Migration
By default, each document move duringchunk migration(page 631) in asharded clusterpropagates to at least one
secondary before the balancer proceeds with its next operation. SeeChunk Migration and Replication(page 632).
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. SeeChunk Migration Queuing
(page 631) for details.
Enterprise
The following changes are specic 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 mustinstall all pack-
age dependencies related to this change, including the appropriate Cyrus SASLGSSAPIlibrary. See
http://docs.mongodb.org/manualtutorial/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. SeeCongure MongoDB
with Kerberos Authentication on Linux(page 331) for more information. For drivers that provide support for Kerberos
authentication to MongoDB, refer toDriver Support(page 293).
For more information on security and risk management strategies, seeMongoDB Security Practices and Procedures
(page 279).
12.2. Previous Stable Releases 775

MongoDB Documentation, Release 2.6.4
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
305
for more information on platform support.
Upgrade Process
Upgrade MongoDB to 2.4In the general case, the upgrade from MongoDB 2.2 to 2.4 is a binary-compatible drop-
in upgrade: shut down themongodinstances and replace them withmongodinstances 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(page 777) and the considerations forreverting to 2.2 after running 2.4(page 781).
Upgrade Recommendations and ChecklistWhen upgrading, consider the following:

mongodinstance or instances.
mustupgrade following themeta-data upgrade procedure(page 777).
authorizationenabled, you will need to upgrade rst to 2.2.1
and then upgrade to 2.4. SeeRolling Upgrade Limitation for 2.2.0 Deployments Running with auth Enabled
(page 781).
system.usersdocuments (i.e. forauthorization) that you created before 2.4 youmust
ensure that there are no duplicate values for theusereld in thesystem.userscollection inanydatabase.
If youdohave documents with duplicate user elds, you must remove them before upgrading.
SeeSecurity Enhancements(page 769) for more information.
Upgrade StandalonemongodInstance to MongoDB 2.4
1.
306
. SeeInstall
MongoDB(page 5) for more information.
2. mongodinstance. Replace the existing binary with the 2.4mongodbinary and restartmongod.
Upgrade a Replica Set from MongoDB 2.2 to MongoDB 2.4You can upgrade to 2.4 by performing a rolling up-
grade of the set by upgrading the members individually while the other members are available to minimize downtime.
Use the following procedure:
1. secondarymembers of the set one at a time by shutting down themongodand replacing the 2.2
binary with the 2.4 binary. After upgrading amongodinstance, wait for the member to recover toSECONDARY
state before upgrading the next instance. To check the member's state, issuers.status()in themongo
shell.
2. mongoshell methodrs.stepDown()to step down theprimaryto allow the normalfailover
(page 523) 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 assumedPRIMARYstate, as observed in the output
ofrs.status(), shut down the previous primary and replacemongodbinary with the 2.4 binary and start
the new process.
305
http://www.mongodb.org/downloads/
306
http://www.mongodb.org/downloads
776 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
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 predened maintenance window.
Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4
Important:Only upgrade sharded clusters to 2.4 ifallmembers 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.
OverviewUpgrading asharded clusterfrom MongoDB version 2.2 to 2.4 (or 2.3) requires that you run a 2.4
mongoswith the--upgradeoption, described in this procedure. The upgrade process does not require down-
time.
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. SeeCluster Meta-
data Upgrade(page 777) for more information.
After completing the meta-data upgrade you can fully upgrade the components of the cluster. With the balancer
disabled:
mongosinstances in the cluster.
mongodcong server instances.
mongodinstances for each shard, one at a time.
SeeUpgrade Sharded Cluster Components(page 780) for more information.
Cluster Meta-data Upgrade
ConsiderationsBeware of the following properties of the cluster upgrade process:
cong database
(page 679) is at least 4 to 5 times the amount of space currently used by thecong database(page 679) data
les.
Additionally, ensure that all indexes in thecong database(page 679) 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 cong servers. Ensure low latency between the upgrade process and the cong servers.

upgrade, donotperform:
sh.enableSharding(),
sh.shardCollection() ,
sh.addShard(),
db.createCollection() ,
db.collection.drop() ,
db.dropDatabase(),
12.2. Previous Stable Releases 777

MongoDB Documentation, Release 2.6.4
any operation that creates a database, or
any other operation that modies the cluster meta-data in any way. SeeSharding Reference(page 678) for
a complete list of sharding commands. Note, however, that not all commands on theSharding Reference
(page 678) page modies the cluster meta-data.
do notuse 2.0mongodandmongosprocesses
in your cluster. 2.0 process may re-introduce old meta-data formats into cluster meta-data.
The upgraded cong database will require more storage space than before, to make backup and working copies of the
config.chunks(page 681) andconfig.collections (page 682) collections. As always, if storage require-
ments increase, themongodmight need to pre-allocate additional data les. SeeWhat tools can I use to investigate
storage use in MongoDB?(page 715) for more information.
Meta-data Upgrade ProcedureChanges to the meta-data format for sharded clusters, stored in thecong database
(page 679), require a special meta-data upgrade procedure when moving to 2.4.
Do not perform operations that modify meta-data while performing this procedure. SeeUpgrade a Sharded Cluster
from MongoDB 2.2 to MongoDB 2.4(page 777) for examples of prohibited operations.
1. cong database
(page 679) is at least 4 to 5 times the amount of space currently used by thecong database(page 679) data
les.
Additionally, ensure that all indexes in thecong database(page 679) 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 cong servers. Ensure low latency between the upgrade process and the cong servers.
To check the version of your indexes, usedb.collection.getIndexes() .
If any indexon the cong databaseis{v:0}, you should rebuild those indexes by connecting to themongos
and either: rebuild all indexes using thedb.collection.reIndex() method, or drop and rebuild specic
indexes usingdb.collection.dropIndex() and thendb.collection.ensureIndex() . If you
need to upgrade the_idindex to{v:1}usedb.collection.reIndex() .
You may have{v:0}indexes on other databases in the cluster.
2. balancer(page 629) in thesharded cluster, as described inDisable the Balancer(page 661).
Optional
For additional security during the upgrade, you can make a backup of the cong database usingmongodump
or other backup tools.
3. mongodormongosprocesses still active in the sharded cluster. The automated
upgrade process checks for 2.0 processes, but network availability can prevent a denitive check. Wait 5 minutes
after stopping or upgrading version 2.0mongosprocesses to conrm that none are still active.
4. mongosprocess withconfigDBpointing to the sharded cluster'scong servers(page 616)
and with the--upgradeoption. The upgrade process happens before the process becomes a daemon (i.e.
before--fork.)
You can upgrade an existingmongosinstance to 2.4 or you can start a newmongosinstance that can reach all
cong servers if you need to avoid reconguring a productionmongos.
Start themongoswith a command that resembles the following:
778 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
mongos --configdb <config servers> --upgrade
Without the--upgradeoption 2.4mongosprocesses 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.
5. mongosprocess starts successfully, the upgrade is complete. If themongosprocess fails to start,
check the log for more information.
If themongosterminates or loses its connection to the cong servers during the upgrade, you may always
safely retry the upgrade.
However, if the upgrade failed during the short critical section, themongoswill exit and report that the up-
grade will require manual intervention. To continue the upgrade process, you must follow theResync after an
Interruption of the Critical Section(page 779) procedure.
Optional
If themongoslogs 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 activitymongoswill force the upgrade
lock. If you can verify that there are no running upgrade processes, you may connect to a 2.2mongosprocess
and force the lock manually:
mongo <mongos.example.net>
db.getMongo().getCollection("config.locks").findOne({ _id
If the process specied in theprocesseld of this document isveriablyofine, run the following operation
to force the lock.
db.getMongo().getCollection("config.locks").update({ _id
It is always more safe to wait for themongosto verify that the lock is inactive, if you have any doubts about
the activity of another upgrade operation. In addition to theconfigUpgrade, themongosmay need to wait
for specic collection locks. Do not force the specic collection locks.
6. mongosprocesses in the sharded cluster,withoutthe--upgradeoption.
SeeUpgrade Sharded Cluster Components(page 780) for more information.
7.Re-enable the balancer(page 661). You can now perform operations that modify cluster meta-data.
Once you have upgraded,do notintroduce version 2.0 MongoDB processes into the sharded cluster. This can rein-
troduce old meta-data formats into the cong 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 SectionDuring 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 cong servers
from verifying or modifying data. If this occurs, thecong servers(page 616) must be re-synced, and there may be
problems starting newmongosprocesses. Thesharded clusterwill remain accessible, but avoid all cluster meta-
data changes until you resync the cong servers. Operations that change meta-data include: adding shards, dropping
databases, and dropping collections.
Note:Only perform the following procedureifsomething (e.g. network, power, etc.) interrupts the upgrade process
during the short critical section of the upgrade. Remember, you may always safely attempt themeta data upgrade
procedure(page 778).
12.2. Previous Stable Releases 779

MongoDB Documentation, Release 2.6.4
To resync the cong servers:
1. balancer(page 629) 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(page 777)),
you have already disabled the balancer.
2. configDBstring. For ex-
ample, if yourconfigDBstring isconfigA:27019,configB:27019,configC:27019 , shut down
configBandconfigC. Shutting down the last two cong servers ensures that mostmongosinstances will
have uninterrupted access to cluster meta-data.
3.mongodumpthe data les of the active cong server (configA).
4. configBandconfigC) to a backup location.
5. data directories.
6. --dbpathpointing to the now-empty data directory and--port
pointing to an alternate port (e.g.27020).
7. mongorestoreto repopulate the data les on the disabled documents from the active cong server
(configA) to the restarted cong servers on the new port (configB:27020,configC:27020 ). These
cong servers are now re-synced.
8. configB:27019
andconfigC:27019).
9. mongosdisables old connections only
after attempted use. 2.4 xes this problem, but to avoid this issue in version 2.2, you can restart allmongos
instances (one-by-one, to avoid downtime) and use thers.stepDown()method before restarting each of the
shardreplica set primaries.
10.
manually reset the upgrade state using a version 2.2mongos. Begin by connecting to the 2.2mongoswith the
mongoshell:
mongo <mongos.example.net>
Then, use the following operation to reset the upgrade process:
db.getMongo().getCollection("config.version").update({ _id
11. Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4
(page 777).
Upgrade Sharded Cluster ComponentsAfter you have successfully completed the meta-data upgrade process
described inMeta-data Upgrade Procedure(page 778), and the 2.4mongosinstance 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:
mongosinstances in the cluster, in any order.
mongodcong server instances, upgrading therstsystem in themongos --configdb ar-
gumentlast.
mongodsecondaries before runningreplSetStepDown
and upgrading the primary of each shard.
When this process is complete, you can nowre-enable the balancer(page 661).
780 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Rolling Upgrade Limitation for 2.2.0 Deployments Running withauthEnabledMongoDBcannotsupport
deployments that mix 2.2.0 and 2.4.0, or greater, components. MongoDB version 2.2.1 and later processescanexist 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.
1.
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.
2.
cesses at the same time.
Upgrade from 2.3 to 2.4If you used amongodfrom 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 created2dsphereortextindexes using amongod
before v2.4-rc2, you will need to rebuild these indexes. For example:
db.records.dropIndex( { loc:
db.records.dropIndex(
db.records.ensureIndex( { loc:
db.records.ensureIndex( { records:
Downgrade MongoDB from 2.4 to Previous VersionsFor some cases the on-disk format of data les used by 2.4
and 2.2mongodis compatible, and you can upgrade and downgrade if needed. However, several new features in 2.4
are incompatible with previous versions:
2dsphereindexes are incompatible with 2.2 and earliermongodinstances.
textindexes are incompatible with 2.2 and earliermongodinstances.
hashedindex as a shard key are incompatible with 2.2 and earliermongosinstances.
hashedindexes are incompatible with 2.0 and earliermongodinstances.
Important:Collections sharded using hashed shard keys, shouldnotuse 2.2mongodinstances, which cannot
correctly support cluster operations for these collections.
If you completed themeta-data upgrade for a sharded cluster(page 777), you can safely downgrade to 2.2 MongoDB
processes.Do notuse 2.0 processes after completing the upgrade procedure.
Note:In sharded clusters, once you have completed themeta-data upgrade procedure(page 777), you cannot use 2.0
mongodormongosinstances in the same cluster.
If you complete the meta-data upgrade, you can safely downgrade components in any order. When upgrade again,
always upgrademongosinstances beforemongodinstances.
Do notcreate2dsphereortextindexes in a cluster that has 2.2 components.
Considerations and CompatibilityIf you upgrade to MongoDB 2.4, and then need to run MongoDB 2.2 with the
same data les, consider the following limitations.
hashedindex 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.2mongoscannot properly route an insert operation
for a collections sharded using ahashedindex 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.
12.2. Previous Stable Releases 781

MongoDB Documentation, Release 2.6.4
nevercreate an2dsphereortextindex, you can move between a 2.4 and 2.2mongodfor a given
data set; however, after you create the rst2dsphereortextindex with a 2.4mongodyou will need to run
a 2.2mongodwith the--upgradeoption and drop any2dsphereortextindex.
Upgrade and Downgrade Procedures
Basic Downgrade and Upgrade as described below, moving between 2.2 and 2.4 is a drop-in replacement:
mongod, using the--shutdownoption as follows:
mongod --dbpath /var/mongod/data --shutdown
Replace/var/mongod/datawith your MongoDBdbPath.
mongodprocesses with the samedbPathsetting, for example:
mongod --dbpath /var/mongod/data
Replace/var/mongod/datawith your MongoDBdbPath.
Downgrade to 2.2 After Creating a2dsphereortextIndexIf you have created2dsphereortextin-
dexes while running a 2.4mongodinstance, you can downgrade at any time, by starting the2.2 mongodwith the
--upgradeoption as follows:
mongod --dbpath /var/mongod/data/ --upgrade
Then, you will need to drop any existing2dsphereortextindexes usingdb.collection.dropIndex() ,
for example:
db.records.dropIndex( { loc:
db.records.dropIndex(
Warning:--upgradewill runrepairDatabaseon any database where you have created a2dsphereor
textindex, which will rebuildallindexes.
Troubleshooting Upgrade/Downgrade OperationsIf you do not use--upgrade, when you attempt to start a
2.2mongodand you have created a2dsphereortextindex,mongodwill 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 le version of a MongoDB database, use the following operation in the shell:
db.getSiblingDB(<databasename>).stats().dataFileVersion
The major data le
307
version for both 2.2 and 2.4 is4, the minor data le version for 2.2 is5and the minor data le
version for 2.4 is6afteryou create a2dsphereortextindex.
Compatibility and Index Type Changes in MongoDB 2.4In 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, seeDowngrade MongoDB from 2.4 to Previous Versions(page 781).
307
The data le version (i.e.pdfile version) is independent and unrelated to the release version of MongoDB.
782 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
New Index TypesIn 2.4 MongoDB adds two new index types:2dsphereandtext. These index types do not
exist in 2.2, and for each database, creating a2dsphereortextindex, will upgrade the data-le version and make
that database incompatible with 2.2.
If you intend to downgrade, you should always drop all2dsphereandtextindexes before moving to 2.2.
You can use thedowngrade procedure(page 781) to downgrade these databases and run 2.2 if needed, however this
will run a full database repair (as withrepairDatabase) for all affected databases.
Index Type ValidationIn 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 specied by
strings that do not refer to an existing index type, and all numbers other than1and-1.
308
In 2.4, creating any invalid index will result in an error. Furthermore, you cannot create a2dsphereortextindex
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:
MongoDB will return the following error document:
{
"err"
"code":,
"n":number>,
"connectionId":number>,
"ok":
}
SeeUpgrade MongoDB to 2.4(page 776) for full upgrade instructions.
Other Resources

309
.

310
.

311
.

312
.
12.2.2
Upgrading
MongoDB 2.2 is a production release series and succeeds the 2.0 production release series.
308
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,
asecondaryin a replica set cannot complete an initial sync from a primary that has a"1"or"-1"index. Avoid all indexes with invalid types.
309
http://mongodb.org/downloads
310
https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+xVersion+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
311
https://jira.mongodb.org/issues/?jql=project%20%3D%20SERVER%20AND%20xVersion%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
312
https://github.com/mongodb/mongo/blob/v2.4/distsrc/THIRD-PARTY-NOTICES
12.2. Previous Stable Releases 783

MongoDB Documentation, Release 2.6.4
MongoDB 2.0 data les 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.
driverdocumentation 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 up-
grade to 2.2.

mongodinstance or instances.

turn off the balancer during the upgrade process. See theDisable the Balancer(page 661) section for more
information.
upgrade allmongosinstances before upgrading anymongodinstances.
Other than the above restrictions, 2.2 processes can interoperate with 2.0 and 1.8 tools and processes. You can safely
upgrade themongodandmongoscomponents of a deployment one by one while the deployment is otherwise oper-
ational. Be sure to read the detailed upgrade procedures below before upgrading production systems.
Upgrading a Standalonemongod
1.
313
.
2. mongodinstance. Replace the existing binary with the 2.2mongodbinary and restart Mon-
goDB.
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:
1. secondarymembers of the set one at a time by shutting down themongodand replacing the 2.0
binary with the 2.2 binary. After upgrading amongodinstance, wait for the member to recover toSECONDARY
state before upgrading the next instance. To check the member's state, issuers.status()in themongo
shell.
2. mongoshell methodrs.stepDown()to step down theprimaryto allow the normalfailover
(page 523) 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 assumedPRIMARYstate, as observed in the output
ofrs.status(), shut down the previous primary and replacemongodbinary 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 predened maintenance window.
313
http://downloads.mongodb.org/
784 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Upgrading a Sharded Cluster
Use the following procedure to upgrade a sharded cluster:
Disable the balancer(page 661).
mongosinstancesrst, in any order.
mongodcong server instances using thestand alone(page 784) procedure. To keep the
cluster online, be sure that at all times at least one cong server is up.
upgrade procedure for replica sets(page 784) detailed above.

Note:Balancing is not currently supported inmixed2.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
314
for more
information.
Changes
Major Features
Aggregation FrameworkThe aggregation framework makes it possible to do aggregation operations without need-
ing to usemap-reduce. Theaggregatecommand exposes the aggregation framework, and theaggregate()
helper in themongoshell provides an interface to these operations. Consider the following resources for background
on the aggregation framework and its use:
Aggregation Concepts(page 391)
Aggregation Reference(page 419)
Aggregation Examples(page 403)
TTL CollectionsTTL 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 tocapped 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 theExpire Data from Collections by Setting TTL(page 198) tutorial.
Concurrency ImprovementsMongoDB 2.2 increases the server's capacity for concurrent operations with the fol-
lowing improvements:
1.
315
2.
316
3.
317
To reect these changes, MongoDB now provides changed and improved reporting for concurrency and use, seelocks
andserver-status-record-statsinserver statusand seedb.currentOp(),mongotop, andmongostat.
314
https://jira.mongodb.org/browse/SERVER-6902
315
https://jira.mongodb.org/browse/SERVER-4328
316
https://jira.mongodb.org/browse/SERVER-3357
317
https://jira.mongodb.org/browse/SERVER-4538
12.2. Previous Stable Releases 785

MongoDB Documentation, Release 2.6.4
Improved Data Center Awareness with Tag Aware ShardingMongoDB 2.2 adds additional support for geo-
graphic distribution or other custom partitioning for sharded collections inclusters. By using this tag aware shard-
ing, you can automatically ensure that data in a sharded database system is always on specic 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(page 530) andwrite concern(page 72). For example, shard tagging can pin all USA data to one
or more logical shards, while replica set tagging can control whichmongodinstances (e.g. production or
reporting) the application uses to service requests.
See the documentation for the following helpers in themongoshell that support tagged sharding conguration:
sh.addShardTag()
sh.addTagRange()
sh.removeShardTag()
Also, seeTag Aware Sharding(page 671) andManage Shard Tags(page 672).
Fully Supported Read Preference SemanticsAll MongoDB clients and drivers now support fullread preferences
(page 530), including consistent support for a full range ofread preference modes(page 603) andtag sets(page 532).
This support extends to themongosand applies identically to single replica sets and to the replica sets for each shard
in asharded cluster.
Additional read preference support now exists in themongoshell using thereadPref()cursor method.
Compatibility Changes
Authentication ChangesMongoDB 2.2 provides more reliable and robust support for authentication clients, in-
cluding drivers andmongosinstances.
If your cluster runs with authentication:

mustuse
theupgrade procedure for sharded clusters(page 785).
findAndModifyReturns Null Value for Upserts that Perform InsertsIn version 2.2, forupsertthat perform
inserts with thenewoption set tofalse,findAndModifycommands will now return the following output:
{:,: null}
In themongoshell, upsertfindAndModifyoperations that perform inserts (withnewset tofalse.)only output a
nullvalue.
In version 2.0 these operations would return an empty document, e.g.{ }.
See:
318
for more information.
mongodump2.2 Output Incompatible with Pre-2.2mongorestore If you use themongodumptool from the
2.2 distribution to create a dump of a database, you must use a 2.2 (or later) version ofmongorestoreto restore
that dump.
See:
319
for more information.
318
https://jira.mongodb.org/browse/SERVER-6226
319
https://jira.mongodb.org/browse/SERVER-6961
786 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
ObjectId().toString() Returns String LiteralObjectId("...") In version 2.2, thetoString()
method returns the string representation of theObjectId()(page 166) object and has the formatObjectId("...").
Consider the following example that calls the toString() method on the
ObjectId("507c7f79bcf86cd7994f6c0e") object:
ObjectId("507c7f79bcf86cd7994f6c0e").toString()
The method now returns thestringObjectId("507c7f79bcf86cd7994f6c0e") .
Previously, in version 2.0, the method would return thehexadecimal string507c7f79bcf86cd7994f6c0e .
If compatibility between versions 2.0 and 2.2 is required, useObjectId().str(page 166), which holds the hexadecimal
string value in both versions.
ObjectId().valueOf() Returns hexadecimal stringIn version 2.2, thevalueOf()method returns the
value of theObjectId()(page 166) 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 thehexadecimal string507c7f79bcf86cd7994f6c0e .
Previously, in version 2.0, the method would return theobjectObjectId("507c7f79bcf86cd7994f6c0e") .
If compatibility between versions 2.0 and 2.2 is required, useObjectId().str(page 166) attribute, which holds the
hexadecimal string value in both versions.
Behavioral Changes
Restrictions on Collection NamesIn version 2.2, collection names cannot:
$.
"").
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:

system.prex. MongoDB reservessystem.for system collections, such as the
system.indexescollection.

maximum exibility, collections should have names less than 80 characters.
Collections names may have any other valid UTF-8 string.
See the
320
and theAre there any restrictions on the names of Collections?(page 697) FAQ item.
320
https://jira.mongodb.org/browse/SERVER-4442
12.2. Previous Stable Releases 787

MongoDB Documentation, Release 2.6.4
Restrictions on Database Names for WindowsDatabase names running on Windows can no longer contain the
following characters:
/\. "*<>:|?
The names of the data les include the database name. If you attempt to upgrade a database instance with one or more
of these characters,mongodwill refuse to start.
Change the name of these databases before upgrading. See
321
and
322
for more infor-
mation.
_idFields and Indexes on Capped CollectionsAllcapped collectionsnow have an_ideld by default,ifthey
exist outside of thelocaldatabase, and now have indexes on the_ideld. This change only affects capped
collections created with 2.2 instances and does not affect existing capped collections.
See:
323
for more information.
New$elemMatchProjection OperatorThe$elemMatchoperator allows applications to narrow the data
returned from queries so that the query operation will only return the rst matching element in an array.
See thehttp://docs.mongodb.org/manualreference/operator/projection/elemMatch doc-
umentation and the
324
and
325
issues for more information.
Windows Specic Changes
Windows XP is Not SupportedAs 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
326
for more information.
Service Support formongos.exeYou may now runmongos.exeinstances as a Windows Service. See
thehttp://docs.mongodb.org/manualreference/program/mongos.exe reference andCongure a
Windows Service for MongoDB(page 21) and
327
for more information.
Log Rotate Command SupportMongoDB for Windows now supports log rotation by way of thelogRotate
database command. See
328
for more information.
New Build Using SlimReadWrite Locks for Windows ConcurrencyLabeled 2008+ on the
329
,
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
330
for more information.
321
https://jira.mongodb.org/browse/SERVER-4584
322
https://jira.mongodb.org/browse/SERVER-6729
323
https://jira.mongodb.org/browse/SERVER-5516
324
https://jira.mongodb.org/browse/SERVER-2238
325
https://jira.mongodb.org/browse/SERVER-828
326
https://jira.mongodb.org/browse/SERVER-5648
327
https://jira.mongodb.org/browse/SERVER-1589
328
https://jira.mongodb.org/browse/SERVER-2612
329
http://www.mongodb.org/downloads
330
https://jira.mongodb.org/browse/SERVER-3844
788 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Tool Improvements
Index Denitions Handled bymongodumpandmongorestore When you specify the--collectionoption
tomongodump,mongodumpwill now backup the denitions for all indexes that exist on the source database. When
you attempt to restore this backup withmongorestore, the targetmongodwill rebuild all indexes. See
808
331
for more information.
mongorestorenow includes the--noIndexRestore option to provide the preceding behavior. Use
--noIndexRestoreto preventmongorestorefrom building previous indexes.
mongooplogfor Replaying OplogsThemongooplogtool makes it possible to pulloplogentries
frommongodinstance and apply them to anothermongodinstance. You can usemongooplog
to achieve point-in-time backup of a MongoDB data set. See the
332
case and the
http://docs.mongodb.org/manualreference/program/mongooplog documentation.
Authentication Support formongotopandmongostatmongotopandmongostatnow contain support for
username/password authentication. See
333
and
334
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 formongoimportandmongorestore mongoimportnow 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--stopOnErroroption will produce an error rather than silently continue importing data. See
SERVER-3937
335
for more information.
Inmongorestore, the--woption provides support for congurable write concern.
mongodumpSupport for Reading from SecondariesYou can now runmongodumpwhen connected to asec-
ondarymember of areplica set. See
336
for more information.
mongoimportSupport for full 16MB DocumentsPreviously,mongoimportwould only import documents
that were less than 4 megabytes in size. This issue is now corrected, and you may usemongoimportto import
documents that are at least 16 megabytes ins size. See
337
for more information.
Timestamp()Extended JSON formatMongoDB extended JSON now includes a newTimestamp()type to
represent the Timestamp type that MongoDB uses for timestamps in theoplogamong other contexts.
This permits tools likemongooplogandmongodumpto query for specic timestamps. Consider the following
mongodumpoperation:
331
https://jira.mongodb.org/browse/SERVER-808
332
https://jira.mongodb.org/browse/SERVER-3873
333
https://jira.mongodb.org/browse/SERVER-3875
334
https://jira.mongodb.org/browse/SERVER-3871
335
https://jira.mongodb.org/browse/SERVER-3937
336
https://jira.mongodb.org/browse/SERVER-3854
337
https://jira.mongodb.org/browse/SERVER-4593
12.2. Previous Stable Releases 789

MongoDB Documentation, Release 2.6.4
mongodump --db
See
338
for more information.
Shell Improvements
Improved Shell User Interface2.2 includes a number of changes that improve the overall quality and consistency
of the user interface for themongoshell:

339
for more information.

340
for more information.
editcommand. See
341
for more information.
Helper to load Server-Side FunctionsThedb.loadServerScripts() loads the contents of the current
database'ssystem.jscollection into the currentmongoshell session. See
342
for more informa-
tion.
Support for Bulk InsertsIf you pass an array ofdocumentsto theinsert()method, themongoshell will now
perform a bulk insert operation. See
343
and
344
for more information.
Note:For bulk inserts on sharded clusters, thegetLastErrorcommand alone is insufcient to verify success.
Applications should must verify the success of bulk inserts in application logic.
Operations
Support for Logging to SyslogSee the
345
case and the documentation of thesyslogFacility
run-time option or themongod --syslogandmongos --syslogcommand line-options.
touchCommandAdded thetouchcommand to read the data and/or indexes from a collection into memory. See:
SERVER-2023
346
andtouchfor more information.
indexCountersNo Longer Report Sampled DataindexCountersnow report actual counters that reect
index use and state. In previous versions, these data were sampled. See
347
andindexCountersfor
more information.
Padding Speciable oncompactCommandSee the documentation of thecompactand the
348
issue for more information.
338
https://jira.mongodb.org/browse/SERVER-3483
339
https://jira.mongodb.org/browse/SERVER-4312
340
https://jira.mongodb.org/browse/SERVER-3470
341
https://jira.mongodb.org/browse/SERVER-3998
342
https://jira.mongodb.org/browse/SERVER-1651
343
https://jira.mongodb.org/browse/SERVER-3819
344
https://jira.mongodb.org/browse/SERVER-2395
345
https://jira.mongodb.org/browse/SERVER-2957
346
https://jira.mongodb.org/browse/SERVER-2023
347
https://jira.mongodb.org/browse/SERVER-5784
348
https://jira.mongodb.org/browse/SERVER-4018
790 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Added Build Flag to Use System LibrariesThe 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 passsconsusing the
--use-system-boost ag, as follows:
scons --use-system-boost
When building MongoDB, you can also passsconsa ag to compile MongoDB using only system libraries rather
than the included versions of the libraries. For example:
scons --use-system-all
See the
349
and
350
issues for more information.
Memory Allocator Changed to TCMallocTo improve performance, MongoDB 2.2 uses the TCMalloc memory
allocator from Google Perftools. For more information about this change see the
351
and
4683
352
. For more information about TCMalloc, see the documentation of
353
itself.
Replication
Improved Logging for Replica Set LagWhensecondarymembers of a replica set fall behind in replication,
mongodnow provides better reporting in the log. This makes it possible to track replication in general and iden-
tify what process may produce errors or halt replication. See
354
for more information.
Replica Set Members can Sync from Specic MembersThe newreplSetSyncFromcommand and new
rs.syncFrom()helper in themongoshell make it possible for you to manually congure from which mem-
ber of the set a replica will polloplogentries. Use these commands to override the default selection logic if needed.
Always exercise caution withreplSetSyncFromwhen overriding the default behavior.
Replica Set Members will not Sync from Members Without Indexes UnlessbuildIndexes: false To
prevent inconsistency between members of replica sets, if the member of a replica set hasbuildIndexes(page 595)
set totrue, other members of the replica set willnotsync from this member, unless they also havebuildIndexes
(page 595) set totrue. See
355
for more information.
New Option To Congure Index Pre-Fetching during ReplicationBy default, when replicating options,secon-
darieswill pre-fetchIndexes(page 431) associated with a query to improve replication throughput in most cases. The
replication.secondaryIndexPrefetch setting and--replIndexPrefetch option allow administra-
tors to disable this feature or allow themongodto pre-fetch only the index on the_ideld. See
356
for more information.
Map Reduce Improvements
In 2.2 Map Reduce received the following improvements:
349
https://jira.mongodb.org/browse/SERVER-3829
350
https://jira.mongodb.org/browse/SERVER-5172
351
https://jira.mongodb.org/browse/SERVER-188
352
https://jira.mongodb.org/browse/SERVER-4683
353
http://goog-perftools.sourceforge.net/doc/tcmalloc.html
354
https://jira.mongodb.org/browse/SERVER-3575
355
https://jira.mongodb.org/browse/SERVER-4160
356
https://jira.mongodb.org/browse/SERVER-6718
12.2. Previous Stable Releases 791

MongoDB Documentation, Release 2.6.4

357
, and

358
.
Sharding Improvements
Index on Shard Keys Can Now Be a Compound IndexIf your shard key uses the prex 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 theShard Key Indexes(page 633) documentation and
359
for more information.
Migration Thresholds ModiedThemigration thresholds(page 630) have changed in 2.2 to permit more even
distribution ofchunksin collections that have smaller quantities of data. See theMigration Thresholds(page 630)
documentation for more information.
Licensing Changes
Added License notice for Google Perftools (TCMalloc Utility). See the
360
and the
361
for more information.
Resources

362
.

363
.

364
.

365
.

366
.
12.2.3
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.
357
https://jira.mongodb.org/browse/SERVER-4521
358
https://jira.mongodb.org/browse/SERVER-4158
359
https://jira.mongodb.org/browse/SERVER-1506
360
https://github.com/mongodb/mongo/blob/v2.2/distsrc/THIRD-PARTY-NOTICES#L231
361
https://jira.mongodb.org/browse/SERVER-4683
362
http://mongodb.org/downloads
363
https://jira.mongodb.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+SERVER+AND+xVersion+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
364
https://jira.mongodb.org/issues/?lter=11225&jql=project%20%3D%20SERVER%20AND%20xVersion%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
365
https://github.com/mongodb/mongo/blob/v2.2/distsrc/THIRD-PARTY-NOTICES
366
http://www.mongodb.com/events/webinar/mongodb-online-conference-sept
792 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
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.
mongoimportandmongoexportnow correctly adhere to the CSV spec for handling CSV input/output. This
may break existing import/export workows that relied on the previous behavior. For more information see
1097
367
.
Journaling
368
isenabled by defaultin 2.0 for 64-bit builds. If you still prefer to run without journaling, startmongod
with the--nojournalrun-time option. Otherwise, MongoDB creates journal les during startup. The rst time
you startmongodwith journaling, you will see a delay asmongodcreates new les. In addition, you may see reduced
write throughput.
2.0mongodinstances are interoperable with 1.8mongodinstances; however, for best results, upgrade your deploy-
ments using the following procedures:
Upgrading a Standalonemongod
1.
369
.
2. mongodinstance. Replace the existing binary with the 2.0.xmongodbinary and restart Mon-
goDB.
Upgrading a Replica Set
1. secondarymembers of the set one at a time by shutting down themongodand replacing the 1.8
binary with the 2.0.x binary from the
370
.
2.
less than 10 seconds), or you can setwrite concern(page 72) in your application code to conrm that each
update reaches multiple servers.
3. rs.stepDown()to step down the primary to allow the normalfailover(page 523) procedure.
rs.stepDown()andreplSetStepDownprovide 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 themongodbinary with
the 2.0.x binary.
Upgrading a Sharded Cluster
1. cong serverinstancesrst, in any order. Since cong servers use two-phase commit,shardcon-
guration metadata updates will halt until all are up and running.
2. mongosrouters in any order.
367
https://jira.mongodb.org/browse/SERVER-1097
368
http://www.mongodb.org/display/DOCS/Journaling
369
http://downloads.mongodb.org/
370
http://downloads.mongodb.org/
12.2. Previous Stable Releases 793

MongoDB Documentation, Release 2.6.4
Changes
Compact Command
Acompactcommand 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
371
for more information.
The specic operations yield in 2.0 are:
_id

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 signicant improvements to theindex(page 471). Indexes are often 25% smaller and 25% faster (depends
on the use case). When upgrading from previous versions, the benets 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:

notwork in versions prior to 2.0. Do not reindex on a secondary. For a workaround, see
372
.
repairDatabasecommand converts indexes to a 2.0 indexes.
To convert all indexes for a given collection to the2.0 type(page 794), invoke thecompactcommand.
Once you create new indexes, downgrading to 1.8.x will require a re-index of any indexes created using 2.0. SeeBuild
Old Style Indexes(page 471).
Sharding Authentication
Applications can now use authentication withsharded clusters.
371
https://jira.mongodb.org/browse/SERVER-2563
372
https://jira.mongodb.org/browse/SERVER-3866
794 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Replica Sets
Hidden Nodes in Sharded ClustersIn 2.0,mongosinstances can now determine when a member of a replica set
becomes hidden without requiring a restart. In 1.8,mongosif you recongured a member as hidden, youhadto
restartmongosto prevent queries from reaching the hidden member.
PrioritiesEachreplica setmember can now have a priority value consisting of a oating-point from 0 to 1000,
inclusive. Priorities let you control which member of the set you prefer to have asprimarythe 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, andC, and suppose that their priorities are set
as follows:
A`s priority is2.
B`s priority is3.
C`s priority is1.
During normal operation, the set will always choseBas primary. IfBbecomes unavailable, the set will electAas
primary.
For more information, see thepriority(page 596) documentation.
Data-Center AwarenessYou can now tagreplica setmembers to indicate their location. You can use these tags
to design customwrite rules(page 72) across data centers, racks, specic servers, or any other architecture choice.
For example, an administrator can dene rules such as very important write orcustomerDataor 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})
which would succeed if it fullled the conditions the DBA dened for very important write.
For more information, see
373
.
Drivers may also support tag-aware reads. Instead of specifying slaveOk, you spec-
ifyslaveOkwith tags indicating which data-centers to read from. For details, see the
http://docs.mongodb.org/manualapplications/drivers documentation.
w:majorityYou can also setwtomajorityto ensure that the write propagates to a majority of nodes, ef-
fectively committing it. The value for majority will automatically adjust as you add or remove nodes from the
set.
For more information, seeWrite Concern(page 72).
Reconguration with a Minority UpIf the majority of servers in a set has been permanently lost, you can now
force a reconguration of the set to bring it back online.
For more information seeRecongure a Replica Set with Unavailable Members(page 580).
Primary Checks for a Caught up Secondary before Stepping DownTo minimize time without aprimary, the
rs.stepDown()method will now fail if the primary does not see asecondarywithin 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 alsoForce a Member to Become Primary(page 573).
373
http://www.mongodb.org/display/DOCS/Data+Center+Awareness#DataCenterAwareness-Tagging%28version2.0%29
12.2. Previous Stable Releases 795

MongoDB Documentation, Release 2.6.4
Extended Shutdown on the Primary to Minimize InterruptionWhen you call theshutdowncommand, the
primarywill refuse to shut down unless there is asecondarywhose 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 theshutdowncommand 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 ModeWhenrepairorcompactruns on asecondary, the secondary will automatically drop into
recovering mode until the operation nishes. This prevents clients from trying to read from it while it's busy.
Geospatial Features
Multi-Location DocumentsIndexing is now supported on documents which have multiple location objects, em-
bedded either inline or in nested sub-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
374
.
Polygon searchesPolygonal$withinqueries are also now supported for simple polygon shapes. For details, see
the$withinoperator documentation.
Journaling Enhancements
--nojournalcommand line option to
disable it.

--journalCommitInterval run-time option exists for specifying your own group commit interval.
The default settings do not change.
{ 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.
NewContinueOnErrorOption for Bulk Insert
Set thecontinueOnErroroption for bulk inserts, in thedriver, 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
getLastErrorcommand will report whether any inserts have failed, not just the last one. If multiple errors occur,
the client will only receive the most recentgetLastErrorresults.
See
375
.
Note:For bulk inserts on sharded clusters, thegetLastErrorcommand alone is insufcient to verify success.
Applications should must verify the success of bulk inserts in application logic.
374
http://www.mongodb.org/display/DOCS/Geospatial+Indexing#GeospatialIndexing-MultilocationDocuments
375
http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPINSERT
796 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Map Reduce
Output to a Sharded CollectionUsing the newshardedag, it is possible to send the result of a map/reduce to
a sharded collection. Combined with thereduceormergeags, it is possible to keep adding data to very large
collections from map/reduce jobs.
For more information, see
376
andhttp://docs.mongodb.org/manualreference/command/mapReduce .
Performance ImprovementsMap/reduce performance will benet from the following:

jsMode ag. See
http://docs.mongodb.org/manualreference/command/mapReduce .
New Querying Features
Additional regex options:sAllows the dot (.) to match all characters including new lines. This is in addition to
the currently supportedi,mandx. See
377
and$regex.
$andA special boolean$andquery operator is now available.
Command Output Changes
The output of thevalidatecommand and the documents in thesystem.profilecollection have both been
enhanced to return information as BSON objects with keys for each value rather than as free-form strings.
Shell Features
Custom PromptYou can dene a custom prompt for themongoshell. 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
Prompt
378
.
Default Shell Init ScriptOn startup, the shell will check for a.mongorc.jsle in the user's home directory.
The shell will execute this le after connecting to the database and before displaying the prompt.
If you would like the shell not to run the.mongorc.jsle automatically, start the shell with--norc.
For more information, seehttp://docs.mongodb.org/manualreference/program/mongo .
Most Commands Require Authentication
In 2.0, when running with authentication (e.g.authorization)alldatabase commands require authentication,
exceptthe following commands.
isMaster
376
http://www.mongodb.org/display/DOCS/MapReduce#MapReduce-Outputoptions
377
http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-RegularExpressions
378
http://www.mongodb.org/display/DOCS/Overview+-+The+MongoDB+Interactive+Shell#Overview-TheMongoDBInteractiveShell-
CustomPrompt
12.2. Previous Stable Releases 797

MongoDB Documentation, Release 2.6.4
authenticate
getnonce
buildInfo
ping
isdbgrid
Resources

379

380

381
12.2.4
Upgrading
MongoDB 1.8 is a standard, incremental production release and works as a drop-in replacement for MongoDB 1.6,
except:
Replica setmembers should be upgraded in a particular order, as described inUpgrading a Replica Set
(page 799).
mapReducecommand has changed in 1.8, causing incompatibility with previous releases.mapReduce
no longer generates temporary collections (thus,keepTemphas been removed). Now, you must always supply
a value forout. See theouteld options in themapReducedocument. 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 Standalonemongod
1.
382
.
2. mongodinstance.
3. mongodbinary.
4.
379
http://mongodb.org/downloads
380
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=11002
381
https://jira.mongodb.org/issues/?lter=11023&jql=project%20%3D%20SERVER%20AND%20xVersion%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
382
http://downloads.mongodb.org/
798 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Upgrading a Replica Set
1.8.xsecondariescanreplicate from 1.6.xprimaries.
1.6.x secondariescannotreplicate from 1.8.x primaries.
Thus, to upgrade areplica setyou must replace all of your secondaries rst, then the primary.
For example, suppose you have a replica set with a primary, anarbiterand several secondaries. To upgrade the set, do
the following:
1.
(a)
(b)
383
.
2.
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 of0before upgrading, and then change them back afterwards.
To do so:
(a) rs.config()and paste the results into a text le.
(b) 0. For example:
config
{
"_id",
"version",
"members"
{
"_id",
"host"
},
{
"_id",
"host"
},
{
"_id",
"host",
"arbiterOnly" true
}
{
"_id",
"host"
},
{
"_id",
"host"
},
]
}
config.version++
3
rs.isMaster()
{
"setName",
383
http://downloads.mongodb.org/
12.2. Previous Stable Releases 799

MongoDB Documentation, Release 2.6.4
"ismaster" false,
"secondary" true,
"hosts"
"ubuntu:27017",
"ubuntu:27018"
],
"arbiters"
"ubuntu:27019"
],
"primary",
"ok"
}
// for each secondary
config.members[0].priority
config.members[3].priority
config.members[4].priority
rs.reconfig(config)
3.
(a)
(b)
384
.
4.
config
config.version++
config.members[0].priority
config.members[3].priority
config.members[4].priority
rs.reconfig(config)
5.
Download Page
385
.
Upgrading a Sharded Cluster
1.
mongoa_mongos_hostname>
use config
db.settings.update({_id:"balancer"},{$set: true}},true)
2. shard:
replica set, follow the directions above forUpgrading a Replica Set(page 799).
mongodprocess, shut it down and then restart it with the 1.8.x binary from the
MongoDB Download Page
386
.
3. mongos:
(a) mongosprocess.
(b)
387
.
384
http://downloads.mongodb.org/
385
http://downloads.mongodb.org/
386
http://downloads.mongodb.org/
387
http://downloads.mongodb.org/
800 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
4.
(a)
(b)
388
.
5.
use config
db.settings.update({_id:"balancer"},{$set: 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.
JournalingReturning to 1.6 after using 1.8Journaling(page 275) works ne, as journaling does not change anything
about the data le format. Suppose you are running 1.8.x with journaling enabled and you decide to switch back to
1.6. There are two scenarios:

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-aheadJournaling Mechanics(page 275) to facilitate fast crash recovery and durability
in the storage engine. With journaling enabled, amongodcan be quickly restarted following a crash without needing
to repair thecollections. The aggregation framework makes it possible to do aggregation
Sparse and Covered Indexes
Sparse Indexes(page 457) are indexes that only include documents that contain the elds specied in the index.
Documents missing the eld will not appear in the index at all. This can signicantly reduce index size for indexes of
elds that contain only a subset of documents within acollection.
Covered Indexes(page 495) enable MongoDB to answer queries entirely from the index when the query only selects
elds that the index contains.
Incremental MapReduce Support
ThemapReducecommand supports new options that enable incrementally updating existingcollections. 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:
388
http://downloads.mongodb.org/
12.2. Previous Stable Releases 801

MongoDB Documentation, Release 2.6.4

existing keys in the output collection if it already exists. Other keys will remain in the collection.

phase will be reduced with the existing document in the output collection.

a permanent output collection in previous releases)

is similar to the temporary collections generated in previous releases, except results are limited to 8MB.
For more information, see theouteld options in themapReducedocument.
Additional Changes and Enhancements
1.8.1

1.8.0

1.7.6

1.7.5
Journaling(page 275).

replica setconnectivity formongos.
getLastErrorimprovements forsharding.
1.7.4
mongosroutesslaveOkqueries tosecondariesinreplica sets.
mapReduceoutput options.
Sparse Indexes(page 457).
1.7.3
covered index(page 495) support.

mapReducecan merge or reduce results into an existing collection.
mongodtracks andmongostatdisplays network usage. Seemongostat.
802 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4

1.7.2
$renameoperator allows renaming of elds in a document.
db.eval()not to block.

mongostat --discover option

1.7.1

$elemMatchon primitives in embedded arrays.

$pullworks on primitives in arrays.
1.7.0

getLastErrorDefaults (page 598) for replica sets.

Release Announcement Forum Pages

389
,
390

391
,
392
,
393
,
394
,
395
,
396
,
397
389
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/v09MbhEm62Y
390
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/JeHQOnam6Qk
391
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/3t6GNZ1qGYc
392
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/S5R0Tx9wkEg
393
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/9Om3Vuw-y9c
394
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/DfNUrdbmI
395
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/df7mwK6Xixo
396
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/HUR9zYtTpA8
397
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/TUnJCg9161A
12.2. Previous Stable Releases 803

MongoDB Documentation, Release 2.6.4
Resources

398

399
12.2.5
Upgrading
MongoDB 1.6 is a drop-in replacement for 1.4. To upgrade, simply shutdownmongodthen 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(page 607) is now production-ready, making MongoDB horizontally scalable, with no single point of failure.
A single instance ofmongodcan now be upgraded to a distributed cluster with zero downtime when the need arises.
Sharding(page 607)
Deploy a Sharded Cluster(page 635)
Convert a Replica Set to a Replicated Sharded Cluster(page 643)
Replica Sets
Replica sets(page 503), which provide automated failover among a cluster ofnnodes, are also now available.
Please note that replica pairs are now deprecated; we strongly recommend that replica pair users upgrade to replica
sets.
Replication(page 503)
Deploy a Replica Set(page 545)
Convert a Standalone to a Replica Set(page 556)
Other Improvements
woption (andwtimeout) forces writes to be propagated tonservers before returning success (this works
especially well with replica sets)
$or queries

$sliceoperator for returning subsets of arrays

findAndModifycommand now supports upserts. It also allows you to specify elds to return
398
http://mongodb.org/downloads
399
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=10172
804 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4

Installation

1.6.x Release Notes

400
1.5.x Release Notes

401

402

403

404

405

406

407

408

409
You can see a full list of all changes on
410
.
Thank you everyone for your support and suggestions!
12.2.6
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 shutdownmongod, then restart with the new binaries. (Users upgrading from release 1.0 should review the
1.2 release notes(page 807), in particular the instructions for upgrading the DB format.)
Release 1.4 includes the following improvements over release 1.2:
400
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/06_QCC05Fpk
401
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/uJfF1QN6Thk
402
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/OYvz40RWs90
403
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/4l0N2U_H0cQ
404
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/oO749nvTARY
405
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/380V_Ec_q1c
406
https://groups.google.com/forum/?hl=en&fromgroups=#!topic/mongodb-user/hsUQL9CxTQw
407
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/94EE3HVidAA
408
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/7SBPQ2RSfdM
409
https://groups.google.com/forum/?fromgroups=#!topic/mongodb-user/VAhJcjDGTy0
410
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=10107
12.2. Previous Stable Releases 805

MongoDB Documentation, Release 2.6.4
Core Server Enhancements
concurrency(page 702) improvements

background index creation(page 460)

Replication and Sharding

--fastsync)
--slavedelay)

$increplication xes

Deployment and Production
congure slow threshold for proling(page 211)
fsync + lockfor backing up raw les
--directoryperdb)
http://localhost:28017/_status to get serverStatus via http
--restto enable)
logRotate
serverStatuscommand (db.serverStatus()) - counters andreplication lag(page 589) stats
mongostattool
Query Language Improvements
$allwith regex
$not
$elemMatch

$addToSet
$unset
$pullsupports object matching
$setwith array indexes
806 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Geo
2d geospatial search(page 452)
$centerand$boxsearches
12.2.7
New Features

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 yourmongodprocess
run./mongod --upgrade
startmongodagain

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

to update the slave rst.
mongoimport
mongoimportjsonhas been removed and is replaced withmongoimportthat can do json/csv/tsv
eld lter changing

returned. Now the eld lter only changes the output, not which objects are returned. If you need that behavior,
you can use$exists
12.2. Previous Stable Releases 807

MongoDB Documentation, Release 2.6.4
12.3
12.3.1
These release notes outline a change to all driver interfaces released in November 2012. See release notes for specic
drivers for additional information.
Changes
As of the releases listed below, there are two major changes to all drivers:
1.
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 namedMongoClient, or similar depending on how host languages
handle namespacing.
2. MongoClientclass will be to acknowledge all write operations
411
.
This will allow your application to receive acknowledgment of all write operations.
See the documentation ofWrite Concern(page 72) for more information about write concern in MongoDB.
Please migrate to the newMongoClientclass expeditiously.
Releases
The following driver releases will include the changes outlined inChanges(page 808). See each driver's release notes
for a full account of each release as well as other related driver-specic changes.

12.4
For MongoDB2.4.1,2.4refers to the release series and.1refers to the revision. The second component of the
release series (e.g.4in2.4.1) describes the type of release series. Release series ending with even numbers (e.g.4
above) arestableand ready for production, while odd numbers are fordevelopmentand testing only.
411
The drivers will callgetLastErrorwithout arguments, which is logically equivalent to thew: 1option; however, this operation allows
replica setusers to override the default write concern with thegetLastErrorDefaults (page 598) setting in theReplica Set Conguration
(page 594).
808 Chapter 12. Release Notes

MongoDB Documentation, Release 2.6.4
Generally, changes in the release series (e.g.2.2to2.4) mark the introduction of new features that may break back-
wards compatibility. Changes to the revision number mark the release bug xes 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 rst number to indicate a major version. For details, seedrivers-version-numbers.
Example
Version numbers

for testing only. Includes new features and changes for testing. Interfaces and
stability may not be compatible in development releases.

12.4. MongoDB Version Numbers 809

MongoDB Documentation, Release 2.6.4
810 Chapter 12. Release Notes

CHAPTER13
About MongoDB Documentation
The MongoDB Manual
1
contains comprehensive documentation on the MongoDBdocument-oriented database man-
agement system. This page describes the manual's licensing, editions, and versions, and describes how to make a
change request and how to contribute to the manual.
For more information on MongoDB, see
2
. To download MongoDB, see
the
3
.
13.1
This manual is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported
4
(i.e.
CC-BY-NC-SA) license.
The MongoDB Manual is copyright © 2011-2014 MongoDB, Inc.
13.2
In addition to the
5
, you can also access this content in the following editions:

6

7

8
(without reference.)

9
You also can access PDF les that contain subsets of the MongoDB Manual:

10

11
1
http://docs.mongodb.org/manual/#
2
http://www.mongodb.org/about/
3
http://www.mongodb.org/downloads
4
http://creativecommons.org/licenses/by-nc-sa/3.0/
5
http://docs.mongodb.org/manual/#
6
http://docs.mongodb.org/master/MongoDB-manual.epub
7
http://docs.mongodb.org/master/single/
8
http://docs.mongodb.org/master/MongoDB-manual.pdf
9
http://docs.mongodb.org/master/manual.tar.gz
10
http://docs.mongodb.org/master/MongoDB-reference-manual.pdf
11
http://docs.mongodb.org/master/MongoDB-crud-guide.pdf
811

MongoDB Documentation, Release 2.6.4

12

13

14

15

16

17
MongoDB Reference documentation is also available as part of
18
. You can also access the
Pages
19
which are also distributed with the ofcial MongoDB Packages.
13.3
This version of the manual reects version 2.6 of MongoDB.
See the
20
for an overview of all editions and output formats of the MongoDB
Manual. You can see the full revision history and track ongoing improvements and additions for all versions of the
manual from its
21
.
This edition reects master branch of the documentation as of the
6b5d51a49f42f8c4046a3bd277c5b24840a24e87 revision. This branch is explicitly accessible via
http://docs.mongodb.org/master and you can always reference the commit of the current manual in the
22
le.
The most up-to-date, current, and stable version of the manual is always available at
http://docs.mongodb.org/manual/.
13.4
To report an issue with this manual or to make a change request, le a ticket at the
23
.
13.5
13.5.1
The original language of all MongoDB documentation is American English. However it is of critical importance to
the documentation project to ensure that speakers of other languages can read and understand the documentation.
12
http://docs.mongodb.org/master/MongoDB-data-models-guide.pdf
13
http://docs.mongodb.org/master/MongoDB-aggregation-guide.pdf
14
http://docs.mongodb.org/master/MongoDB-replication-guide.pdf
15
http://docs.mongodb.org/master/MongoDB-sharding-guide.pdf
16
http://docs.mongodb.org/master/MongoDB-administration-guide.pdf
17
http://docs.mongodb.org/master/MongoDB-security-guide.pdf
18
http://kapeli.com/dash
19
http://docs.mongodb.org/master/manpages.tar.gz
20
http://docs.mongodb.org
21
https://github.com/mongodb/docs
22
http://docs.mongodb.org/master/release.txt
23
https://jira.mongodb.org/browse/DOCS
812 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
To this end, the MongoDB Documentation Project is preparing to launch a translation effort to allow the community
to help bring the documentation to speakers of other languages.
If you would like to express interest in helping to translate the MongoDB documentation once this project is opened
to the public, please:

24
, and

25
user group.
The
26
user group exists to facilitate collaboration between translators and the documentation
team at large. You can join the group without signing the Contributor Agreement, but you will not be allowed to
contribute translations.
See also:
Contribute to the Documentation(page 812)
Style Guide and Documentation Conventions(page 814)
MongoDB Manual Organization(page 823)
MongoDB Documentation Practices and Processes(page 820)
MongoDB Documentation Build System(page 824)
The entire documentation source for this manual is available in the
27
, which is one of the
MongoDB project repositories on GitHub
28
.
To contribute to the documentation, you can open a
29
, fork the
30
, make a
change, and issue a pull request.
In order for the documentation team to accept your change, you must complete the
ment
31
.
You can clone the repository by issuing the following command at your system shell:
git clone git://github.com/mongodb/docs.git
13.5.2
The MongoDB Manual uses
32
, a sophisticated documentation engine built upon
33
. The orig-
inal
34
les, as well as all necessary Sphinx extensions and build tools, are available in the same
repository as the documentation.
For more information on the MongoDB documentation process, see:
24
http://www.mongodb.com/legal/contributor-agreement
25
http://groups.google.com/group/mongodb-translators
26
http://groups.google.com/group/mongodb-translators
27
https://github.com/mongodb/docs
28
http://github.com/mongodb
29
https://github.com/
30
https://github.com/mongodb/docs
31
http://www.mongodb.com/contributor
32
http://sphinx-doc.org//
33
http://docutils.sourceforge.net/
34
http://docutils.sourceforge.net/rst.html
13.5. Contribute to the Documentation 813

MongoDB Documentation, Release 2.6.4
Style Guide and Documentation Conventions
This document provides an overview of the style for the MongoDB documentation stored in this repository. The
overarching goal of this style guide is to provide an accessible base style to ensure that our documentation is easy to
read, simple to use, and straightforward to maintain.
For information regarding the MongoDB Manual organization, seeMongoDB Manual Organization(page 823).
Document History
2011-09-27: Document created with a (very) rough list of style guidelines, conventions, and questions.
2012-01-12: Document revised based on slight shifts in practice, and as part of an effort of making it easier for people
outside of the documentation team to contribute to documentation.
2012-03-21: Merged in content from the Jargon, and cleaned up style in light of recent experiences.
2012-08-10: Addition to the Referencing section.
2013-02-07: Migrated this document to the manual. Added map-reduce terminology convention. Other edits.
2013-11-15: Added new table of preferred terms.
Naming Conventions
This section contains guidelines on naming les, sections, documents and other document elements.

For Sphinx, all les should have a.txtextension.
Separate words in le names with hyphens (i.e.-.)
For most documents, le names should have a terse one or two word name that de-
scribes the material covered in the document. Allow the path of the le within the doc-
ument tree to add some of the required context/categorization. For example it's ac-
ceptable to have http://docs.mongodb.org/manualcore/sharding.rst and
http://docs.mongodb.org/manualadministration/sharding.rst .
For tutorials, the full title of the document should be in the le name. For example,
http://docs.mongodb.org/manualtutorial/replace-one-configuration-server-in-a-shard-cluster.rst

be addressed, without needing them to read the content. This shortens the amount of time that people spend
looking for answers, and improvise search/scanning, and possibly SEO.

:ref:references in documents), use names that include enough context to
be intelligible through all documentation. For example, use replica-set-secondary-only-node as
opposed to secondary-only-node. This makes the source more usable and easier to maintain.
Style Guide
This includes the local typesetting, English, grammatical, conventions and preferences that all documents in the manual
should use. The goal here is to choose good standards, that are clear, and have a stylistic minimalism that does not
interfere with or distract from the content. A uniform style will improve user experience and minimize the effect of a
multi-authored document.
814 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
Punctuation

Oxford commas are the commas in a list of things (e.g. something, something else, and another thing) before
the conjunction (e.g. and or or.).

HeadingsUse title case for headings and document titles. Title case capitalizes the rst letter of the rst, last, and
all signicant words.
VerbsVerb tense and mood preferences, with examples:
Avoidthe rst person. For example do not say, We will begin the backup process by locking the database, or
I begin the backup process by locking my database instance.
Usethe second person. If you need to back up your database, start by locking the database rst. In practice,
however, it's more concise to imply second person using the imperative, as in Before initiating a backup, lock
the database.

loss, back up your databases.

database will lead to an invalid state.

foo and this will do foo when possible. Use does foo over will do foo in situations where this foos is
unacceptable.
Referencing
alwayslink to the Jira case. The Manual's
conf.pyprovides an:issue:role that links directly to a Jira case (e.g.:issue:\`SERVER-9001\` ).

only the rst occurrence of the reference in a section. You shouldalwaysreference objects, except in section
headings.
whyrst; the link second.
For example, instead of this:
Use theConvert a Replica Set to a Replicated Sharded Cluster(page 643) procedure if you have an existing
replica set.
Type this:
To deploy a sharded cluster for an existing replica set, seeConvert a Replica Set to a Replicated Sharded Cluster
(page 643).
General Formulations

Do not use a period after every item unless the list item completes the unnished sentence before the list.
13.5. Contribute to the Documentation 815

MongoDB Documentation, Release 2.6.4
Use appropriate commas and conjunctions in the list items.
Typically begin a bulleted list with an introductory sentence or clause, with a colon or comma.

standalone
workow
mongodinstance that cannot be accessed. Do not
use the colloquialism down.

Structural Formulations

h3 blocks, 2 h3 blocks, or more than 2 h3 blocks.

the contents of the section. In a single document you should strive to have section titles that are not redundant
and grammatically consistent with each other.

middle of long paragraphs. Err on the side of shorter paragraphs.

pound complex structures that require semi-colons).

become too complex or incomplete. However, sometimes such paragraphs are useful for emphasis, summary,
or introductions.
As a corollary, most sections should have multiple paragraphs.

redundant, make sure that the function and use of every example is clearly described.
ReStructured Text and Typesetting
{ [ a,
a, a ] }over{[a,a,a]}.

=for heading level 1 or h1s. Use underlines and overlines for document titles.
-for heading level 2 or h2s.
~for heading level 3 or h3s.
`for heading level 4 or h4s.
-) to indicate items of an ordered list.

Use the footnote format that includes automatic numbering and a target name for ease of use. For instance a
footnote tag may look like:[#note]_with the corresponding directive holding the body of the footnote that
resembles the following:.. [#note].
Donotinclude.. code-block:: [language] in footnotes.
816 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
.. code-block:: [language] form to insert literal blocks into the text.
While the double colon,::, is functional, the.. code-block:: [language] form makes the source
easier to read and understand.

reference types to ensure uniform formatting and cross-referencing.
13.5. Contribute to the Documentation 817

MongoDB Documentation, Release 2.6.4
818 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
Jargon and Common Terms
Pre-
ferred
Term
Concept Dispreferred
Alternatives
Notes
docu-
ment
A single, top-level object/record
in a MongoDB collection.
record, object,
row
Prefer document over object because of
concerns about cross-driver language handling
of objects. Reserve record for allocation of
storage. Avoid row, as possible.
databaseA group of collections. Refers to
a group of data les. This is the
logical sense of the term
database.
Avoid genericizing database. Avoid using
database to refer to a server process or a data
set. This applies both to the datastoring
contexts as well as other (related) operational
contexts (command context,
authentication/authorization context.)
in-
stance
A daemon process. (e.g.mongos
ormongod)
process
(acceptable
sometimes), node
(never
acceptable),
server.
Avoid using instance, unless it modies
something specically. Having a descriptor for
a process/instance makes it possible to avoid
needing to make mongod or mongos plural.
Server and node are both vague and
contextually difcult to disambiguate with
regards to application servers, and underlying
hardware.
eld
name
The identier of a value in a
document.
key, column Avoid introducing unrelated terms for a single
eld. In the documentation we've rarely had to
discuss the identier of a eld, so the extra
word here isn't burdensome.
eld/valueThe name/value pair that
describes a unit of data in
MongoDB.
key, slot, attributeUse to emphasize the difference between the
name of a eld and its value For example,
_id is the eld and the default value is an
ObjectId.
valueThe data content of a eld.data
Mon-
goDB
A group of processes, or
deployment that implement the
MongoDB interface.
mongo,
mongodb, cluster
Stylistic preference, mostly. In some cases it's
useful to be able to refer generically to
instances (that may be eithermongodor
mongos.)
sub-
document
An embedded or nested
document within a document or
an array.
embedded
document, nested
document
map-
reduce
An operation performed by the
mapReduce command.
mapReduce, map
reduce,
map/reduce
Avoid confusion with the command, shell
helper, and driver interfaces. Makes it possible
to discuss the operation generally.
clus-
ter
A sharded cluster. grid, shard
cluster, set,
deployment
Cluster is a great word for a group of
processes; however, it's important to avoid
letting the term become generic. Do not use for
any group of MongoDB processes or
deployments.
sharded
clus-
ter
Asharded cluster. shard cluster,
cluster, sharded
system
replica
set
A deployment of replicating
mongodprograms that provide
redundancy and automatic
failover.
set, replication
deployment
de-
ploy-
ment
A group of MongoDB processes,
or a standalonemongod
instance.
cluster, systemTypically in the form MongoDB deployment.
Includes standalones, replica sets and sharded
clusters.
data
set
The collection of physical
databases provided by a
MongoDB deployment.
database, dataImportant to keep the distinction between the
data provided by a mongod or a sharded cluster
as distinct from each database (i.e. a logical
database that refers to a group of collections
stored in a single series of data les.)
pri-
mary
The only member of a replica set
that can accept writes.
master Avoid primary member construction.
sec-
ondary
Read-only members of a replica
set that apply operations from the
primary's oplog.
slave Accept secondary member as needed.
pri-
mary
shard
The shard in a cluster that's
primary for a database.
primary Avoid ambiguity with primary in the context of
replica sets.
range
based
shard-
ing
Refers to sharding based on
regular shard keys where the
range is the value of the eld(s)
selected as the shard key.
hash
based
shard-
ing
Refers to sharding based on
hashed shard keys where the
range is the hashed value of the
eld selected as the shard key.
Even though hashed sharding is based on
ranges of hashes, the sequence of hashes aren't
meaningful to users, and the range-based
aspect of hashed shard keys is an
implementation detail.
shard-
ing
Describes the practice of
horizontal scaling or partitioning
as implemented in sharded
clusters.
partitioning,
horizontal scaling
Only use the terms partitioning and
horizontal scaling to describe what sharding
does, and its operation. Don't refer to sharding
as the partitioning system.
meta-
data
data about data meta-data, meta
data
13.5. Contribute to the Documentation 819

MongoDB Documentation, Release 2.6.4
Database Systems and Processes

mongodormongos. Refer to these as processes
or instances. Reserve database for referring to a database structure, i.e., the structure that holds collections
and refers to a group of les on disk.
Distributed System Terms

clusters or other variants.
Data Structure Terms

ments.
Do not refer to documents as objects, because drivers (and MongoDB) do not preserve the order of elds when
fetching data. If the order of objects matter, use an array.

Other Terms
example.net(and.orgor.comif needed) for all examples and samples.

Notes on Specic Features

1. is capableof storing coordinates in sub-documents, in practice, users should only store
coordinates in arrays. (See:
35
.)
MongoDB Documentation Practices and Processes
This document provides an overview of the practices and processes.
Commits
When relevant, include a Jira case identier in a commit message. Reference documentation cases when applicable,
but feel free to reference other cases from
36
.
Err on the side of creating a larger number of discrete commits rather than bundling large set of changes into one
commit.
35
https://jira.mongodb.org/browse/DOCS-41
36
http://jira.mongodb.org/
820 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
For the sake of consistency, remove trailing whitespaces in the source le.
Hard wrap les to between 72 and 80 characters per-line.
Standards and Practices

reviewers should have signicant technical experience with the material covered in the documentation.

into the publication branches.
Collaboration
To propose a change to the documentation, do either of the following:

37
proposing the change. Someone on the documentation team will
make the change and be in contact with you so that you can review the change.

38
, fork the
39
, commit your changes, and issue a pull request. Someone
on the documentation team will review and incorporate your change into the documentation.
Builds
Building the documentation is useful because
40
and docutils can catch numerous errors in the format and
syntax of the documentation. Additionally, having access to an example documentation as itwillappear to the users
is useful for providing more effective basis for the review process. Besides Sphinx, Pygments, and Python-Docutils,
the documentation repository contains all requirements for building the documentation resource.
Talk to someone on the documentation team if you are having problems running builds yourself.
Publication
The makele for this repository contains targets that automate the publication process. Usemake htmlto publish
a test build of the documentation in thebuild/directory of your repository. Usemake publishto build the full
contents of the manual from the current branch in the../public-docs/directory relative the docs repository.
Other targets include:
man- builds UNIX Manual pages for all Mongodb utilities.
push- builds and deploys the contents of the../public-docs/.
pdfs- builds a PDF version of the manual (requires LaTeX dependencies.)
Branches
This section provides an overview of the git branches in the MongoDB documentation repository and their use.
37
https://jira.mongodb.org/browse/DOCS
38
https://github.com/
39
https://github.com/mongodb/docs
40
http://sphinx.pocoo.org/
13.5. Contribute to the Documentation 821

MongoDB Documentation, Release 2.6.4
At the present time, future work transpires in themaster, with the main publication beingcurrent. As the
documentation stabilizes, the documentation team will begin to maintain branches of the documentation for specic
MongoDB releases.
Migration from Legacy Documentation
The MongoDB.org Wiki contains a wealth of information. As the transition to the Manual (i.e. this project and
resource) continues, it'scriticalthat no information disappears or goes missing. The following process outlineshow
to migrate a wiki page to the manual:
1.
In this process you should follow cross references and gain an understanding of both the underlying information
and how the parts of the new content relates its constituent parts.
2.
wiki page.
3.
In the case of commands and reference material, make sure that documented options are accurate.
4.
The target of the redirect neednotcontain every piece of information on the wiki page,ifthe manual as a
whole does, and relevant section(s) with the information from the wiki page are accessible from the target of the
redirection.
5.
mation in question.
At this point, update the relevant Jira case with the target that you've chosen for the redirect, and make the ticket
unassigned.
6.
else on the team, should make a nal pass at both pages with fresh eyes and then make the redirect.
Steps 1-5 should ensure that no information is lost in the migration, and that the nal review in step 6 should be
trivial to complete.
Review Process
Types of ReviewThe content in the Manual undergoes many types of review, including the following:
Initial Technical ReviewReview by an engineer familiar with MongoDB and the topic area of the documentation.
This review focuses on technical content, and correctness of the procedures and facts presented, but can improve any
aspect of the documentation that may still be lacking. When both the initial technical review and the content review
are complete, the piece may be published.
Content ReviewTextual review by another writer to ensure stylistic consistency with the rest of the manual. De-
pending on the content, this may precede or follow the initial technical review. When both the initial technical review
and the content review are complete, the piece may be published.
822 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
Consistency ReviewThis occurs post-publication and is content focused. The goals of consistency reviews are to
increase the internal consistency of the documentation as a whole. Insert relevant cross-references, update the style as
needed, and provide background fact-checking.
When possible, consistency reviews should be as systematic as possible and we should avoid encouraging stylistic and
information drift by editing only small sections at a time.
Subsequent Technical ReviewIf the documentation needs to be updated following a change in functionality of the
server or following the resolution of a user issue, changes may be signicant enough to warrant additional technical
review. These reviews follow the same form as the initial technical review, but is often less involved and covers a
smaller area.
Review MethodsIf you're not a usual contributor to the documentation and would like to review something, you
can submit reviews in any of the following methods:

you can nd by clicking on the diff button in the upper left portion of the screen. You can also use the
following URL to reach this interface:
https://github.com/mongodb/docs/pull/[pull-request-id]/files
Replace[pull-request-id] with the identier of the pull request. Make all comments inline, using
GitHub's comment system.
You may also provide comments directly on commits, or on the pull request itself but these commit-comments
are archived in less coherent ways and generate less useful emails, while comments on the pull request lead to
less specic changes to the document.

41
project. These are better for more general changes that aren't
necessarily tied to a specic line, or affect multiple les.

with your changes.
If you insert lines that begin with any of the following annotations:
.. TODO:
TODO:
.. TODO
TODO
followed by your comments, it will be easier for the original writer to locate your comments. The two dots..
format is a comment in reStructured Text, which will hide your comments from Sphinx and publication if you're
worried about that.
This format is often easier for reviewers with larger portions of content to review.
MongoDB Manual Organization
This document provides an overview of the global organization of the documentation resource. Refer to the notes
below if you are having trouble understanding the reasoning behind a le's current location, or if you want to add new
documentation but aren't sure how to integrate it into the existing resource.
If you have questions, don't hesitate to open a ticket in the
42
or contact the
team
43
.
41
http://jira.mongodb.org/browse/DOCS
42
https://jira.mongodb.org/browse/DOCS
43
[email protected]
13.5. Contribute to the Documentation 823

MongoDB Documentation, Release 2.6.4
Global Organization
Indexes and Experience The documentation project has two index les:
http://docs.mongodb.org/manualcontents.txt andhttp://docs.mongodb.org/manualindex.txt .
The contents le provides the documentation's tree structure, which Sphinx uses to create the left-pane navigational
structure, to power the Next and Previous page functionality, and to provide all overarching outlines of the
resource. The index le is not included in the contents le (and thus builds will produce a warning here) and is
the page that users rst land on when visiting the resource.
Having separate contents and index les provides a bit more exibility with the organization of the resource while
also making it possible to customize the primary user experience.
Topical OrganizationThe placement of les in the repository depends on thetypeof documentation rather than the
topicof the content. Like the difference betweencontents.txtandindex.txt, by decoupling the organization
of the les from the organization of the information the documentation can be more exible and can more adequately
address changes in the product and in users' needs.
Filesin thesource/directory represent the tip of a logical tree of documents, whiledirectoriesare containers of
types of content. Theadministrationandapplicationsdirectories, however, are legacy artifacts and with a
few exceptions contain sub-navigation pages.
With several exceptions in thereference/directory, there is only one level of sub-directories in thesource/
directory.
Tools
The organization of the site, like all Sphinx sites derives from thetoctree
44
structure. However, in order to annotate
the table of contents and provide additional exibility, the MongoDB documentation generatestoctree
45
structures
using data from YAML les stored in thesource/includes/directory. These les start withref-tocortoc
and generate output in thesource/includes/toc/ directory. Briey this system has the following behavior:
ref-tocrefer to the documentation of API objects (i.e. commands, operators and methods),
and the build system generates les that holdtoctree
46
directives as well as les that holdtablesthat list
objects and a brief description.
tocrefer to all other documentation and the build system generates les that hold
toctree
47
directives as well as les that holddenition liststhat contain links to the documents and short
descriptions the content.
specfollowingtocorref-tocwill generate aggregated tables or denition lists and
allow ad-hoc combinations of documents for landing pages and quick reference guides.
MongoDB Documentation Build System
This document contains more direct instructions for building the MongoDB documentation.
Getting Started
Install DependenciesThe MongoDB Documentation project depends on the following tools:
44
http://sphinx-doc.org/markup/toctree.html#directive-toctree
45
http://sphinx-doc.org/markup/toctree.html#directive-toctree
46
http://sphinx-doc.org/markup/toctree.html#directive-toctree
47
http://sphinx-doc.org/markup/toctree.html#directive-toctree
824 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4

OS XInstall Sphinx, Docutils, and their dependencies witheasy_installthe following command:
easy_install Sphinx Jinja2 Pygments docutils PyYAML droopy fabric
Feel free to usepiprather thaneasy_installto install python packages.
To generate the images used in the documentation,
48
.
Optional
To generate PDFs for the full production build, install a TeX distribution (for building the PDF.) If you do not have a
LaTeX installation, use
49
. This isonlyrequired to build PDFs.
Arch LinuxInstall packages from the system repositories with the following command:
pacman -S python2-sphinx python2-yaml inkscape python2-pip
Then install the following Python packages:
pip install droopy fabric
Optional
To generate PDFs for the full production build, install the following packages from the system repository:
pacman -S texlive-bin texlive-core texlive-latexextra
Debian/UbuntuInstall the required system packages with the following command:
apt-get install python-sphinx python-yaml python-argparse inkscape python-pip
Then install the following Python packages:
48
http://inkscape.org/download/
49
http://www.tug.org/mactex/2011/
13.5. Contribute to the Documentation 825

MongoDB Documentation, Release 2.6.4
pip install droopy fabric
Optional
To generate PDFs for the full production build, install the following packages from the system repository:
apt-get install texlive-latex-recommended texlive-latex-recommended
Setup and CongurationClone the repository:
git clone git://github.com/mongodb/docs.git
Then run thebootstrap.pyscript in thedocs/repository, to congure the build dependencies:
python bootstrap.py
This downloads and congures the
50
repository, which contains the authoritative build system
shared between branches of the MongoDB Manual and other MongoDB documentation projects.
You can runbootstrap.pyregularly to update build system.
Building the Documentation
The MongoDB documentation build system is entirely accessible viamaketargets. For example, to build an HTML
version of the documentation issue the following command:
make html
You can nd the build output inbuild/<branch>/html, where<branch>is the name of the current branch.
In addition to thehtmltarget, the build system provides the following targets:
publishBuilds and integrates all output for the production build. Build output is in
build/public/<branch>/ . When you runpublishin themaster, the build will generate
some output inbuild/public/.
push;stageUploads the production build to the production or staging web servers. Depends onpublish. Re-
quires access production or staging environment.
push-all;stage-allUploads the entire content ofbuild/public/to the web servers. Depends on
publish. Not used in common practice.
push-with-delete;stage-with-delete Modies the action ofpushandstageto remove remote le
that don't exist in the local build. Use with caution.
html;latex;dirhtml;epub;texinfo;man;jsonThese are standard targets derived from the default
Sphinx Makele, with adjusted dependencies. Additionally, for all of these targets you can append-nitpick
to increase Sphinx's verbosity, or-cleanto remove all Sphinx build artifacts.
latexperforms several additional post-processing steps on.texoutput generated by Sphinx. This target will
also compile PDFs usingpdflatex.
htmlandmanalso generates a.tar.gzle of the build outputs for inclusion in the nal releases.
50
http://github.com/mongodb/docs-tools/
826 Chapter 13. About MongoDB Documentation

MongoDB Documentation, Release 2.6.4
Build Mechanics and Tools
Internally the build system has a number of components and processes. See the
51
for more
information on the internals. This section documents a few of these components from a very high level and lists useful
operations for contributors to the documentation.
FabricFabric is an orchestration and scripting package for Python. The documentation uses Fabric to handle the
deployment of the build products to the web servers and also unies a number of independent build operations. Fabric
commands have the following form:
fab <module>.<task>[:<argument>]
The<argument>is optional in most cases. Additionally some tasks are available at the root level, without a module.
To see a full list of fabric tasks, use the following command:
fab -l
You can chain fabric tasks on a single command line, although this doesn't always make sense.
Important fabric tasks include:
tools.bootstrap Runs thebootstrap.pyscript. Useful for re-initializing the repository without needing to
be in root of the repository.
tools.dev;tools.resettools.devswitches theoriginremote of thedocs-toolscheckout inbuild
directory, to../docs-toolsto facilitate build system testing and development.tools.resetresets the
originremote for normal operation.
tools.conftools.confreturns the content of the conguration object for the current project. These data are
useful during development.
stats.report:<filename> Returns, a collection of readability statistics. Specify le names relative to
source/tree.
makeProvides a thin wrapper around Make calls. Allows you to start make builds from different locations in the
project repository.
process.refresh_dependencies Updates the time stamp of.txtsource les with changed include les, to
facilitate Sphinx's incremental rebuild process. This task runs internally as part of the build process.
BuildclothBuildcloth
52
is a meta-build tool, used to generate Makeles programmatically. This makes the build
system easier to maintain, and makes it easier to use the same fundamental code to generate various branches of the
Manual as well as related documentation projects. See
53
for the relevant code.
Runningmakewith no arguments will regenerate these parts of the build system automatically.
RstclothRstcloth
54
is a library for generating reStructuredText programmatically. This makes it possible to generate
content for the documentation, such as tables, tables of contents, and API reference material programmatically and
transparently. See
55
for the relevant code.
If you have any questions, please feel free to open a
56
.
51
https://github.com/mongodb/docs-tools/blob/master/README.rst
52
https://pypi.python.org/pypi/buildcloth/
53
https://github.com/mongodb/docs-tools/tree/master/makecloth
54
https://pypi.python.org/pypi/rstcloth
55
https://github.com/mongodb/docs-tools/tree/master/rstcloth
56
https://jira.mongodb.org/browse/DOCS
13.5. Contribute to the Documentation 827

MongoDB Documentation, Release 2.6.4
828 Chapter 13. About MongoDB Documentation

Index
Symbols
__system (user role),
_id,
_id index,
<database>.system.indexes (MongoDB reporting output),
271
<database>.system.js (MongoDB reporting output),
<database>.system.namespaces (MongoDB reporting
output),
<database>.system.prole (MongoDB reporting output),
271
0 (error code),
100 (error code),
12 (error code),
14 (error code),
2 (error code),
20 (error code),
3 (error code),
4 (error code),
45 (error code),
47 (error code),
48 (error code),
49 (error code),
5 (error code),
A
addShard (user action),
admin.system.roles (MongoDB reporting output),
admin.system.roles.db (MongoDB reporting output),
admin.system.roles.privileges (MongoDB reporting out-
put),
admin.system.roles.privileges[n].actions (MongoDB re-
porting output),
admin.system.roles.privileges[n].resource (MongoDB re-
porting output),
admin.system.roles.role (MongoDB reporting output),
369
admin.system.roles.roles (MongoDB reporting output),
370
admin.system.roles.roles[n].db (MongoDB reporting out-
put),
admin.system.roles.roles[n].role (MongoDB reporting
output),
admin.system.users (MongoDB reporting output),
admin.system.users.credentials (MongoDB reporting out-
put),
admin.system.users.customData (MongoDB reporting
output),
admin.system.users.db (MongoDB reporting output),
admin.system.users.roles (MongoDB reporting output),
372
admin.system.users.roles[n].db (MongoDB reporting out-
put),
admin.system.users.roles[n].role (MongoDB reporting
output),
admin.system.users.user (MongoDB reporting output),
372
admin.system.version (MongoDB reporting output),
administration tutorials,
anyAction (user action),
appendOplogNote (user action),
applicationMessage (user action),
ARBITER (replica set state),
authSchemaUpgrade (user action),
B
backup (user role),
balancing,
congure,
internals,
migration,
operations,
secondary throttle,
C
changeCustomData (user action),
changeOwnCustomData (user action),
changeOwnPassword (user action),
changePassword (user action),
829

MongoDB Documentation, Release 2.6.4
chunks._id (MongoDB reporting output),
chunks.data (MongoDB reporting output),
chunks.les_id (MongoDB reporting output),
chunks.n (MongoDB reporting output),
cleanupOrphaned (user action),
closeAllDatabases (user action),
clusterAdmin (user role),
clusterManager (user role),
clusterMonitor (user role),
collection
system,
collMod (user action),
collStats (user action),
compact (user action),
compound index,
cong,
cong (MongoDB reporting output),
cong databases,
cong servers,
cong.changelog (MongoDB reporting output),
cong.changelog._id (MongoDB reporting output),
cong.changelog.clientAddr (MongoDB reporting out-
put),
cong.changelog.details (MongoDB reporting output),
681
cong.changelog.ns (MongoDB reporting output),
cong.changelog.server (MongoDB reporting output),
681
cong.changelog.time (MongoDB reporting output),
cong.changelog.what (MongoDB reporting output),
cong.chunks (MongoDB reporting output),
cong.collections (MongoDB reporting output),
cong.databases (MongoDB reporting output),
cong.lockpings (MongoDB reporting output),
cong.locks (MongoDB reporting output),
cong.mongos (MongoDB reporting output),
cong.settings (MongoDB reporting output),
cong.shards (MongoDB reporting output),
cong.tags (MongoDB reporting output),
cong.version (MongoDB reporting output),
connection pooling
read operations,
connPoolStats (user action),
connPoolSync (user action),
consistency
rollbacks,
convertToCapped (user action),
cpuProler (user action),
createCollection (user action),
createIndex (user action),
createRole (user action),
createUser (user action),
crud
write operations,
CURRENT (system variable available in aggregation),
429
cursorInfo (user action),
D
database,
local,
database references,
dbAdmin (user role),
dbAdminAnyDatabase (user role),
dbHash (user action),
dbOwner (user role),
DBRef,
dbStats (user action),
DESCEND (system variable available in aggregation),
429
development tutorials,
diagLogging (user action),
DOWN (replica set state),
dropCollection (user action),
dropDatabase (user action),
dropIndex (user action),
dropRole (user action),
dropUser (user action),
E
EDITOR,
emptycapped (user action),
enableProler (user action),
enableSharding (user action),
environment variable
EDITOR,
HOME,
F
failover
replica set,
FATAL (replica set state),
les._id (MongoDB reporting output),
les.aliases (MongoDB reporting output),
les.chunkSize (MongoDB reporting output),
les.contentType (MongoDB reporting output),
les.lename (MongoDB reporting output),
les.length (MongoDB reporting output),
les.md5 (MongoDB reporting output),
les.metadata (MongoDB reporting output),
les.uploadDate (MongoDB reporting output),
nd (user action),
ushRouterCong (user action),
fsync (user action),
fundamentals
sharding,
830 Index

MongoDB Documentation, Release 2.6.4
G
geospatial queries,
exact,
getCmdLineOpts (user action),
getLog (user action),
getParameter (user action),
getShardMap (user action),
getShardVersion (user action),
grantRole (user action),
GridFS,,
chunks collection,
collections,
les collection,
index,
initialize,
H
HOME,
hostInfo (user action),
hostManager (user role),
I
index
_id,
background creation,
compound,,
create,,
create in background,
drop duplicates,,
duplicates,,
embedded elds,
hashed,,
list indexes,
measure use,
monitor index building,
multikey,
name,
options,
overview,
rebuild,
remove,
replica set,
sort order,
sparse,,
subdocuments,
TTL index,
unique,,
index types,
primary key,
indexStats (user action),
inprog (user action),
insert (user action),
installation,
installation guides,
installation tutorials,
internal (user action),
internals
cong database,
invalidateUserCache (user action),
K
KEEP (system variable available in aggregation),
killCursors (user action),
killop (user action),
L
listDatabases (user action),
listShards (user action),
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),
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),
600
local.startup_log.cmdLine (MongoDB reporting output),
599
local.startup_log.hostname (MongoDB reporting output),
599
local.startup_log.pid (MongoDB reporting output),
local.startup_log.startTime (MongoDB reporting output),
599
local.startup_log.startTimeLocal (MongoDB reporting
output),
local.system.replset (MongoDB reporting output),
local.system.replset._id (MongoDB reporting output),
594
local.system.replset.members (MongoDB reporting out-
put),
local.system.replset.members[n]._id (MongoDB report-
ing output),
local.system.replset.members[n].arbiterOnly (MongoDB
reporting output),
local.system.replset.members[n].buildIndexes (Mon-
goDB reporting output),
local.system.replset.members[n].hidden (MongoDB re-
porting output),
local.system.replset.members[n].host (MongoDB report-
ing output),
local.system.replset.members[n].priority (MongoDB re-
porting output),
local.system.replset.members[n].slaveDelay (MongoDB
reporting output),
Index 831

MongoDB Documentation, Release 2.6.4
local.system.replset.members[n].tags (MongoDB report-
ing output),
local.system.replset.members[n].votes (MongoDB
reporting output),
local.system.replset.settings (MongoDB reporting out-
put),
local.system.replset.settings.chainingAllowed (Mon-
goDB reporting output),
local.system.replset.settings.getLastErrorDefaults (Mon-
goDB reporting output),
local.system.replset.settings.getLastErrorModes (Mon-
goDB reporting output),
local.system.replset.settings.heartbeatTimeoutSecs
(MongoDB reporting output),
local.system.replset.version (MongoDB reporting out-
put),
logRotate (user action),
M
mongos,,
mongos load balancer,
moveChunk (user action),
N
namespace
local,
system,
nearest (read preference mode),
netstat (user action),
P
planCacheRead (user action),
planCacheWrite (user action),
primary (read preference mode),
PRIMARY (replica set state),
primaryPreferred (read preference mode),
PRUNE (system variable available in aggregation),
Q
query optimizer,
R
read (user role),
read operation
architecture,
connection pooling,
read operations
query,
read preference,
background,
behavior,
member selection,
modes,
mongos,
nearest,
ping time,
semantics,
sharding,
tag sets,,
readAnyDatabase (user role),
readWrite (user role),
readWriteAnyDatabase (user role),
RECOVERING (replica set state),
references,
reIndex (user action),
remove (user action),
REMOVED (replica set state),
removeShard (user action),
renameCollectionSameDB (user action),
repairDatabase (user action),
replica set
elections,
failover,,
index,
local database,
network partitions,
reconguration,
resync,
rollbacks,
sync,,
tag sets,
replica set members
arbiters,
delayed,
hidden,
non-voting,
replSetCongure (user action),
replSetGetStatus (user action),
replSetHeartbeat (user action),
replSetStateChange (user action),
restore (user role),
resync (user action),
revokeRole (user action),
ROLLBACK (replica set state),
rollbacks,
ROOT (system variable available in aggregation),
root (user role),
S
secondary (read preference mode),
SECONDARY (replica set state),
secondary throttle,
secondaryPreferred (read preference mode),
serverStatus (user action),
setParameter (user action),
shard key,
cardinality,
832 Index

MongoDB Documentation, Release 2.6.4
query isolation,
write scaling,
sharded clusters,
sharding
chunk size,
cong database,
cong servers,
localhost,
shard key,
shard key indexes,
shards,
shardingState (user action),
shards,
shutdown (user action),
slaveOk,
splitChunk (user action),
splitVector (user action),
STARTUP (replica set state),
STARTUP2 (replica set state),
storageDetails (user action),
system
collections,
namespace,
system.prole.client (MongoDB reporting output),
system.prole.command (MongoDB reporting output),
273
system.prole.cursorid (MongoDB reporting output),
system.prole.keyUpdates (MongoDB reporting output),
273
system.prole.lockStats (MongoDB reporting output),
274
system.prole.lockStats.timeAcquiringMicros (Mon-
goDB reporting output),
system.prole.lockStats.timeLockedMicros (MongoDB
reporting output),
system.prole.millis (MongoDB reporting output),
system.prole.moved (MongoDB reporting output),
system.prole.nmoved (MongoDB reporting output),
system.prole.nreturned (MongoDB reporting output),
274
system.prole.ns (MongoDB reporting output),
system.prole.nscanned (MongoDB reporting output),
273
system.prole.ntoreturn (MongoDB reporting output),
273
system.prole.ntoskip (MongoDB reporting output),
system.prole.numYield (MongoDB reporting output),
274
system.prole.nupdated (MongoDB reporting output),
273
system.prole.op (MongoDB reporting output),
system.prole.query (MongoDB reporting output),
system.prole.responseLength (MongoDB reporting out-
put),
system.prole.scanAndOrder (MongoDB reporting out-
put),
system.prole.ts (MongoDB reporting output),
system.prole.updateobj (MongoDB reporting output),
273
system.prole.user (MongoDB reporting output),
T
tag sets,
conguration,
text search tutorials,
top (user action),
touch (user action),
TTL index,
tutorials,
administration,
development patterns,
installation,
text search,
U
UNKNOWN (replica set state),
unlock (user action),
update (user action),
userAdmin (user role),
userAdminAnyDatabase (user role),
V
validate (user action),
viewRole (user action),
viewUser (user action),
W
write concern,
write operations,
Index 833

About This Presentation

Slide Content

Tags

Categories

Download

Quick Actions

Statistics

Related Slideshows

Mongo db manual

About This Presentation

Slide Content

Slide 1

Slide 2

Slide 3

Slide 4

Slide 5

Slide 6

Slide 7

Slide 8

Slide 9

Slide 10

Slide 11

Slide 12

Slide 13

Slide 14

Slide 15

Slide 16

Slide 17

Slide 18

Slide 19

Slide 20

Slide 21

Slide 22

Slide 23

Slide 24

Slide 25

Slide 26

Slide 27

Slide 28

Slide 29

Slide 30

Slide 31

Slide 32

Slide 33

Slide 34

Slide 35

Slide 36

Slide 37

Slide 38

Slide 39

Slide 40

Slide 41

Slide 42

Slide 43

Slide 44

Slide 45

Slide 46

Slide 47

Slide 48

Slide 49

Slide 50

Slide 51

Slide 52

Slide 53

Slide 54

Slide 55

Slide 56

Slide 57

Slide 58

Slide 59

Slide 60

Slide 61

Slide 62

Slide 63

Slide 64

Slide 65

Slide 66

Slide 67

Slide 68

Slide 69

Slide 70

Slide 71

Slide 72

Slide 73

Slide 74

Slide 75

Slide 76

Slide 77