Welcome to this introductory article that will guide you through all the parts of RavenDB needed for basic understanding and simple setup.
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.
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);
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.
/// 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
public class Employees_ByFirstNameAndLastName : AbstractIndexCreationTask<Employee>
// 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
FirstName = employee.FirstName,
LastName = employee.LastName
Few words about the documentation
The documentation has been divided into few sections:
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,
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:
Please visit this dedicated article if you are interested in this topic.