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](http://api.mongodb.org/python/1.4%2B/tutorial.html).

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 postsCol = (fromString "test.posts")

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:

    > cols <- collectionNames con (fromString "test")
    > map toString cols
    ["test.system.indexes"]

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
-------------------

To insert a document into a collection we can use the *insert* function:

    > insert con postsCol post

When a document is inserted a special key, *_id*, is automatically
added if the document doesn't already contain an *_id* key. The value
of *_id* must be unique across the collection. insert() returns the
value of *_id* for the inserted document. For more information, see
the [documentation on _id](http://www.mongodb.org/display/DOCS/Object+IDs).

After inserting the first document, the posts collection has actually
been created on the server. We can verify this by listing all of the
collections in our database:

    > cols <- collectionNames con (fromString "test")
    > map toString cols
    [u'postsCol', u'system.indexes']

* Note The system.indexes collection is a special internal collection
that was created automatically.

Getting a single document with findOne
-------------------------------------

The most basic type of query that can be performed in MongoDB is
*findOne*. This method returns a single document matching a query (or
*Nothing* if there are no matches). It is useful when you know there is
only one matching document, or are only interested in the first
match. Here we use *findOne* to get the first document from the posts
collection:

    > findOne con postsCol []
    Just [(Chunk "_id" Empty,BsonObjectId (Chunk "K\151\153S9\CAN\138e\203X\182'" Empty)),(Chunk "author" Empty,BsonString (Chunk "Mike" Empty)),(Chunk "text" Empty,BsonString (Chunk "My first blog post!" Empty)),(Chunk "tags" Empty,BsonArray [BsonString (Chunk "mongoDB" Empty),BsonString (Chunk "Haskell" Empty)]),(Chunk "date" Empty,BsonDate 1268226361.753s)]

The result is a dictionary matching the one that we inserted
previously.

* Note: The returned document contains an *_id*, which was automatically
added on insert.

*findOne* also supports querying on specific elements that the
resulting document must match. To limit our results to a document with
author "Mike" we do:

    > findOne con postsCol $ toBsonDoc [("author", toBson "Mike")]
    Just [(Chunk "_id" Empty,BsonObjectId (Chunk "K\151\153S9\CAN\138e\203X\182'" Empty)),(Chunk "author" Empty,BsonString (Chunk "Mike" Empty)),(Chunk "text" Empty,BsonString (Chunk "My first blog post!" Empty)),(Chunk "tags" Empty,BsonArray [BsonString (Chunk "mongoDB" Empty),BsonString (Chunk "Haskell" Empty)]),(Chunk "date" Empty,BsonDate 1268226361.753s)]

If we try with a different author, like "Eliot", we'll get no result:

    > findOne con postsCol $ toBsonDoc [("author", toBson "Eliot")]
    Nothing

Bulk Inserts
------------

In order to make querying a little more interesting, let's insert a
few more documents. In addition to inserting a single document, we can
also perform bulk insert operations, by using the *insertMany* api
which accepts a list of documents to be inserted. This will insert
each document in the iterable, sending only a single command to the
server:

    > now <- getPOSIXTime
    > :{
      let new_postsCol = [toBsonDoc [("author", toBson "Mike"),
                                     ("text", toBson "Another post!"),
                                     ("tags", toBson ["bulk", "insert"]),
                                     ("date",  toBson now)],
                          toBsonDoc [("author", toBson "Eliot"),
                                     ("title", toBson "MongoDB is fun"),
                                     ("text", toBson "and pretty easy too!"),
                                     ("date", toBson now)]]
      :}
    > insertMany con postsCol new_posts

* Note that *new_posts !! 1* has a different shape than the other
posts - there is no "tags" field and we've added a new field,
"title". This is what we mean when we say that MongoDB is schema-free.

Querying for More Than One Document
------------------------------------

To get more than a single document as the result of a query we use the
*find* method. *find* returns a cursor instance, which allows us to
iterate over all matching documents. There are several ways in which
we can iterate: we can call *nextDoc* to get documents one at a time
or we can get a lazy list of all the results by applying the cursor
to *allDocs*:

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

Of course you can use bind (*>>=*) to combine these into one line:

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

* Note: *nextDoc* automatically closes the cursor when the last
document has been read out of it. Similarly, *allDocs* automatically
closes the cursor when you've consumed to the end of the resulting
list.

Counting
--------

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

    > num <- count con postsCol

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

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

Range Queries
-------------

No non native sorting yet.

Indexing
--------

WIP - coming soon.

Something like...

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