Tutorial
Getting the DatabaseDownload the database, unpack it, and start the mongod process:
By default MongoDB will store data files in /data/db/ (or c:/data/db) on all systems. This convention is used throughout the documentation. You can use a different directory by specifying the --dbpath argument:
Getting A Database ConnectionLet's now try manipulating the database with the database shell . (We could perform similar operations from any programming language using an appropriate driver. The shell is convenient for interactive and administrative use.) Start the MongoDB JavaScript shell with:
By default the shell connects to database "test" on localhost. You then see:
"connecting to:" tells you the name of the database the shell is using. To switch databases, type:
To see a list of handy commands, type help.
Inserting Data into A CollectionLet'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.
A few things to note :
Let's add some more records to this collection:
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:
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 itcommand. But we can also work with the cursor directly; just how that's done is discussed in the next section. Accessing Data From a QueryBefore 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 :
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:
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 :
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:
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 ReturnsNow 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.
SELECT * FROM things WHERE name="mongo"
SELECT * FROM things WHERE x=4
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:
SELECT j FROM things WHERE x=4
Note that the "_id" field is always returned. findOne() - Syntactic SugarFor 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 thefind() function, but instead of returning a cursor, it will return either the first document returned from the database, or nullif 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 callingnext() 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:
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:
More HelpIn addition to the general "help" command, you can call help on db and db.whatever to see a summary of methods available. If you are curious about what a function is doing, you can type it without the {{()}}s and the shell will print the source, for example:
mongo is a full JavaScript shell, so any JavaScript function, syntax, or class can be used in the shell. In addition, MongoDB defines some of its own classes and globals (e.g., db). You can see the full API at http://api.mongodb.org/js/. What NextAfter completing this tutorial the next step to learning MongoDB is to dive into the manual for more details. |