RavenDB: first contact

We have seen how to setup the development environment to use RavenDB, obviously the next step is to try to use our brand new environment.

NuGet to the rescue

First of all let’s setup the Visual Studio project to use RavenDB, using nuget as simple as adding a package reference to the RavenDB nuget package:

Figure: nuget installation dialog

the package installation downloads all the required dependencies and setup the application configuration file with the required connection string, that obviously must be adapted to your environment:

Figure: the application configuration file customized for my environment, where RavenDB server listen on port 81

The basics

RavenDB has 2 main building block that must be understood in order to manage all the features, having had previous experience with NHibernate can help in this area because the RavenDB API has been designed to help ORM users to migrate and stay in well known environment.

IDocumentStore

The IDocumentStore interface is the counterpart, for ORM users, of the NHibernate ISessionFactory there should (we’ll see in future posts why “should” and not must) be one document store per each RavenDB server we need to access.

Figure: the creation and initialization of the document store

the document store has several properties that we can use to customize the behavior of the connection, the security and the behavior of the store itself.

The only really required thing to do is to initialize, once, the store calling the quite obvious “Initialize” method.

IDocumentSession

the document session interface, that mimics the NHibernate ISession behaviors, is the entry point to access data stored on a RavenDB server instance. The document session is also our “Unit Of Work” implementation that let us manage business transactions against the server.

Connection to a database is as easy as:

Figure: the creation of a document session

where “myMusic” is the name of the database where I created the sample data, if we do not specify the database name the connection will be made against the default database (that always exists) or against the default database specified before the document store initialization using the DefaultDatabase property (we can also specify the default database in the connection string.

So far so good…so what?

…let’s try to pick some data…just try:

Figure: some data retrieved in a rather funky way

Cool! what’s going on? we have done a really strange thing we have used the generic Query method, closed against a .net 4.0 dynamic type, asking for the first 10 items…and we received back 10 items…not so expected as it can seem at a first look.

A little digression…little, trust me…

In order to figure out what has happened when the above query has been executed we need to understand how data (document) are stored in a document database.

No tables here guys , the above linq query can be compared to the following, invalid, T-SQL statement:

select top 10 *
go

That obviously has no meaning in a relational world because lacks, al least, the “from <table-name>” clause. Document databases has the concept of collection that represents an homogeneous subset of data and in RavenDB the subset you want to query over is expressed by the .net generic type you choose for the Query method (it is not really true, but for the moment it’s good enough).

Let’s move on

If we take a look at the database using the Raven Management Studio we can see that there are 2 different collections: Albums and Genres.

Figure: collection contained in the database

Which is the easiest method to tell to the document session that we want to query the albums collection? remember easiest.

Just define an Album type with the same shape of the json document stored in the database

Figures: on the left side the Album type definition on the right side the json document that represents an album in the database

As you can see we have defined even complex types (AlbumGenre and AlbumArtist, we’ll have future posts to detail the concept of “relation”) that will be automatically mapped to the corresponding nested properties in the json document. One thing you may already have noticed is that the json document is the serialized version of the .net type.

Query

if we rewrite the above query using the Album type we fetch exactly 10 albums:

Figure: RavenDB query executed to retrieve 10 albums from the database

wundershon …but how can RavenDB “map” our .net type to its own internal representation? using one of the thousands of cool features that this database have: metadata.

Figure: the same document showing the metadata tab in the management studio.

each document has a set of extensible metadata attached to it and the important one in this case is the Raven-Entity-Name, the database engine utilizes a set of conventions to translate a .net type name to the so called “Raven tag name”:

Figure: using document store conventions to map .net type name to Raven tag name.

Enough for this post…next time is time for “storing data”

.m