DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
The Latest "Software Integration: The Intersection of APIs, Microservices, and Cloud-Based Systems" Trend Report
Get the report
  1. DZone
  2. Refcards
  3. MongoDB
refcard cover
Refcard #171

MongoDB

Flexible NoSQL for Humongous Data

Covers configuration options, shell functions, types of cursors, sharding and more.

Free PDF for Easy Reference
refcard cover

Written By

author avatar Vlad Mihalcea
CEO of Hypersistence, vladmihalcea.com
Table of Contents
► Configuration Options ► Using the Shell ► Diagnosing What’s Happening ► Types of Cursors ► Hinting ► System Profiling ► Replica Sets ► Sharding ► Mongo Monitoring Service (MMS) ► Quick Rules ► Query Operators ► Update Modifiers ► Aggregation Pipeline Operators ► Making Backups ► Replica Set Maintenance ► Demoting a Member ► User Management ► MongoDB Restrictions ► Additional Resources
Section 1

Configuration Options

Setting Options

Startup options for MongoDB can be set on the command line or in a configuration file. The syntax is slightly different between the two. Here are the three types of options:

Command-Line Config File
--dbpath /path/to/db dbpath=/path/to/db
--auth auth=true
-vvv vvv=true

Run mongod --help for a full list of options. Here are some of the most useful:

Option Description
--config /path/to/config Specifies config file where other options are set.
--dbpath /path/to/data Path to data directory.
--logpath /path/to/file.log Where the log is stored. This is a path to the exact file, not a directory.
--logappend On restart, appends to (does not truncate) the existing log file. Always use this when using the --logpath option.
--fork Forks the mongod as a daemon process.
--auth Enables authentication on a single server.
--keyFile /path/to/key.txt Enables authentication on replica sets and sharding. Takes a path to a shared secret key
--nohttpinterface Turns off HTTP interface.
--bind_ip address Only allows connections from the specified network interface.

Seeing Options

If you started mongod with a bunch of options six months ago, how can you see which options you used? The shell has a helper:


> db.serverCmdLineOpts()
{ “argv” : [ “./mongod”, “--port”, “30000” ], “parsed” : { }, “ok” : 1 }

The parsed field is a list of arguments read from a config file

Section 2

Using the Shell

Shell Help

There are a number of functions that give you a little help if you forget a command:


> // basic help
> help
        db.help()                    help on db methods
        db.mycoll.help()             help on collection methods
        sh.help()                    sharding helpers
        rs.help()                    replica set helpers
        help admin                   administrative help
        help connect                 connecting to a db help
        ...

Note that there are separate help functions for databases, collections, replica sets, sharding, administration, and more. Although not listed explicitly, there is also help for cursors:


> // list common cursor functions
> db.foo.find().help()

You can use these functions and helpers as built-in cheat sheets.

Seeing Function Definitions

If you don’t understand what a function is doing, you can run it without the parentheses in the shell to see its source code:


> // run the function
> db.serverCmdLineOpts()
{ “argv” : [ “./mongod” ], “parsed” : { }, “ok” : 1 }
> // see its source
> db.serverCmdLineOpts

This can be helpful for seeing what arguments it expects or what errors it can throw, as well as how to run it from another language.

Using edit

The shell has limited multi-line support, so it can be difficult to program in. The shell helper edit makes this easier, opening up a text editor and allowing you to edit variables from there. For example:


  <xmp>
> x = function() { /* some function we’re going to fill in */ }
>    edit x
<opens emacs with the contents of x>
</xmp>

Modify the variable in your editor, then save and exit. The variable will be set in the shell.

Either the EDITOR environment variable or a MongoDB shell variable EDITOR must be set to use edit. You can set it in the MongoDB shell as follows:


  <xmp$gt;
> EDITOR=”/user/bin/emacs”
</xmp>

edit is not available from JavaScript scripts, only in the interactive shell.

.mongorc.js

If a .mongorc.js file exists in your home directory, it will automatically be run on shell startup. Use it to initialize any helper functions you use regularly and remove functions you don’t want to accidentally use.

For example, if you would prefer to not have dropDatabase() available by default, you could add the following lines to your .mongorc.js file:


  <xmp>
DB.prototype.dropDatabase = function() {
    print(“No dropping DBs!”);
}
db.dropDatabase = DB.prototype.dropDatabase;
</xmp>

The example above will change the dropDatabase() helper to only print a message, and not to drop databases.

Note that this technique should not be used for security because a determined user can still drop a database without the helper. However, removing dangerous admin commands can help prevent fat-fingering.

A couple of suggestions for helpers you may want to remove from .mongorc.js are:

  • DB.prototype.shutdownServer
  • DBCollection.prototype.drop
  • DBCollection.prototype.ensureIndex
  • DBCollection.prototype.reIndex
  • DBCollection.prototype.dropIndexes

Changing the Prompt

The shell prompt can be customized by setting the prompt variable to a function that returns a string:


  <xmp>
prompt = function() { 
    try {
        db.getLastError();
    }
    catch (e) {
        print(e);
    }
    return (new Date())+”$ “;
}
</xmp>

If you set prompt, it will be executed each time the prompt is drawn (thus, the example above would give you the time the last operation completed).

Try to include the db.getLastError() function call in your prompt. This is included in the default prompt and takes care of server reconnection and returning errors from writes.

Also, always put any code that could throw an exception in a try/catch block. It’s annoying to have your prompt turn into an exception!

Section 3

Diagnosing What’s Happening

Viewing and Killing Operations

You can see current operations with the currentOp function:


  <xmp>
> db.currentOp()
{
    “inprog” : [
        {
            “opid” : 123,
            “active” : false,
            “locktype” : “write”,
            “waitingForLock” : false,
            “secs_running” : 200,
            “op” : “query”,
            “ns” : “foo.bar”,
            “query” : {
            }
            ...
        },
        ...
    ]
}
</xmp>

Using the opid field from above, you can kill operations:


  <xmp>
> db.killOp(123)
</xmp>

Not all operations can be killed or will be killed immediately. In general, operations that are waiting for a lock cannot be killed until they acquire the lock.

Index Usage

Use explain() to see which index MongoDB is using for a query.


  <xmp>
> db.foo.find(criteria).explain()
{
        “cursor” : “BasicCursor”,
        “isMultiKey” : false,
        “n” : 2,
        “nscannedObjects” : 2,
        “nscanned” : 2,
        “nscannedObjectsAllPlans” : 2,
        “nscannedAllPlans” : 2,
        “scanAndOrder” : false,
        “indexOnly” : false,
        “nYields” : 0,
        “nChunkSkips” : 0,
        “millis” : 0,
        “indexBounds” : {

        },
        “server” : “ubuntu:27017”
}
</xmp>

There are several important fields in the output of explain():

  • n: the number of results returned.
  • nscanned: the number of index entries read.
  • nscannedObjects: the number of docs referred by the index.
  • indexOnly: if the query never had to touch the collection itself.
  • nYields: the number of times this query has released the read lock and waited for other operations to go.
  • indexBounds: when an index is used, this shows the index scan ranges.
Section 4

Types of Cursors

A BasicCursor means that no index was used. A BtreeCursor means a normal index was used. Parallel cursors are used by sharding and geospatial indexes use their own special cursors.

Section 5

Hinting

Use hint() to force a particular index to be used for a query:


  <xmp>
> db.foo.find().hint({x:1})
</xmp>
Section 6

System Profiling

You can turn on system profiling to see operations currently happening on a database. There is a performance penalty to profiling, but it can help isolate slow queries.


  <xmp>
> db.setProfilingLevel(2) // profile all operations
> db.setProfilingLevel(1) // profile operations that take longer than 100ms
> db.setProfilingLevel(1, 500) // profile operations that take longer than 500ms
> db.setProfilingLevel(0) // turn off profiling
> db.getProfilingLevel(1) // see current profiling setting
</xmp>

Profile entries are stored in a capped collection called system.profile in the database in which profiling was enabled. Profiling can be turned on and off for each database.

Section 7

Replica Sets

To find replication lag, connect to a secondary and run this function:


  <xmp>
> db.printReplicationStatus()
configured oplog size:   2000MB
log length start to end: 23091secs (6.4hrs)
oplog first event time:  Fri Aug 10 2012 04:33:03 GMT+0200 (CEST)
oplog last event time:   Mon Aug 20 2012 10:56:51 GMT+0200 (CEST)
now:                     Mon Aug 20 2012 10:56:51 GMT+0200 (CEST)
</xmp>

To see a member’s view of the entire set, connect to it and run:


  <xmp>
> rs.status()                    
</xmp>

This command will show you what it thinks the state and status of the other members are.

Running rs.status() on a secondary will show you who the secondary is syncing from in the (poorly named) syncingTo field.

Section 8

Sharding

To see your cluster’s metadata (shards, databases, chunks, etc.), run the following function:


  <xmp>
> db.printShardingStatus()
> db.printShardingStatus(true) // show all chunks                     Mon Aug 20 2012 10:56:51 GMT+0200 (CEST)
</xmp>

You can also connect to the mongos and see data about your shards, databases, collections, or chunks by using “use config” and then querying the relevant collections.


  <xmp>
> use config
switched to db config
> show collections
chunks
databases
lockpings
locks
mongos
settings
shards
system.indexes
version
</xmp>

Always connect to a mongos to get sharding information. Never connect directly to a config server. Never directly write to a config server. Always use sharding commands and helpers.

After maintenance, sometimes mongos processes that were not actually performing the maintenance will not have an updated version of the config. Either bouncing these servers or running the flushRouterConfig command is generally a quick fix to this issue.


  <xmp>
> use admin
> db.runCommand({flushRouterConfig:1})
</xmp>

Often this problem will manifest as setShardVersion failed errors.

Don’t worry about setShardVersion errors in the logs, but they should not trickle up to your application (you shouldn’t get the errors from a driver unless the mongos it’s connecting to cannot reach any config servers).

Section 9

Mongo Monitoring Service (MMS)

MMS is a free, easily-setup way to monitor MongoDB. To use it, create an account at http://mms.10gen.com

graph

See http://mms.10gen.com/help for more documentation.

Section 10

Quick Rules

Databases

Database names cannot contain “.”, “$”, or “\0” (the null character). Names can only contain characters that can be used on your filesystem as filenames. Admin, config, and local are reserved database names (you can store your own data in them, but you should never drop them).

Collections

Collection names cannot contain “$” or “\0”. Names prefixed with “system.” are reserved by MongoDB and cannot be dropped (even if you created the collection). Dots are often used for organization in collection names, but they have no semantic importance. A collection named “che.se” has no more relation to a collection named “che” than one named “cheese” does.

Field Names

Field names cannot contain “.” nor “\0”. Fields should only contain “$” when they are database references.

Index Options

background Builds indexes in the background, while other connections can read and write.
unique Every value for this key must be distinct.
sparse Non-existent values are not indexed. Very handy for indexing unique fields that some documents might not have.
expireAfterSeconds Takes a number of seconds and makes this a “time to live” collection.
dropDups When creating unique indexes, drops duplicate values instead of erroring out. Note that this will delete documents with duplicate values!
clustering when creating a clustering secondary index, the document is copied into the index making any query on that index be a range query and therefore fast. (TokuMX distribution only)

Query Format

Queries are generally of the form:


  <xmp>
{key : {$op : value}}
</xmp>

For example:


  <xmp>
{age : {$gte : 18}}
</xmp>

There are three exceptions to this rule: $and, $or, and $nor, which are all top-level:


  <xmp>
{$or : [{age: {$gte : 18}}, {age : {$lt : 18}, parentalConsent:true}}]}
</xmp>

Update Format

Updates are always of the form:


  <xmp>
{key : {$mod : value}}
</xmp>

For example:


  <xmp>
{age : {$inc : 1}}
</xmp>
Section 11

Query Operators

✓:Matches

X:Does not match

Operator Example Query Example Docs
$gt, $gte, $lt, $lte, $ne {numSold : {$lt:3}}

✓{numSold: 1}

X {numSold: “hello”}

X{x : 1}

$in, $nin {age : {$in : [10, 14, 21]}}

✓{age: 21}

✓{age: [9, 10, 11]}

X{age: 9}

$all {hand : {$all : [“10”,”J”,”Q”,”K”,”A”]}}

✓{hand: [“7”, “8”, “9”, “10”, “J”, “Q”, “K”, “A”]}

X{hand:[“J”,”Q”,”K”]}

$not {name : {$not : /jon/i}}

✓{name: "Jon"}

X {name: "John"}

$mod {age : {$mod : [10, 0]}}

✓ {age: 50}

X {age: 42}

$exists {phone: {$exists: true}}

✓ {phone: "555-555-5555"}

X {phones: ["555-555-5555", "1-800-555-5555"]}

$type* {age : {$type : 2}}

✓ {age : "42"}

X {age : 42}

$size {"top-three":{$size:3}}

✓ {"top-three":["gold","silver","bronze"]}

X {"top-three":["blue ribbon"]}

$regex {role: /admin.*/i} {role: {$regex:’admin.*’, $options: ‘i’ }} ✓ {"top-three":["gold","silver","bronze"]} X {"top-three":["blue ribbon"]}
Section 12

Update Modifiers

Modifier Start Doc Example Mod End Doc
$set {x:"foo"} {$set:{x:[1,2,3]}} {x:[1,2,3]}
$unset {x:"foo"} {$unset:{x:true}} {}
$inc {countdown:5} {$inc:{countdown:-1}} {countdown:4}
$push, $pushAll {votes:[-1,-1,1]} {$push:{votes:-1}} {votes:[-1,-1,1,-1}}
$pull, $pullAll {blacklist:["ip1","ip2","ip3"]} {$pull:{blacklist:"ip2"}} {blacklist:"ip1","ip3"}
$pop {queue:["1pm","3pm","8pm"]} {$pop:{queue:-1}} {queue:["3pm","8pm"]}
$addToSet, $each {ints:[0,1,3,4]} {$addToSet:{ints:{$each:[1,2,3]}}} {ints:[0,1,2,3,4]}
$rename {nmae:"sam"} {$rename:{nmae:"name"}} {name:"sam"}
$bit {permission:6} {$bit:{permissions:{or:1}}} {permission:7}
Section 13

Aggregation Pipeline Operators

The aggregation framework can be used to perform everything from simple queries to complex aggregations.

To use the aggregation framework, pass the aggregate() function a pipeline of aggregation stages:


  <xmp>
> db.collection.aggregate({$match:{x:1}}, 
... {$limit:10}, 
... {$group:{_id : “$age”}})
</xmp>

A list of available stages:

Operator Description
{$project : projection} Includes, exclude,s renames, and munges fields.
{$match : match} Queries, takes an argument identical to that passed to find().
{$limit : num} Limits results to num.
{$skip : skip} Skips num results.
{$sort : sort} Sorts results by the given fields.
{$group : group} Groups results using the expressions given (see table below).
{$unwind : field} Explodes an embedded array into its own top-level documents.

To refer to a field, use the syntax $fieldName. For example, this projection would return the existing “time” field with a new name, “time since epoch”:


  <xmp>
{$project: {“time since epoch”: “$time”}}
</xmp>

$project and $group can both take expressions, which can use this $fieldName syntax as shown below

Expression Op Example Description
$add : ["$age", 1] Adds 1 to the age field.
$divide : ["$sum", "$count"] Divides the sum field by count.
$mod : ["$sum", "$count"] The remainder of dividing sum by count.
$multiply : ["$mph", 24, 365] Multiplies mph by 24*365.
$subtract : ["$price", "$discount"] Subtracts discount from price.
$strcasecmp : ["ZZ", "$name"] 1 if name is less than ZZ, 0 if name is ZZ, -1 if name is greater than ZZ.
$substr : ["$phone", 0, 3] Gets the area code (first three characters) of phone.
$toLower : "$str" Converts str to all lowercase.
$toUpper : "$str" Converts str to all uppercase.
$ifNull : ["$mightExist", $add : ["$doesExist", 1]] If mightExist is not null, returns mightExist. Otherwise returns the result of the second expression.
$cond : [exp1, exp2, exp3] If exp1 evalutes to true, return exp2, otherwise return expr3.
Section 14

Making Backups

The best way to make a backup is to make a copy of the database files while they are in a consistent state (i.e., not in the middle of being read from/to).

  1. 1. Use the fsync+lock command. This flushes all in-flight writes to disk and prevents new ones.
    
      <xmp>
    {$project: {“time since epoch”: “$time”}}
    </xmp>


  2. Copy data files to a new location.
  3. Use the unlock command to unlock the database.
    
      <xmp>
    > db.fsyncUnlock()
    </xmp>


To restore from this backup, copy the files to the correct server’s dbpath and start the mongod.

If you have a filesystem that does filesystem snapshots and your journal is on the same volume and you haven’t done anything stripy with RAID, you can take a snapshot without locking. In this case, when you restore, the journal will replay operations to make the data files consistent.

Mongodump is only for backup in special cases. If you decide to use it anyway, don’t fsync+lock first.

Section 15

Replica Set Maintenance

Keeping Members from Being Elected

To permanently stop a member from being elected, change its priority to 0:


  <xmp>
> var config = rs.config()
> config.members[2].priority = 0
> rs.reconfig(config)
</xmp>

To prevent a secondary from being elected temporarily, connect to it and issue the freeze command:


  <xmp>
> rs.freeze(10*60) // # of seconds to not become primary
</xmp>

This can be handy if you don’t want to change priorities permanently but need to do maintenance on the primary.

Section 16

Demoting a Member

If a member is currently primary and you don’t want it to be, use stepDown:


  <xmp>
> rs.stepDown(10*60) // # of seconds to not try to become primary again
</xmp>

Starting a Member as a Stand-Alone Server

For maintenance, often it is desirable to start up a secondary and be able to do writes on it (e.g., for building indexes). To accomplish this, you can start up a secondary as a stand-alone mongod temporarily.

If the secondary was originally started with the following arguments:


  <xmp>
$ mongod --dbpath /data/db --replSet setName --port 30000
</xmp>

Shut it down cleanly and restart it with:


  <xmp>
$ mongod --dbpath /data/db --port 30001
</xmp>

Note that the dbpath does not change, but the port does and the replSet option is removed (all other options can remain the same). This mongod will come up as a stand-alone server. The rest of the replica set will be looking for a member on port 30000, not 30001, so it will just appear to be “down” to the rest of the set.

When you are finished with maintenance, restart the server with the original arguments.

Section 17

User Management

Check current user privileges


  <xmp>
> db.runCommand(
...   {
...     usersInfo:”manager”,
...     showPrivileges:true
...   }
... )
</xmp>

Create a superAdmin


  <xmp>
> use sensors
switched to db sensors
> db.createUser(
...   {
...     user: “sensorsUserAdmin”,
...     pwd: “password”,
...     roles:
...     [
...       {
...         role: “userAdmin”,
...         db: “sensors”
...       }
...     ]
...   }
... )
</xmp>

View user roles


  <xmp>
> use sensors
switched to db sensors
> db.getUser(“sensorsUserAdmin”)
{
        “_id” : “sensors.sensorsUserAdmin”,
        “user” : “sensorsUserAdmin”,
        “db” : “sensors”,
        “roles” : [
                {
                        “role” : “userAdmin”,
                        “db” : “sensors”
                }
        ]
}
</xmp>

Show role privileges


  <xmp>
> db.getRole( “userAdmin”, { showPrivileges: true } )
</xmp>

Grant a role


  <xmp>
> db.grantRolesToUser(
...     “sensorsUserAdmin”,
...     [
...       { role: “read”, db: “admin” }
...     ]
... )
</xmp>

Revoke a role


  <xmp>
> db.revokeRolesFromUser(
...     “sensorsUserAdmin”,
...     [
...       { role: “userAdmin”, db: “sensors” }
...     ]
... )
</xmp>
Section 18

MongoDB Restrictions

  1. The maximum document size is 16 megabytes.
  2. Namespaces must be shorter than 123 bytes.
  3. Each namespace file must be no larger than 2047 megabytes.
  4. The index entry total size must be less than 1024 bytes.
  5. A collection can have up to 64 indexes.
  6. The index name (namespace included) cannot be longer than 125 chars.
  7. A replica set can have at most 12 members.
  8. A shard key can have at most 512 bytes.
  9. A shard key is always immutable.
  10. MongoDB non-indexed field sort will return results only if this operation doesn’t use more than 32 megabytes of memory.
  11. Aggregation pipeline stages are limited to 100 megabytes of RAM. When the limit is exceeded, an error is thrown. “allowDiskUse” option allows aggregation pipeline stages to use temporary files for processing.
  12. A bulk operation is limited to 1000 operations.
  13. A database name is case-sensitive and may have up to 64 characters.
  14. Collections names cannot contain: $, null or start with the “system.” prefix.

Field names cannot contain: $, null or . (dot)

Section 19

Additional Resources

  • Download MongoDB at http://www.mongodb.org/downloads
  • Documentation is available at http://docs.mongodb.org
  • See the roadmap and file bugs and request features at http://jira.mongodb.org
  • Ask questions on the mailing list: http://groups.google.com/group/mongodb-user

Like This Refcard? Read More From DZone

related article thumbnail

DZone Article

related refcard thumbnail

Free DZone Refcard

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.linkDescription }}

{{ parent.urlSource.name }}
by
CORE
· {{ parent.articleDate | date:'MMM. dd, yyyy' }} {{ parent.linkDate | date:'MMM. dd, yyyy' }}
Tweet
{{ parent.views }} ViewsClicks
  • Edit
  • Delete
  • {{ parent.isLocked ? 'Enable' : 'Disable' }} comments
  • {{ parent.isLimited ? 'Remove comment limits' : 'Enable moderated comments' }}