MongoDB Basics

Introduction

Some time ago, I heard about MongoDb and I started searching on search engines to get to know its scope. I found lot of supporting material in scattered form on various websites and books. Then, I thought of compiling atleast some basic getting started sort of tutorial for MongoDB so that the developers who are new to MongoDB or unfamiliar with it, can get to know what it is and how to initiate development with this new technology.

I must mention here that this article is much inspired by Karl Seguin's book on MongoDB. His blog can be found here.

This article demonstrates the introduction of MongoDB, no-SQL, the document-oriented database. The developers who are unfamiliar with no-SQL database, will wonder how it works. As a document-oriented database, MongoDB is a more generalized NoSQL solution. It should be viewed as an alternative to relational databases. Like relational databases, it too can benefit from being paired with some of the more specialized NoSQL solutions. Take it as simple as just any database, which stores data in some particular structure. Let's first setup your environment and enjoy the MongoDB power and start thinking of using it in your projects where you find it appropriate.

Setting Up the MongoDB

It's easy to set up and running with MongoDB.

1. Go to the official download page and get the binaries of your choice.
2. Extract the archive (anywhere you want) and navigate to the bin subfolder. Note that mongod is the server process and mongo is the client shell - these are the two executables we'll be spending most of our time with.
3. Create a new text file in the bin subfolder named mongodb.config.
4. Add a single line to your mongodb.config: dbpath=PATH_TO_WHERE_YOU_WANT_TO_STORE_YOUR_DATABASE_FILES. For example, on Windows, you might do dbpath=c:\mongodb\data.
5. Make sure the dbpath you specified exists.
6. Launch mongod with the --config /path/to/your/mongodb.config parameter. As an example, if you extracted the downloaded file to c:\mongodb\ and you created c:\mongodb\data\, then within c:\mongodb\bin\mongodb.config, you would specify dbpath=c:\mongodb\data\. You could then launch mongod from a command prompt via c:\ mongodb\bin\mongod --config c:\mongodb\bin\mongodb.config.

Hopefully you now have MonogDB up and running. If you get an error, read the output carefully - the server is quite good at explaining what happens wrong. You can now launch mongo which will connect a shell to your running server. Try entering db.version() to make sure everything's working as it should. Hopefully, you'll see the version number you installed. Go ahead and enter db.help(), you'll get a list of commands that you can execute against the db object.

Some Basic Concepts

Let's start our journey by getting to know the basic mechanics of working with MongoDB. Obviously, this is core to understanding MongoDB, but it will also help to give the idea about some higher level questions about where MongoDB fits.

To get started, there are six basic concepts we need to understand.

1. MongoDB has the same concept of a 'database' with which you are likely already familiar. Within a MongoDB instance, you can have zero or more databases, each acting as high-level containers for everything else. You could think of it as simple database object in Microsoft SQL Server just for understanding the idea more clearly.
2. A database can have zero or more 'collections'. A collection shares the same concept as a traditional `table', that you can think of the two as the same thing.
3. Collections are made up of zero or more 'documents'. A document can be thought of as a 'row'.
4. A document is made up of one or more 'fields', which you can guess, are like 'columns'.
5. 'Indexes' in MongoDB function much like their RDBMS counterparts.
6. 'Cursors' are different than the other five concepts. When you ask MongoDB for data, it returns a cursor, which you can do your processing, such as counting or skipping ahead, without actually pulling down data.

In summary, MongoDB is made up of databases which contain collections. A collection is made up of documents. Each document is made up of fields. Collections can be indexed, which improves lookup and sorting performance. Finally, when we get data from MongoDB, we do so through a cursor which is delayed to execute until necessary, might be called as lazy loading.

While these concepts are similar to their relational database counterparts, they are not identical. The core difference comes from the fact that relational databases define columns at the table level whereas a document-oriented database defines its fields at the document level. Each document within a collection can have its own unique set of fields. As such, a collection is a container in comparison to a table, while a document has a lot more information than a row.

Let's Start Playing with MongoDB

First, we'll use the global use method to switch databases, go ahead and enter use mycompany. It doesn't matter that the database doesn't really exist yet. The first collection that we create will also create the actual mycompany database.

Now that you are inside a database, you can start issuing database commands, like db.getCollectionNames(). If you do so, you should get an empty array ([ ]). Since collections are schema-less, we don't explicitly need to create them. We can simply insert a document into a new collection.

To do so, use the insert command, supplying it with the document to insert:

db.departments.insert({name: 'Human Resource', city: 'karachi', head: 'Muhammad Ibrahim'})

The above line is executing insert against the departments collection, passing it a single argument. Internally MongoDB uses a binary serialized JSON format. Externally, this means that we use JSON a lot, as is the case with our parameters. If we execute db.getCollectionNames() now, we'll actually see two collections: departments and system.indexes. system.indexes is created once per database and contains the information on our databases index. You can now use the find command against departments to return a list of documents:

db.departments.find()

Notice that, in addition to the data you specified, there's an _id field. Every document must have a unique _id field. You can either generate one yourself or let MongoDB generate an ObjectId for you. Most of the time you'll probably want to let MongoDB generate it for you. By default, the _id field is indexed - which explains why the system.indexes collection was created. You can look at system.indexes:

db.system.indexes.find()

What you're seeing is the name of the index, the database and collection it was created against and the fields included in the index.

Now, back to our discussion about schema-less collections. Insert a totally different document into departments, such as:

db.departments.insert({name: 'Development', country: 'Pakistan', _
departmentManager: 'Saeed Anwar', annualBudget: 5000000})

And, again use find to list the documents. Hopefully now you are starting to understand why the more traditional terminology wasn't a good fit.

There's one practical aspect of MongoDB you need to have a good grasp of before moving to more advanced topics: query selectors. A MongoDB query selector is like the where clause of an SQL statement. As such, you use it when finding, counting, updating and removing documents from collections. A selector is a JSON object , the simplest of which is {} which matches all documents (null works too). If we want all departments in Karachi city, we could use {city:'Karachi'}.

Before delving too deeply into selectors, let's set up some data to play with. Let insert some data in Employees collection, remember although it does not already exist but when you go to insert in that collection, MondoDB will create that collection in the current database:

db.employees.insert({name: 'Amir Sohail', dob: new Date(1973,2,13,7,47), 
hobbies: ['cricket','reading'], city: 'Karachi', gender: 'm'});
db.employees.insert({name: 'Inzama-ul-Haq', dob: new Date(1977,2,13,7,47), 
hobbies: ['cricket','browsing'], city: 'Lahore', gender: 'm'});
db.employees.insert({name: 'Muhammad Yousuf', dob: new Date(1978, 0, 24, 13, 0), 
hobbies: ['football','chatting'], city: 'Karachi', gender: 'm'});
db.employees.insert({name: 'Muhammad Younis', dob: new Date(1982, 0, 24, 13, 0), 
hobbies: ['watching movies'], city: 'Peshawar', 
gender: 'm', department:'Human Resource'});
db.employees.insert({name: 'Shahid Afridi', dob: new Date(1983, 0, 24, 13, 0), 
hobbies: ['basketball','chatting'], city: 'Karachi', 
gender: 'm', department:'Development'});
db.employees.insert({name: 'Moin Khan', dob: new Date(1978, 0, 24, 13, 0), 
hobbies: ['cricket','chatting', 'browsing'], city: 'Islamabad', gender: 'm'});
db.employees.insert({name: 'Afra Kareem', dob: new Date(1993, 0, 24, 13, 0), 
hobbies: ['reading','browsing'], city: 'Karachi', gender: 'f', department:'Development'});
db.employees.insert({name: 'Asma Khan', dob: new Date(1985, 0, 24, 13, 0), 
hobbies: ['reading','watching movies'], city: 'Lahore', 
gender: 'f', department:'Human Resource'});
db.employees.insert({name: 'Nazia Malik', dob: new Date(1984, 0, 24, 13, 0), 
hobbies: ['reading'], city: 'Karachi', gender: 'f', department:'Development'});
db.employees.insert({firstName: 'Waqar', lastName: 'Younis', 
dob: new Date(1978, 0, 24, 13, 0), 
hobbies: ['cricket','chatting', 'basketball', 'browsing'], city: 'Karachi', gender: 'm'});
db.employees.insert({name: 'Waseem Akram', dob: new Date(1975, 0, 24, 13, 0), 
hobbies: ['cricket','chatting'], city: 'Rawalpindi', gender: 'm'});
db.employees.insert({name: 'Shoaib Akhtar', dob: new Date(1980, 0, 24, 13, 0), 
hobbies: ['football'], city: 'Rawalpindi', gender: 'm'});
db.employees.insert({name: 'Muhammad Amir', dob: new Date(1978, 0, 24, 13, 0), 
hobbies: ['bowling'], city: 'Karachi', gender: 'm'});
db.employees.insert({name: 'Saeed Ajmal', dob: new Date(1983, 0, 24, 13, 0), 
hobbies: ['spin bowling'], city: 'Karachi', gender: 'm'});
db.employees.insert({name: 'Abdur Rehman', dob: new Date(1982, 0, 24, 13, 0), 
hobbies: ['bowling'], city: 'Lahore', gender: 'm'});
db.employees.insert({name: 'Muhammad Mushtaq', dob: new Date(1972, 0, 24, 13, 0), 
hobbies: ['cricket','chatting'], city: 'Lahore', gender: 'm'});
db.employees.insert({firstName: 'Saqlain', lastName: 'Mushtaq', 
dob: new Date(1978, 0, 24, 13, 0), 
hobbies: ['football','chatting'], city: 'Karachi', 
gender: 'm', department:'Development'});

Now that we have data, we can master selectors. {field: value} is used to find any documents where field is equal to value. {field1: value1, field2: value2} is how we do an and statement. The special $lt, $lte, $gt, $gte and $ne are used for less than, less than or equal, greater than, greater than or equal and not equal operations. For example, to get all male employees that have city Karachi, we could do:

db.employees.find({gender: 'm', city: 'Karachi'})

The $exists operator is used for matching the presence or absence of a field, for example:

db.employees.find({firstName: {$exists: false}})

should return a single document. If we want to OR rather than AND, we use the $or operator and assign it to an array of values we want or'd:

db.employees.find({gender: 'f', $or: [{hobbies: 'reading'}, {hobbies: 'browsing'}, {
city: 'Karachi'}]})

The above will return all female employees which either have hobbies reading or browsing or city is Karachi. There's something pretty neat going on in our last example. You might have already noticed, but the loves field is an array. MongoDB supports arrays as first class objects. This is an incredibly handy feature. Once you start using it, you wonder how you ever lived without it. What's more interesting is how easy selecting based on an array value is: {hobbies: ' cricket'} will return any document where cricket is a value of hobbies. There are more available operators than what we've seen so far. The most flexible being $where which lets us supply JavaScript to execute on the server. These are all described in the Advanced Queries section of the MongoDB website. What we've covered so far though is the basics you'll need to get started. It's also what you'll end up using most of the time. We've seen how these selectors can be used with the find command. They can also be used with the remove command which we've briefly looked at, the count command, which we haven't looked at but you can probably figure out. The ObjectId which MongoDB generated for our _id field can be selected like so:

db.employees.find({_id: ObjectId("TheObjectId")})

We have remove() command for deletion purpose. To delete all records, simply you could call it on the required collection.

db.employees.remove()

Or alternatively, you could place the desired query selectors to delete only the selective documents.

Points of Interest

We did get MongoDB up and running, looked briefly at the insert and remove commands. We also introduced find and saw what MongoDB selectors were all about. We've had a good start and laid a solid foundation for things to come. Believe it or not, you actually know most of what there is to know about MongoDB - it really is meant to be quick to learn and easy to use. Insert different documents, possibly in new collections, and get familiar with different selectors. Use find, count and remove. After a few tries on your own, things that might have seemed awkward at first will hopefully fall into place.

Hopefully, I am planning to write another article to use MongoDB with C#.NET environment. I appreciate your feedback/comments or any improvements you want to suggest in this regard, to help in making the article much better and helpful for others.

History

• 30^th January, 2012: Initial post