see on GitHub

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:


In RavenDB 3.5 we had the distribution package split into two ZIP packages to make things more comfortable and have a separate Tools package.

Now, we will focus on the distribution package (if you want to read about the installer go here).
There are 2 zip files available, the main zip contains the following:

The package contains 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.

The second zip file called Tools is for advanced users and contains the following:

  • Raven.Backup.exe - A utility for doing backups, read more.
  • Raven.Smuggler.exe - A utility for exporting and importing data between servers, read more.
  • Raven.Monitor.exe - A utility for monitoring RavenDB I/O disk rates, read more.
  • Raven.StorageExporter.exe - A utility for exporting a database directly from the Esent / Voron data files, read more.
  • Raven.Traffic.exe - A utility to record and replay requests that are being received by RavenDB, read more.
  • Raven.ApiToken.exe - A utility to generate an ApiToken, not through the studio.


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.


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:


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:


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


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


The following sample applications are available:

Playground Server

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