This quick tutorial should get you up and running doing basic create, read, update, delete (CRUD) operations with Casbah.
Please ensure you have downloaded and installed mongodb and have it running on its default host (localhost) and port (27107).
The next step is to get and install sbt, create an sbt project and install casbah. I recommend using sbt-extras - a special sbt script for installing and running sbt.
curl https://raw.github.com/paulp/sbt-extras/master/sbt > sbt chmod +ux sbt
name := "Casbah Tutorial" version := "0.1" scalaVersion := "2.10.2" libraryDependencies += "org.mongodb" %% "casbah" % "2.6.3"
Run the console and test (sbt will automatically install the dependencies):
$ ./sbt console scala> import com.mongodb.casbah.Imports._ import com.mongodb.casbah.Imports._
If you had any errors installing casbah please refer to the installation guide, otherwise you are ready to start using casbah!
The first step of using Casbah is to connect to MongoDB. Remember, this tutorial expects MongoDB to be running on localhost on port 27017. MongoClient is the connection class.
Load the scala shell ./sbt console
import com.mongodb.casbah.Imports._ val mongoClient = MongoClient("localhost", 27017)
There are various connection configuration options see the connection guide for more information.
The scala repl has tab completion type: mongoClient.<tab> for a list of all the operations you can run on a connection.
In MongoDB a database doesn't need to exist prior to connecting to it, simply adding documents to a collection is enough to create the database.
Try connecting to the "test" database and getting a list all the collections
val db = mongoClient("test") db.collectionNames
If your database is new then db.collectionNames will return an empty Set, otherwise it will list the collections in the database.
The next step before starting to add, update and remove documents is to get a collection
val coll = db("test")
coll is the "test" collection in the "test" database. You are now ready to begin adding documents.
If you had an existing "test" collection drop it first: coll.drop()
Inserting, reading, updating and deleting documents in MongoDB is simple. The MongoDBObject is a Map-like object that represents a MongoDB Document.
Create two documents a and b:
val a = MongoDBObject("hello" -> "world") val b = MongoDBObject("language" -> "scala")
Insert the documents:
coll.insert( a ) coll.insert( b )
Count the number of documents in the "test" collection:
Use find to query the database and return an iterable cursor, then print out the string representation of each document:
val allDocs = coll.find() println( allDocs ) for(doc <- allDocs) println( doc )
You may notice an extra field in the document: _id. This is the primary key for a document, if you don't supply an _id an ObjectId will be created for you.
By providing a MongoDBObject to the find method you can filter the results:
val hello = MongoDBObject("hello" -> "world") val helloWorld coll.findOne( hello ) // Find a document that doesn't exist val goodbye = MongoDBObject("goodbye" -> "world") val goodbyeWorld coll.findOne( goodbye )
Notice that find returns a Cursor and findOne returns an Option.
Now you have some data in MongoDB, how do you change it? MongoDB provides a powerful update method that allows you to change single or multiple documents.
First, find the scala document and add its platform:
val query = MongoDBObject("language" -> "scala") val update = MongoDBObject("platform" -> "JVM") val result = coll.update( query, update ) println("Number updated: " + result.getN) for (c <- coll.find) println(c)
You will notice that the document is now missing "langauge" -> "scala"! This is because when using update if you provide a simple document it will replace the existing one with the new document.
This is the most common gotcha for newcomers to MongoDB.
val query = MongoDBObject("platform" -> "JVM") val update = $set("language" -> "Scala") val result = coll.update( query, update ) println( "Number updated: " + result.getN ) for ( c <- coll.find ) println( c )
By default update will only update a single document - to update all the documents set the multi flag: .update( query, update, multi=true).
Another useful feature of the update command is it also allows you to upsert documents on the fly. Setting upsert=True will insert the document if doesn't exist, otherwise update it:
val query = MongoDBObject("language" -> "clojure") val update = $set("platform" -> "JVM") val result = coll.update( query, update, upsert=true ) println( "Number updated: " + result.getN ) for (c <- coll.find) println(c)
The final part of the tutorial is removing documents. Remove is the similar to find, in that you provide a query of documents to match against:
val query = MongoDBObject("language" -> "clojure") val result = coll.remove( query ) println("Number removed: " + result.getN) for (c <- coll.find) println(c)
To remove all documents, provide a blank document to match all items in the database:
val query = MongoDBObject() val result = coll.remove( query ) println( "Number removed: " + result.getN ) println( coll.count() )
Rather than iterating the collection and removing each document, its more efficient to drop the collection: