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:

• Distribution package or installer which can be downloaded from ravendb.net
• NuGet 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:

• Bundles - contains all non built-in plugins e.g. Authorization or Encryption,
• Client - contains all .NET client libraries needed for development,
• Server - contains all server files (including configuration files such as Raven.Server.exe.config)
• Web - contains all files needed for IIS deployment

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.

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:

• What is a document store?
• Creating a document store
• Setting up a default database

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:

• What is a session and how does it work? and Opening a session
• What are commands?

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:

• What are indexes?
• Creating and deploying indexes
• Indexing basics
• Map indexes

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:

• MVC Starter Kit

Playground Server

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