mongodb/tutorial.md

MongoDB Haskell Mini Tutorial

Author: Brian Gianforcaro (b.gianfo@gmail.com)

Updated: 2/28/2010

This is a mini tutorial to get you up and going with the basics of the Haskell mongoDB drivers. It is modeled after the pymongo tutorial.

You will need the mongoDB bindings installed as well as mongo itself installed.

$ = command line prompt
> = ghci repl prompt

Installing Haskell Bindings

From Source:

$ git clone git://github.com/srp/mongoDB.git
$ cd mongoDB
$ runhaskell Setup.hs configure
$ runhaskell Setup.hs build
$ runhaskell Setup.hs install

From Hackage using cabal:

$ cabal install mongoDB

Getting Ready

Start a MongoDB instance for us to play with:

$ mongod

Start up a haskell repl:

$ ghci

Now We'll need to bring in the MongoDB/BSON bindings:

> import Database.MongoDB
> import Database.MongoDB.BSON

Making A Connection

Open up a connection to your DB instance, using the standard port:

> con <- connect "127.0.0.1" []

or for a non-standard port

> import Network
> con <- connectOnPort "127.0.0.1" (Network.PortNumber 666) []

By default mongoDB will try to find the master and connect to it and will throw an exception if a master can not be found to connect to. You can force mongoDB to connect to the slave by adding SlaveOK as a connection option, eg:

> con <- connect "127.0.0.1" [SlaveOK]

Databases, Collections and FullCollections

As many database servers, MongoDB has databases--separate namespaces under which collections reside. Most of the APIs for this driver request the FullCollection which is simply the Database and the Collection concatenated with a period.

For instance 'myweb_prod.users' is the the FullCollection name for the *Collection 'users' in the database 'myweb_prod'.

Databases and collections do not need to be created, just start using them and MongoDB will automatically create them for you.

In the below examples we'll be using the following FullCollection:

> import Data.ByteString.Lazy.UTF8
> let testcol = (fromString "test.haskell")

You can obtain a list of databases available on a connection:

> dbs <- databaseNames con

You can obtain a list of collections available on a database:

> collections <- collectionNames con (fromString "test")

Documents

Data in MongoDB is represented (and stored) using JSON-style documents. In mongoDB we use the BsonDoc type to represent these documents. At the moment a BsonDoc is simply a tuple list of the type '[(ByteString, BsonValue)]'. Here's a BsonDoc which could represent a blog post:

> import Data.Time.Clock.POSIX
> now <- getPOSIXTime
> :{
  let post = [(fromString "author", BsonString $ fromString "Mike"),
              (fromString "text",
               BsonString $ fromString "My first blog post!"),
              (fromString "tags",
               BsonArray [BsonString $ fromString "mongodb",
                          BsonString $ fromString "python",
                          BsonString $ fromString "pymongo"]),
              (fromString "date", BsonDate now)]
  :}

With all the type wrappers and string conversion, it's hard to see what's actually going on. Fortunately the BSON library provides conversion functions toBson and fromBson for converting native between the wrapped BSON types and many native Haskell types. The functions toBsonDoc and fromBsonDoc help convert from tuple lists with plain String keys, or Data.Map.

Here's the same BSON data structure using these conversion functions:

> :{
  let post = toBsonDoc [("author", toBson "Mike"),
                        ("text", toBson "My first blog post!"),
                        ("tags", toBson ["mongoDB", "Haskell"]),
                        ("date", BsonDate now)]
  :}

Inserting a Document

> insert con testcol post

Getting a single document with findOne

> findOne con testcol (toBsonDoc [("author", toBson "Mike")])

Querying for More Than One Document

> cursor <- find con testcol (toBsonDoc [("author", toBson "Mike")])
> allDocs cursor

You can combine these into one line:

> docs <- allDocs =<< find con testcol (toBsonDoc [("author", toBson "Mike")])

See nextDoc to modify cursor incrementally one at a time.

• Note: allDocs automatically closes the cursor when done, through nextDoc.

Counting

We can count how many documents are in an entire collection:

> num <- count con testcol

Or we can query for how many documents match a query:

> num <- countMatching con testcol (toBsonDoc [("author", toBson "Mike")])

Range Queries

No non native sorting yet.

Indexing

WIP - coming soon.

Something like...

> index <- createIndex con testcol [("author", Ascending)] True