see on GitHub

Session : Querying : How to Query

This session explains the following methods to query a database:

  • session.Query
  • session.Advanced.DocumentQuery
  • session.Advanced.RawQuery

Session.Query

The most straightforward way to issue a query is by using the Query method which allows you to define queries using LINQ. In order to take advantage of querying capabilities specific for RavenDB, the querying API provides extension methods that will be described later.

Syntax

IRavenQueryable<T> Query<T>(string indexName = null, string collectionName = null,
                            bool isMapReduce = false);

IRavenQueryable<T> Query<T, TIndexCreator>()
    where TIndexCreator : AbstractIndexCreationTask, new();

Parameters
indexName string Name of an index to perform a query on (mutually exclusive with collectionName)
collectionName string Name of a collection (mutually exclusive with indexName)
isMapReduce bool Indicates if queried index is a map/reduce index (modifies how we treat identifier properties)
Return Value
IRavenQueryable Instance implementing IRavenQueryable interface containing additional query methods and extensions

Example I - Basic Dynamic Query

// load all entities from 'Employees' collection
List<Employee> employees = session
    .Query<Employee>()
    .ToList();
// load all entities from 'Employees' collection
List<Employee> employees = await asyncSession
    .Query<Employee>()
    .ToListAsync();

The above is an example of a dynamic query which doesn't require you to specify an index name. RavenDB will create an auto index automatically if necessary.

The provided Employee type as the generic type parameter does not only define the type of returned results, but it also indicates that the queried collection will be Employees. There is no need to specify it as the parameter.

Example II - LINQ Syntax Support

Both LINQ syntaxes are supported:

  • Method syntax:

// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
List<Employee> employees = session
    .Query<Employee>()
    .Where(x => x.FirstName == "Robert")
    .ToList();
// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
List<Employee> employees = await asyncSession
    .Query<Employee>()
    .Where(x => x.FirstName == "Robert")
    .ToListAsync();

  • Query syntax:

// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
IRavenQueryable<Employee> query = from employee in session.Query<Employee>()
                                  where employee.FirstName == "Robert"
                                  select employee;

List<Employee> employees = query.ToList();
// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
IRavenQueryable<Employee> query = from employee in asyncSession.Query<Employee>()
                                  where employee.FirstName == "Robert"
                                  select employee;

List<Employee> employees = await query.ToListAsync();

Example III - Using Specific Index

// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
// using 'Employees/ByName' index
IRavenQueryable<Employee> query = from employee in session.Query<Employee>("Employees/ByName")
                                  where employee.FirstName == "Robert"
                                  select employee;

List<Employee> employees = query.ToList();
// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
// using 'Employees/ByName' index
IRavenQueryable<Employee> query = from employee in asyncSession.Query<Employee>("Employees/ByName")
                                  where employee.FirstName == "Robert"
                                  select employee;

List<Employee> employees = await query.ToListAsync();

or

// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
// using 'Employees/ByName' index
List<Employee> query = (from employee in session.Query<Employee, Employees_ByName>()
                        where employee.FirstName == "Robert"
                        select employee).ToList();
// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
// using 'Employees/ByName' index
List<Employee> query = await (from employee in asyncSession.Query<Employee, Employees_ByName>()
                              where employee.FirstName == "Robert"
                              select employee).ToListAsync();

Session.Advanced.DocumentQuery

The advanced querying methods accessible by session.Advanced.DocumentQuery is the low-level API used to query RavenDB. The entire LINQ API is the wrapper of DocumentQuery API and each query created using LINQ is built on top of it. Since it offers the full spectrum of querying capabilities, you might find it handy when doing very complex queries that are difficult to shape using Linq.

Example IV

// load all employees hired between
// 1/1/2002 and 12/31/2002
List<Employee> employees = session
    .Advanced.DocumentQuery<Employee>()
    .WhereBetween(x => x.HiredAt, new DateTime(2002, 1, 1), new DateTime(2002, 12, 31))
    .ToList();
// load all employees hired between
// 1/1/2002 and 12/31/2002
List<Employee> employees = await asyncSession
    .Advanced.AsyncDocumentQuery<Employee>()
    .WhereBetween(x => x.HiredAt, new DateTime(2002, 1, 1), new DateTime(2002, 12, 31))
    .ToListAsync();

Session.Advanced.RawQuery

Queries in RavenDB use a SQL-like language called RavenDB Query Language (RQL). All of the above queries generate RQL sent to the server. The session also gives you the way to express the query directly in RQL using RawQuery method.

Example IV

// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
List<Employee> employees = session
    .Advanced.RawQuery<Employee>("from Employees where FirstName = 'Robert'")
    .ToList();
// load all entities from 'Employees' collection
// where FirstName equals 'Robert'
List<Employee> employees = await asyncSession
    .Advanced.AsyncRawQuery<Employee>("from Employees where FirstName = 'Robert'")
    .ToListAsync();

Custom Methods and Extensions for LINQ

Available custom methods and extensions: