Tutorial

Getting the Database

Download the database, unpack it, and start the mongod process:

$ bin/mongod

Getting A Database Connection

Let's now try manipulating the database with the database shell. (Note we could perform similar operations from any programming language using an appropriate driver.  The shell is convenient for interactive use.)

Start the MongoDB JavaScript shell with:

$ bin/mongo

(By default the shell connects to an assumed database on localhost.)  You then see:

MongoDB shell version: 0.9.8
url: test
connecting to: test
type "help" for help
>

"connecting to:" tells you the name of the database the shell is using. To switch databases, type:

> use mydb

To see a list of handy commands, type help.

Tip for Developers with Experience in Other Databases You may notice, in the examples below, that we never create a database or collection. MongoDB does not require that you do so. As soon as you insert something, MongoDB creates the underlying collection and database. If you query a collection that does not exist, Mongo treats it as an empty collection.

Inserting Data into A Collection

Let's create a test collection and insert some data into it. We will create two objects, j and t, and then save them in the collection things.

In the following examples, '>' indicates commands typed at the shell prompt.

> j = { name: "mongo"};
{"name" : "mongo"}
> t = { x : 3 };
{ "x" : 3  }
> db.things.save(j);
> db.things.save(t);
> db.things.find();
in cursor for : DBQuery: example.things ->
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
{"x" : 3 , "_id" : "497cf61651712cf7758fbdbc"}
>

A few things to note :

• We did not predefine the collection. The database creates it automatically on the first insert.
• The documents we store can have any "structure" - in fact in this example, the documents have no common data elements at all. In practice, one usually stores documents of the same structure within collections. However, this flexibility means that schema migration and augmentation are very easy in practice - rarely will you need to write scripts which perform "alter table" type operations.
• Upon being inserted into the database, objects are assigned an object ID (if they do not already have one) in the field _id.
• When you run the above example, your ObjectID values will be different.

Let's add some more records to this collection:

> for( var i = 1; i < 10; i++ ) db.things.save( { x:4, j:i } );
> db.things.find();
in cursor for : DBQuery: example.things ->
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
{"x" : 3 , "_id" : "497cf61651712cf7758fbdbc"}
{"x" : 4 , "j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
{"x" : 4 , "j" : 2 , "_id" : "497cf87151712cf7758fbdbe"}
{"x" : 4 , "j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}
{"x" : 4 , "j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}
{"x" : 4 , "j" : 5 , "_id" : "497cf87151712cf7758fbdc1"}
{"x" : 4 , "j" : 6 , "_id" : "497cf87151712cf7758fbdc2"}
{"x" : 4 , "j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"x" : 4 , "j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
has more

Note that not all documents were shown - the shell limits the number to 10 when automatically iterating a cursor. Since we already had 2 documents in the collection, we only see the first 8 of the newly-inserted documents.

If we want to return the next set of results, there's the it shortcut. Continuing from the code above:

{"x" : 4 , "j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"x" : 4 , "j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
has more
> it
{"x" : 4 , "j" : 9 , "_id" : "497cf87151712cf7758fbdc5"}
{"x" : 4 , "j" : 10 , "_id" : "497cf87151712cf7758fbdc6"}

Technically, find() returns a cursor object. But in the cases above, we haven't assigned that cursor to a variable. So, the shell automatically iterates over the cursor, giving us an initial result set, and allowing us to continue iterating with the it command.

But we can also work with the cursor directly; just how that's done is discussed in the next section.

Accessing Data From a Query

Before we discuss queries in any depth, lets talk about how to work with the results of a query - a cursor object. We'll use the simple find() query method, which returns everything in a collection, and talk about how to create specific queries later on.

In order to see all the elements in the collection when using the mongo shell, we need to explicitly use the cursor returned from the find() operation.

Lets repeat the same query, but this time use the cursor that find() returns, and iterate over it in a while loop :

> var cursor = db.things.find();
> while (cursor.hasNext()) { print(tojson(cursor.next())); }
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
{"x" : 3 , "_id" : "497cf61651712cf7758fbdbc"}
{"x" : 4 , "j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
{"x" : 4 , "j" : 2 , "_id" : "497cf87151712cf7758fbdbe"}
{"x" : 4 , "j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}
{"x" : 4 , "j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}
{"x" : 4 , "j" : 5 , "_id" : "497cf87151712cf7758fbdc1"}
{"x" : 4 , "j" : 6 , "_id" : "497cf87151712cf7758fbdc2"}
{"x" : 4 , "j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"x" : 4 , "j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
{"x" : 4 , "j" : 9 , "_id" : "497cf87151712cf7758fbdc5"}
>

The above example shows cursor-style iteration. The hasNext() function tells if there are any more documents to return, and the next() function returns the next document. We also used the built-in tojson() method to render the document in a pretty JSON-style format.

When working in the JavaScript shell, we can also use the functional features of the language, and just call forEach on the cursor. Repeating the example above, but using forEach() directly on the cursor rather than the while loop:

> db.things.find().forEach( function(x) { print(tojson(x));});
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
{"x" : 3 , "_id" : "497cf61651712cf7758fbdbc"}
{"x" : 4 , "j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
{"x" : 4 , "j" : 2 , "_id" : "497cf87151712cf7758fbdbe"}
{"x" : 4 , "j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}
{"x" : 4 , "j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}
{"x" : 4 , "j" : 5 , "_id" : "497cf87151712cf7758fbdc1"}
{"x" : 4 , "j" : 6 , "_id" : "497cf87151712cf7758fbdc2"}
{"x" : 4 , "j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"x" : 4 , "j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
{"x" : 4 , "j" : 9 , "_id" : "497cf87151712cf7758fbdc5"}
>

In the case of a forEach() we must define a function that is called for each document in the cursor.

In the mongo shell, you can also treat cursors like an array :

> var cursor = db.things.find();
> print (tojson(cursor[4]));
{"x" : 4 , "j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}

When using a cursor this way, note that all values up to the highest accessed (cursor[4] above) are loaded into RAM at the same time. This is inappropriate for large result sets, as you will run out of memory. Cursors should be used as an iterator with any query which returns a large number of elements.

In addition to array-style access to a cursor, you may also convert the cursor to a true array:

> var arr = db.things.find().toArray();
> arr[5];
{"x" : 4 , "j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}

Please note that these array features are specific to mongo - The Interactive Shell, and not offered by all drivers.

MongoDB cursors are not snapshots - operations performed by you or other users on the collection being queried between the first and last call to next() of your cursor may or may not be returned by the cursor. Use explicit locking to perform a snapshotted query.

Specifying What the Query Returns

Now that we know how to work with the cursor objects that are returned from queries, lets now focus on how to tailor queries to return specific things.

In general, the way to do this is to create "query documents", which are documents that indicate the pattern of keys and values that are to be matched.

These are easier to demonstrate than explain. In the following examples, we'll give example SQL queries, and demonstrate how to represent the same query using MongoDB via the mongo shell. This way of specifying queries is fundamental to MongoDB, so you'll find the same general facility in any driver or language.

> db.things.find({name:"mongo"}).forEach(function(x) { print(tojson(x));});
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
>

> db.things.find({x:4}).forEach(function(x) { print(tojson(x));});
{"x" : 4 , "j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
{"x" : 4 , "j" : 2 , "_id" : "497cf87151712cf7758fbdbe"}
{"x" : 4 , "j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}
{"x" : 4 , "j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}
{"x" : 4 , "j" : 5 , "_id" : "497cf87151712cf7758fbdc1"}
{"x" : 4 , "j" : 6 , "_id" : "497cf87151712cf7758fbdc2"}
{"x" : 4 , "j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"x" : 4 , "j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
{"x" : 4 , "j" : 9 , "_id" : "497cf87151712cf7758fbdc5"}
>

The query expression is an document itself. A query document of the form { a:A, b:B, ... } means "where a==A and b==B and ...". More information on query capabilities may be found in the Queries and Cursors section of the Mongo Developers' Guide.

MongoDB also lets you return "partial documents" - documents that have only a subset of the elements of the document stored in the database. To do this, you add a second argument to the find() query, supplying a document that lists the elements to be returned.

To illustrate, lets repeat the last example find({x:4}) with an additional argument that limits the returned document to just the "j" elements:

> db.things.find({x:4}, {j:true}).forEach(function(x) { print(tojson(x));});
{"j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
{"j" : 2 , "_id" : "497cf87151712cf7758fbdbe"}
{"j" : 3 , "_id" : "497cf87151712cf7758fbdbf"}
{"j" : 4 , "_id" : "497cf87151712cf7758fbdc0"}
{"j" : 5 , "_id" : "497cf87151712cf7758fbdc1"}
{"j" : 6 , "_id" : "497cf87151712cf7758fbdc2"}
{"j" : 7 , "_id" : "497cf87151712cf7758fbdc3"}
{"j" : 8 , "_id" : "497cf87151712cf7758fbdc4"}
{"j" : 9 , "_id" : "497cf87151712cf7758fbdc5"}
>

Note that the "_id" field is always returned.

findOne() - Syntactic Sugar

For convenience, the mongo shell (and other drivers) lets you avoid the programming overhead of dealing with the cursor, and just lets you retrieve one document via the findOne() function. findOne() takes all the same parameters of the find() function, but instead of returning a cursor, it will return either the first document returned from the database, or null if no document is found that matches the specified query.

As an example, lets retrieve the one document with name=='mongo'. There are many ways to do it, including just calling next() on the cursor (after checking for null, of course), or treating the cursor as an array and accessing the 0th element.

However, the findOne() method is both convenient and efficient:

> var mongo = db.things.findOne({name:"mongo"});
> print(tojson(mongo));
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
>

This is more efficient because the client requests a single object from the database, so less work is done by the database and the network. This is the equivalent of find({name:"mongo"}).limit(1).

Limiting the Result Set via limit()

You may limit the size of a query's result set by specifing a maximum number of results to be returned via the limit() method.

This is highly recommended for performance reasons, as it limits the work the database does, and limits the amount of data returned over the network. For example:

> db.things.find().limit(3);
in cursor for : DBQuery: example.things ->
{"name" : "mongo" , "_id" : "497cf60751712cf7758fbdbb"}
{"x" : 3 , "_id" : "497cf61651712cf7758fbdbc"}
{"x" : 4 , "j" : 1 , "_id" : "497cf87151712cf7758fbdbd"}
>

What Next

After completing this tutorial the next step to learning MongoDB is to dive into the manual for more details.