Getting started

Welcome to this introductory article that will guide you through all the parts of RavenDB needed for basic understanding and simple setup.

Starting server

For starters, you need to have a RavenDB server running. There are couple of ways you can acquire it:

Now, we will focus on the distribution package (if you want to read about the installer go here). The package contains the following directories:

In the package there is a file Start.cmd which will start a server as a console application (aka debug mode), which is great for development purposes or simply to try out various functionalities, but not for production release. When server has started, the Studio will be available at http://localhost:<port>/. RavenDB is configured by default to use port 8080, or the next available, if this is one is occupied.

Information

If you want to install RavenDB as a service, please visit this article. There is also a possibility to install it on IIS or run it as an embedded instance.


Client

In the Client directory (in the distribution package), all .NET client libraries can be found. After referencing them in your project, all classes are found under the Raven.* namespace, with the DocumentStore as the most interesting one. This is the main entry point for your application, which will establish and manage connection channel between your application and a server. We recommend reading the following articles:

Information

Worth knowing is that the DocumentStore is a heavyweight object and there should only be one instance of it per application (singleton).

There are two ways to manipulate data using the store, first one (and the recommended one) is a Session, second one are Commands, which are a low-level way to manipulate data and should only be used when needed. Both the Session and the Commands contain asynchronous and synchronous methods.

Please read the following articles if you want to get more details:


Examples

Before we will proceed, we would like to point out that in most of the articles the Northwind database is being used. More details about it and information on how to deploy it can be found here.


Theory & few examples

RavenDB is a document database, which means that all stored objects are called documents. Each document contains a key that identifies it, data, and adjacent metadata, both stored in JSON format. The metadata contains various information describing the document, e.g. the modification date or the collection assignment.

Creating Document Store, Opening a Session, Storing and Loading entities

The example below will demonstrate how to create the DocumentStore, open a Session, store, and load few entities.

using (IDocumentStore store = new DocumentStore
{
	Url = "http://localhost:8080/",	// server URL
	DefaultDatabase = "Northwind"	// default database
})
{
	store.Initialize(); // initializes document store, by connecting to server and downloading various configurations

	using (IDocumentSession session = store.OpenSession()) // opens a session that will work in context of 'DefaultDatabase'
	{
		Employee employee = new Employee
		{
			FirstName = "John",
			LastName = "Doe"
		};

		session.Store(employee); // stores employee in session, assigning it to a collection `Employees`
		string employeeId = employee.Id; // Session.Store will assign Id to employee, if it is not set

		session.SaveChanges(); // sends all changes to server

		// Session implements Unit of Work pattern,
		// therefore employee instance would be the same and no server call will be made
		Employee loadedEmployee = session.Load<Employee>(employeeId);
		Assert.Equal(employee, loadedEmployee);
	}
}

Querying

To satisfy queries, indexes must be used. In short, index is a server-side function that defines using which fields (and what values) document can be searched on. The whole indexation process is done asynchronously, which gives a very quick response times, even when large amounts of data have been changed, however implication of this approach is that the index might be stale. Before you continue, we advise reading the following articles:

This example assumes that your database contains the Northwind sample data. If you are not sure how to deploy it, please visit this article.

/// <summary>
/// All _ in index class names will be converted to /
/// it means that Employees_ByFirstNameAndLastName will be Employees/ByFirstNameAndLastName
/// when deployed to server
/// 
/// AbstractIndexCreationTask is a helper class that gives you strongly-typed syntax
/// for creating indexes
/// </summary>
public class Employees_ByFirstNameAndLastName : AbstractIndexCreationTask<Employee>
{
	public Employees_ByFirstNameAndLastName()
	{
		// this is a simple (Map) index LINQ-flavored mapping function
		// that enables searching of Employees by
		// FirstName, LastName (or both)
		Map = employees => from employee in employees
						   select new
							{
								FirstName = employee.FirstName,
								LastName = employee.LastName
							};
	}
}


Few words about the documentation

The documentation has been divided into few sections:

  • in Indexes you can find all the theory about indexes and querying,
  • Transformers contain information about server-side transformation functions that can shape your query results,
  • in Client API you can find API reference with basic examples for most of the methods available in client. There is also a lot of theory on how things work on client side,
  • Server contains information about administration, maintenance, configuration, installation, and troubleshooting of the server,
  • Studio - go there if you want to check what can be done using the Studio

Samples

The following sample applications are available:

Playground Server

Please visit this dedicated article if you are interested in this topic.