Getting Started

This quick tutorial should get you up and running doing basic create, read, update, delete (CRUD) operations with Casbah.

Prerequisites

Please ensure you have downloaded and installed mongodb and have it running on its default host (localhost) and port (27107).

Getting started

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.

1. Create a project directory: mkdir casbah_tutorial && cd casbah_tutorial

2. Install sbt-extras script:

     curl https://raw.githubusercontent.com/paulp/sbt-extras/master/sbt > sbt
     chmod +ux sbt
   

3. Create an sbt build file: `build.sbt:

   name := "Casbah Tutorial"
   
   
   version := "0.1"
   
   
   scalaVersion := "2.11.7"
   
   
   libraryDependencies += "org.mongodb" %% "casbah" % "3.1.1"
   

4. 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!

Connecting to MongoDB

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.

Getting databases and collections

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.

Doing CRUD operations

Inserting, reading, updating and deleting documents in MongoDB is simple. The MongoDBObject is a Map-like object that represents a MongoDB Document.

Create

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 )

Read

Count the number of documents in the “test” collection:

coll.count()

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 )

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 )

Update

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)

MongoDB comes with a host of update operators to modify documents. Casbah has a powerful :doc:DSL <guide/querying> for creating these update documents. Lets set the language to scala for the JVM document:

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 )

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)

Removing

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:

coll.drop()

Learning more about Casbah

If you got this far you’ve made a great start, so well done! The next step on your Casbah journey is the Reference, where you can learn indepth about how to use casbah and mongodb.