Querying: Basics

Indexes are used by RavenDB to satisfy queries.

Query-Flow

Each query in RavenDB must be expressed by RQL, our query language. Each query must match an index in order to return the results. The full query flow is as follows:

1. from index | collection

   • First step. When a query is issued, it locates the appropriate index. If our query specifies that index, the task is simple - use this index. Otherwise, a query analysis takes place and an auto-index is created.

2. where

   • When we have our index, we scan it for records that match the query predicate.

3. load

   • If a query contains a projection that requires any document loads to be processed, they are done just before projection is executed.

4. select

   • From each record, the server extracts the appropriate fields. It always extracts the id() field (stored by default).

   • If a query is not a projection query, then we load a document from storage. Otherwise, if we stored all requested fields in the index, we use them and continue. If not, the document is loaded from storage and the missing fields are fetched from it.

   • If a query indicates that projection should be used, then all results that were not filtered out are processed by that projection. Fields defined in the projection are extracted from the index (if stored).

5. include

   • If any includes are defined, then the results are being traversed to extract the IDs of potential documents to include with the results.

6. Return results.

Querying Using LINQ

RavenDB Client supports querying using LINQ. This functionality can be accessed using the session Query method, and is the most common and basic method for querying the database.

Example I

Let's execute our first query and return all the employees from the Northwind database. To do that, we need to have a document store and opened session and specify a collection type that we want to query (in our case Employees) by passing Employee as a generic parameter to the Query method:

// load all entities from 'Employees' collection
IList<Employee> results = session
    .Query<Employee>()
    .ToList(); // send query

// load all entities from 'Employees' collection
IList<Employee> results = await asyncSession
    .Query<Employee>()
    .ToListAsync(); // send query

from Employees

By specifying Employee as a type parameter, we are also defining a result type.

Example II - Filtering

To filter the results, use the suitable LINQ method, like Where:

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
IList<Employee> results = session
    .Query<Employee>()
    .Where(x => x.FirstName == "Robert")
    .ToList(); // send query

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
IList<Employee> results = await asyncSession
    .Query<Employee>()
    .Where(x => x.FirstName == "Robert")
    .ToListAsync(); // send query

from Employees
where FirstName = 'Robert'

// load up entity from 'Employees' collection
// with ID matching 'employees/1-A'
Employee result = session
    .Query<Employee>()
    .Where(x => x.Id == "employees/1-A")
    .FirstOrDefault(); // send query

// load up entity from 'Employees' collection
// with ID matching 'employees/1-A'
Employee result = await asyncSession
    .Query<Employee>()
    .Where(x => x.Id == "employees/1-A")
    .FirstOrDefaultAsync(); // send query

from Employees
where id() = 'employees/1-A'

You can read more about filtering here.

Example III - Paging

Paging is very simple. The methods Take and Skip can be used:

// load up to 10 entities from 'Products' collection
// where there are more than 10 units in stock
// skip first 5 results
IList<Product> results = session
    .Query<Product>()
    .Where(x => x.UnitsInStock > 10)
    .Skip(5)
    .Take(10)
    .ToList(); // send query

// load up to 10 entities from 'Products' collection
// where there are more than 10 units in stock
// skip first 5 results
IList<Product> results = await asyncSession
    .Query<Product>()
    .Where(x => x.UnitsInStock > 10)
    .Skip(5)
    .Take(10)
    .ToListAsync(); // send query

You can read more about paging here.

Example IV - Querying a Specified Index

In the above examples, we did not specify an index that we want to query. RavenDB will try to locate an appropriate index or create a new one. You can read more about creating indexes here.

In order to specify an index, we need to pass it as a second generic parameter to the Query method or pass the index name as a parameter.

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = session
    .Query<Employee, Employees_ByFirstName>()
    .Where(x => x.FirstName == "Robert")
    .ToList(); // send query

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = await asyncSession
    .Query<Employee, Employees_ByFirstName>()
    .Where(x => x.FirstName == "Robert")
    .ToListAsync(); // send query

from index 'Employees/ByFirstName' 
where FirstName = 'Robert'

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = session
    .Query<Employee>("Employees/ByFirstName")
    .Where(x => x.FirstName == "Robert")
    .ToList(); // send query

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = await asyncSession
    .Query<Employee>("Employees/ByFirstName")
    .Where(x => x.FirstName == "Robert")
    .ToListAsync(); // send query

from index 'Employees/ByFirstName' 
where FirstName = 'Robert'

Low-Level Query Access

To take full control over your queries, we introduced a DocumentQuery method that is available in advanced session operations. It is a low-level access to the querying mechanism the user can take advantage of to shape queries according to his needs.

Example

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = session
    .Advanced
    .DocumentQuery<Employee, Employees_ByFirstName>()
    .WhereEquals(x => x.FirstName, "Robert")
    .ToList(); // send query

// load all entities from 'Employees' collection
// where 'FirstName' is 'Robert'
// using 'Employees/ByFirstName' index
IList<Employee> results = await asyncSession
    .Advanced
    .AsyncDocumentQuery<Employee, Employees_ByFirstName>()
    .WhereEquals(x => x.FirstName, "Robert")
    .ToListAsync(); // send query

from index 'Employees/ByFirstName' 
where FirstName = 'Robert'

Remarks