====== Introduction ======

From [[http://www.mongodb.org/|the hp]]: "MongoDB (from "humongous") is a scalable, high-performance, open source NoSQL database. Written in C++, features"
  * Document-Oriented Storage (JSON-style documents with dynamic schemas offer simplicity and power)
  * Full Index Support (Index on any attribute)
  * Replication & High Availability (Mirror across LANs and WANs)
  * Auto-Sharding (Scale horizontally without compromising functionality)
  * Querying 
  * Fast In-Place Updates 
  * Map/Reduce 
  * GridFS 
  * Commercial Support 


This page aims to be a MongoDB **"hello world"** example, for more info read 
  * [[MongoDBCookBook]]
  * [[MongoDBAdmin]]

===== Differences to traditional DBMS =====

MongoDB does not support transactions. [[http://www.mongodb.org/display/DOCS/Atomic+Operations|Atomic operations]] are supported.

====== Getting started ======

<code bash>
sudo apt-get install mongodb
</code>


will pull in all dependencies, install and start the database.

If required, adjust settings in /etc/mongodb.conf (like IP binding or port)

===== Start/stop database =====

<code bash>
sudo service mongodb stop
sudo service mongodb start
</code>

===== Login to database =====

An easy way is the [[http://www.mongodb.org/display/DOCS/mongo+-+The+Interactive+Shell|mongo]] interactive shell.
In a terminal, type

<code bash>
mongo
</code>

This connects to database "test".


====== Usage examples ======

The information below comes from the [[http://www.mongodb.org/display/DOCS/Manual|MongoDB manual]]
===== Use a specific database =====

To use a specific database, say "accounts", login to mongo and issue

<code bash>
>use accounts
</code>

If database "accounts" does not exist yet, it will be created.

List all existing databases:
<code bash>
>show dbs
</code>
===== Collections =====

MongoDB [[http://www.mongodb.org/display/DOCS/Collections|collections]] can be compared to RDBS tables. Collections are named groupings of documents.

Login to a specific database and list existing collections:

<code java>
>use accounts
>show collections
</code>

As with databases, the first time you access a collection, it will be automatically be created for you.


===== Insert documents =====

As mentioned before, MongoDB is document-oriented. Whereas you think of //rows// in RDBMS, you think of [[http://www.mongodb.org/display/DOCS/Documents|documents]] in MongoDB.
More specifically, MongoDB documents are in JSON format.


Insert one document
<code bash>
> db.transactions.save({"name":"alice","type":"withdrawal", "amount": 30})
</code>

or bulk insert (supported in shell since v2.2)
<code bash>
>db.transactions.save([{"name":"alice","type":"deposit", "amount": 500}, {"name":"alice","type":"withdrawal", "amount": 50}, {"name":"bob","type":"withdrawal", "amount": 20}, {"name":"bob","type":"withdrawal", "amount": 60}])
</code>

===== Update =====

Change transaction type to "deposit" where name=bob and amount 60
<code java>
> db.transactions.update({"name":"bob", "amount":60}, {$set : {"type":"deposit"}})
</code>

===== Delete documents =====
<code java>
db.transactions.drop() 	//drop the entire transactions collection
db.transactions.remove() //remove all objects from the collection
db.transactions.remove( { name : "sara" } )  //remove objects from the collection where name is sara
</code>

===== Retrieve data =====

Get all documents
<code java>
> db.transactions.find()
</code>

==== With WHERE clause====

Alice's money transactions:
<code java>
> db.transactions.find({"name" : "alice"})
</code>

==== Only specific fields ====

Show only type and amount fields
<code java>
> db.transactions.find({}, {"type":true, "amount":true, "_id":false})
</code>

==== Limit result to x rows ====
<code java>
> db.transactions.find({}, {}).limit(2)
</code>

==== Sort results ====

sort by name ascending, amount descending
<code java>
> db.transactions.find( {},{}).sort({"name":1,"amount":-1})
</code>
==== Indizes ====

Run ensureIndex(), which builds the index ONLY if it does not already exist.

<code java>
db.transactions.ensureIndex({"name":true});
</code>

View existing indizes

<code java>
db.transactions.getIndexes()
</code>

The [[http://docs.mongodb.org/manual/core/indexes/|manual]] has more details.


===== Simple analyses =====

==== Count lines ====

<code java>
> db.transactions.count() 
// or with a WHERE clause
> db.transactions.count({"name":"alice"}) 
</code>
==== Calculate sum ====

How much did all users withdraw?
<code java>
> db.transactions.group( {
   "key": {"name":true} , 
   "cond": {"type":"withdrawal"}, 
   "reduce": function (obj,prev) { prev.csum += obj.amount; }, 
   "initial": { csum: 0 } 
}  )
</code>


==== Calculate average ====

==== Distinct values ====

<code java>
> db.transactions.distinct("name")
</code>
==== Analyse query ====


Use [[http://www.mongodb.org/display/DOCS/Explain#Explain-millis|explain()]] to get statistics about a query, e.g. check "millis" for the query runtime in milliseconds.

**NOTE: during the execution of explain(), the actual query is being run!** So if the query takes lots of time, explain() will take a long time, too.

<code java>
> db.transactions.find({},{"name":true, "amount":"true"}).explain()


{
	"cursor" : "BasicCursor",
	"isMultiKey" : false,
	"n" : 6,
	"nscannedObjects" : 6,
	"nscanned" : 6,
	"nscannedObjectsAllPlans" : 6,
	"nscannedAllPlans" : 6,
	"scanAndOrder" : false,
	"indexOnly" : false,
	"nYields" : 0,
	"nChunkSkips" : 0,
	"millis" : 0,
	"indexBounds" : {
		
	},
	"server" : "ankh:27017"
}




</code>