MongoDB Shell Guide – Operations and Commands

This article is part of our Academy Course titled MongoDB – A Scalable NoSQL DB.

In this course, you will get introduced to MongoDB. You will learn how to install it and how to operate it via its shell. Moreover, you will learn how to programmatically access it via Java and how to leverage Map Reduce with it. Finally, more advanced concepts like sharding and replication will be explained. Check it out here!

1. Introduction

MongoDB shell is the best tool out there to discover MongoDB features and manage every single aspect of your server deployments, instances, databases, collections and documents. It is based on JavaScript language for executing command and queries. Please do not worry if you have little or no knowledge of JavaScript: you will be able to mostly understand every example effortlessly as there is a common pattern to follow.

With JSON being a format to manage document, it is also used to specify commands and queries as well as to return their results. Such unification brings a lot of benefits because JSON is inherently simple, human-friendly and easy to understand.

In this part of the tutorial our intention is to go through most of the commands and queries supported by MongoDB using its shell except the ones related to sharding (will be covered in details in Part 4. MongoDB Sharding Guide) and replication (will be covered in details in Part 5. MongoDB Replication Guide). More advanced topics will be covered in Part 7. MongoDB Security, Profiling, Indexing, Cursors and Bulk Operations Guide.

Each section is dedicated to particular aspect of MongoDB: we start off from Shell Command Helpers, then look at Databases, Collections and Documents, move to Queries and Aggregations, and finish up with Server specific commands.

MongoDB has many internal and experimental commands and those (in most cases) we will not cover. Their usage is limited to very specific scenarios you may never encounter (or their behavior might be unstable).

Next sections assume that your MongoDB server instance is up and running on local machine as described in Part 1. MongoDB Installation – How to install MongoDB.

2. Shell Command Helpers

MongoDB shell provides a couple of command helpers which allow establishing the context and implicitly populating shell variables, including:

• db: current database context variable
• rs: replica set context variable
• sh: sharding context variable

With no command line arguments provided, MongoDB shell by default connects to local MongoDB server instance on port 27017 and database with name test (which may not physically exist on the disk).

Command	use <database>
Description	Switches current database to <database> and assigns shell variable db to the current database.
Example	In MongoDB shell, let us issue the command: use mydb
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

use <database>

Command	show dbs show databases
Description	Outputs a list of all databases on the server instance.
Example	In MongoDB shell, let us issue the command: show dbs (or show databases)
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

show dbs
show databases

Command	show users
Description	Outputs a list of users for current database with their roles and custom data (if any).
Example	In MongoDB shell, let us issue the command: show users
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

show users

Command	show roles
Description	Outputs a list of all roles, both user-defined and built-in, for the current database.
Example	In MongoDB shell, let us issue the command: show roles Note: Only a fragment of the output is shown.
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

show roles

Command	show logs
Description	Shows the accessible logger names.
Example	In MongoDB shell, let us issue the command: show logs
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

show logs

Command	show log [name]
Description	Outputs the last segment of log in memory. If logger name is omitted the global logger will be used as default.
Example	In MongoDB shell, let us issue the command: show log global

show log [name]

Command	help
Description	Shows quick help on shell commands.
Example	In MongoDB shell, let us issue the command: help
Reference	http://docs.mongodb.org/manual/reference/mongo-shell/#command-helpers

help

With MongoDB shell, there are at least two ways to run commands:

• using the generic db.runCommand() function call
• using the more convenient db.<command> or db.<collection>.<command> wrapper function calls

In most cases the second option is much more readable and that will be the choice for our examples in the following sections. In most cases both options will be demonstrated side by side (if applicable) so you will be able to pick your favorite way to run commands. Please notice that not all commands do have MongoDB shell wrappers and as such, they can be run with db.runCommand() function call only.

Command	version()
Description	Returns the current version of the MongoDB shell instance.
Example	In MongoDB shell, let us issue the command: version()
Reference	http://docs.mongodb.org/manual/reference/method/version/

version()

Command	getHostName() hostname()
Description	Returns the hostname of the system running the MongoDB shell.
Example	In MongoDB shell, let us issue the command: hostname() (or getHostName())
Reference	http://docs.mongodb.org/manual/reference/method/hostname/ http://docs.mongodb.org/manual/reference/method/getHostName/

getHostName()
hostname()

Command	getMemInfo()
Description	Returns a document with two fields that report the amount of memory (in megabytes) used by the JavaScript MongoDB shell: resident: the subset of a memory currently stored in physical RAM virtual: a working memory, typically residing on both disk and in physical RAM
Example	In MongoDB shell, let us issue the command: getMemInfo()
Reference	http://docs.mongodb.org/manual/reference/method/getMemInfo/

getMemInfo()

3. Databases

Database is a top-level data container in MongoDB which holds one or more collections of documents. For every database MongoDB creates physical file (or files) on a disk, aggressively pre-allocating data files to reserve the space and avoid file system fragmentation.

The data file names follow the pattern: the first data file has name <databasename>.0, the next one <databasename>.1 and so on. The size of first pre-allocated file is 64 megabytes, the second one has size 128 megabytes, next one 256 megabytes, and so on, up to maximum size of 2 gigabytes (at this point all subsequent files will be 2 gigabytes in size). One thing to keep in mind, MongoDB will not permanently create a database until the data is inserted into it.

By default, MongoDB also creates the journal files, which store write operations on disk prior to they are being applied to databases.

Command	db.help()
Description	Show help for database methods.
Example	In MongoDB shell, let us issue the command: db.help() Note: Only a fragment of the output is shown.
Reference	http://docs.mongodb.org/manual/reference/method/db.help/#db.help

db.help()

Command	db.commandHelp(<command>)
Description	Displays the help information for particular command <command> with examples of usage and expecting parameters.
Example	In MongoDB shell, let us issue the command: db.commandHelp(‘filemd5’)
Reference	http://docs.mongodb.org/manual/reference/method/db.commandHelp/

db.commandHelp(<command>)

Command	db.getName()
Description	Returns the current database name.
Example	In MongoDB shell, let us issue the command: db.getName()
Reference	http://docs.mongodb.org/manual/reference/method/db.getName/

db.getName

Command	db.getSiblingDB(<database>)
Description	Returns another database without modifying the db variable in the shell environment. It can be used as an alternative to the use <database> helper (see please Shell Command Helpers).
Example	In MongoDB shell, let us issue the command: db.getSiblingDB(‘admin’).getName()
Reference	http://docs.mongodb.org/manual/reference/method/db.getSiblingDB/

db.getSiblingDB(<database>)

Every MongoDB server instance has its own local database, which stores data used in the replication process, and other instance-specific data. The local database is not touched by replication: collections in the local database are never replicated (Part 5. MongoDB Replication Guide talks more about replication). Also, there is an admin database – a privileged database which users must have access to in order to run certain administrative commands.

To run the command in context of admin database, the following options are available:

• 1 2	use admin db.runCommand( <command> )

  Please notice that the current database will be switched to admin.

• 1	db.getSiblingDB( 'admin' ) .runCommand( <command> )

  A bit more verbose chained calls but current database will not be switched and stays unchanged.

• 1	db.adminCommand( <command> )

  A shortcut to db.getSiblingDB( ‘admin’ ) .runCommand( <command> ).

Command	listCommands
Wrapper	db.listCommands()
Description	Displays a list of all database commands with examples of usage and expecting parameters. The commands which require administrative privileges are marked as adminOnly.
Example	In MongoDB shell, let us issue the command: db.listCommands() Alternatively, let us run the same command using runCommand() call: db.runCommand( { listCommands: 1 } )Note: Only a fragment of the output is shown.
Reference	http://docs.mongodb.org/manual/reference/command/listCommands/ http://docs.mongodb.org/manual/reference/method/db.listCommands/

listCommands

Command	listDatabases
Description	This command provides a list of existing databases together with basic statistics about them. It should be run in context of admin database.
Example	In MongoDB shell, let us issue the command: db.getSiblingDB(‘admin’).runCommand( { listDatabases: 1 } )
Reference	http://docs.mongodb.org/manual/reference/command/listDatabases/

listDatabases

Command	clone
Wrapper	db.cloneDatabase( <hostname>[:<port>] )
Description	This command clones a database with the same name as the current database from a remote MongoDB instance running on <hostname> andport <port> to the current host.
Example	Assuming there in another instance of MongoDB server running on port 27018, let us issue the command in the shell: db.cloneDatabase( ‘localhost:27018’ ) Alternatively, let us run the same command using runCommand() call: db.runCommand( { clone: ‘localhost:27018’ } )
Reference	http://docs.mongodb.org/manual/reference/command/clone/ http://docs.mongodb.org/manual/reference/method/db.cloneDatabase/

clone

4. Collections

Collections are the containers of MongoDB documents that share one or more indexes. For the users familiar with RDBMS concepts, a collection is the equivalent of a table. Collection belongs to a single database and do not enforce any schema on containing documents. There is no limit on number of documents any individual collection can contain unless it is a special type of collection called capped collection: a fixed-sized collection that automatically overwrites its oldest entries when it reaches its maximum size.

Together with database name, collections form a namespace: database name concatenated with collection name using period ‘.’ character, for example:

• test.collection1
• test.collection1.subcollection1

Additionally to user-defined collections, MongoDB stores system information in collections that use the <database>.system.* namespace and are reserved for internal use. The admin database (see please Databases section) includes following system collections:

• admin.system.roles
• admin.system.users
• admin.system.version

Each user database has following system collections defined:

• <database>.system.namespaces
• <database>.system.indexes
• <database>.system.profile
• <database>.system.js

In this section we will not explore system collections directly but if you are interested in getting more details, please refer to the official documentation.

5. Documents

In MongoDB the data is represented and stored as a JSON documents: field and value pairs. More precisely, MongoDB uses binary JSON (BSON) to store serialized documents on a disk but for the user it looks like regular JSON (at least, inMongoDB shell). The range of supported filed data types is quite impressive (please refer to BSON data types reference):

• Double
• String
• Object
• Array
• Binary Data
• Undefined
• Object Id
• Boolean
• Date
• Null
• Regular Expression
• JavaScript (with/without scope)
• 32-bit integer
• 64-bit integer
• Timestamp

Other documents (so called embedded documents), arrays, arrays of documents and references are supported as well.

The field names have couple of restrictions:

• The field with name _id is reserved for use as a primary key and must be unique in whole collection (it is immutable and may be of any type other than an array). This field is always the first field in the document.
• The field names cannot start with the dollar sign ‘$’ character and cannot contain the dot ‘.’ character. Those are reserved.

For example, the simple document representing a Book may look like this:

References (DBRefs) are the pointers from one document to another (using the value of the document’s _id field, collection name, and, optionally, its database name):

For the users familiar with RDBMS concepts, it may look similar to foreign keys and joins, but MongoDB does not support joins: to resolve the reference, the additional query (or queries) should be executed. Nevertheless, it is quite a useful concept to commonly represent links between documents. Looking back to our Book example, let us assume the authors are stored in separate collection and every book is going to have a reference to its author. Here is an example of Author document:

And every Book now references the Author by its _id field and DBRef type:

Later in this section we will see more examples of inserting different documents and using document references.

The one hard limit to keep in mind is that the maximum size of the document (represented in BSON format) is 16 megabytes. For more comprehensive overview of document data model, please refer to official documentation.

The write/update commands have a notion of write concern: the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concerns determines the level of guarantee. When inserts, updates and deletes have a weak write concern, write operations return quickly. Consequently, with strong write concerns the clients may await the MongoDB server instance(s) to confirm the write operations. In some failure cases, write operations issued with weak write concerns may not be persisted. We are going to get back to write concern in Part 5. MongoDB Replication Guide but if you would like to get more details right now, please refer to official documentation.

The update command supports variety of operators to control the modification semantics which are listed in the table below (for more details please refer to official documentation):

Here is an example of the update using some of the operators from the table above:

The latest MongoDB release introduces the bulk operations support, which along with indexing will be covered in Part 7. MongoDB Security, Profiling, Indexing, Cursors and Bulk Operations Guide.

6. Queries

Queries are being used to retrieve data stored in the MongoDB database. In MongoDB, queries select documents from a single collection only (as we already know, joins are not supported). Queries specify the criteria to match the documents against. A query may include a projection to select the fields from the matching documents to return (quite useful to limit the amount of data that should be sent over the network).

With latest release MongoDB allows to limit the query processing time using maxTimeMS option (milliseconds). Please notice that maxTimeMS only accounts for CPU time and does not include network latency or idle time.

db.books.find( { “title”: { “$regex”: “MongoDB” } } ).maxTimeMS( 500 )

In Part 7. MongoDB Security, Profiling, Indexing, Cursors and Bulk Operations Guide we will go through some advanced topics related to cursors, query profiling and query plans.

7. Aggregations

MongoDB provides a family of commands to perform collection-wide aggregation operations (so called aggregation framework). Most the commands we are going to cover in this section except mapReduce, which will be covered in Part 6. MongoDB Map Reduce Tutorial.

8. GridFS

GridFS allows storing and retrieving files that exceed the MongoDB document size limit of 16MB (see please Documents section). Instead of storing a file in a single document, GridFS divides a file into parts (or chunks) and stores each of those chunks as a separate document. By default, the size of the chunk is 255KB. GridFS stores files in two collections (the fs prefix may be changed):

• fs.chunks: stores file content as binary chunks
• fs.files: stores file metadata

For more details, please refer to official documentation.

8. Server

MongoDB server supports a vast variety of commands to inspect its internals and monitor current activities. To satisfy the needs of enterprise deployments, MongoDB has a powerful, role-based security model to ensure that users and applications have access to only the data they are allowed to. Being a large topic, it will be covered in Part 7. MongoDB Security, Profiling, Indexing, Cursors and Bulk Operations Guide.

9. What’s next

In this section we have played quite a lot with MongoDB shell and seen most of the MongoDB commands in action. In the next section we are going to learn how to integrate MongoDB in your Java applications.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.