RQL - Raven Query Language

The query pipeline in RavenDB includes the following main stages:

1. Detect query source (from)

   • Based on your query, RavenDB will determine the appropriate data source from which to retrieve results.

   • Note: all queries in RavenDB use an index to provide results, even when you don't specify one.

   • The following options are available:

     • from index - Explicitly specify which index to use.

     • from collection - Specify the collection to query.
       RavenDB will decide which index will be used depending on the query criteria.

   • Learn more about these query scenarios in this Query Overview.

2. Filter the data (where)

   • The index is scanned for records that match the query predicate.

3. Include related documents (include)

   • Related documents that are included in the query will be retrieved and returned to the client
     along with the resulting matching documents, reducing the need to do another network round trip
     to the database when accessing the included documents.

4. Sort results (order by)

   • Query results can be sorted.
     For example, you can order by a field value, by the resulting documents' score, by random ordering, etc.

5. Limit results (limit)

   • You can specify the number of results you want to get back from the query
     and the number of results you want to skip.

6. Project results (select)

   • Projections are specified when you need to retrieve only specific document fields, instead of the whole full document. This reduces the amount of data sent over the network and is useful when only partial data is needed. When projections are Not defined on the query - then the full document content is retrieved from the document storage.

   • Projections are applied as the last stage after the query has been processed, filtered, sorted, and paged.
     This means that the projection doesn't apply to all the documents in the database,
     only to the results that are actually returned.

   • Data can be loaded (load) from related documents to be used in the projected fields.

   • For each record, the server extracts the requested field:
     If a field is stored in the index - the server will fetch it from the index.
     If a field is Not stored in the index - the server will fetch it from the document storage.

7. Return results to the client.

The following keywords and methods are available in RQL:

• DECLARE
• FROM
  • index
• GROUP BY
  • array()
• WHERE
  • id()
  • search()
  • cmpxchg()
  • boost()
  • regex()
  • startsWith()
  • endsWith()
  • lucene()
  • exists()
  • exact()
  • intersect()
  • spatial.within()
  • spatial.contains()
  • spatial.disjoint()
  • spatial.intersects()
  • moreLikeThis()
• ORDER BY
  • ASC | ASCENDING
  • DESC | DESCENDING
  • AS
    • string
    • long
    • double
    • alphaNumeric
  • random()
  • score()
  • spatial.distance()
• LOAD
• SELECT
  • DISTINCT
  • key()
  • sum()
  • count()
  • facet()
  • timeseries()
  • counter()
• LIMIT
• UPDATE
• INCLUDE
• WITH
• MATCH

With the following operators:

• >=
• <=
• <> or !=
• <
• >
• = or ==
• BETWEEN
• IN
• ALL IN
• OR
• AND
• NOT
• (
• )

And the following values:

• true
• false
• null
• string e.g. 'John' or "John"
• number (long and double) e.g. 17
• parameter e.g. $param1

You can use the declare keyword to create a JavaScript function that can then be called from a select clause when using a projection. JavaScript functions add flexibility to your queries as they can be used to manipulate and format retrieved results.

// Declare a JavaScript function 
declare function output(employee) {
    // Format the value that will be returned in the projected field 'FullName'
    var formatName = function(x){ return x.FirstName + " " + x.LastName; };
    return { FullName : formatName(employee) };
}

// Query with projection calling the 'output' JavaScript function
from Employees as employee select output(employee)

Values are returned from a declared Javascript function as a set of values rather than in a nested array to ease the projection of retrieved values. See an example for this usage here.

The keyword from is used to determine the source data that will be used when the query is executed.
The following options are available:

// Full collection query 
// Data source: The raw collection documents (Auto-index is Not created)
from "Employees"

// Collection query - by ID 
// Data source: The raw collection documents (Auto-index is Not created)
from "Employees" where id() = "employees/1-A"

// Dynamic query - with filtering
// Data source: Auto-index (server uses an existing auto-index or creates a new one)
from "Employees" where FirstName = "Laura"

// All collections query
// Data source: All raw collections (Auto-index is Not created)
from @all_docs

// Dynamic query - with filtering 
// Data source: Auto-index (server uses an existing auto-index or creates a new one)
from @all_docs where FirstName = "Laura"

// Index query
// Data source: The specified index
from index "Employees/ByFirstName"

// Index query - with filtering
// Data source: The specified index
from index "Employees/ByFirstName" where FirstName = "Laura"

Use the where keyword with various operators to filter chosen documents from the final result-set.

from "Companies"
where Name = "The Big Cheese" // Can use either '=' or'=='

from "Companies"
where Address.City = "Albuquerque"

from "Products" 
where PricePerUnit between 10.5 and 13.0 // Using between

from "Products" 
where PricePerUnit >= 10.5 and PricePerUnit <= 13.0 // Using >= and <=

from Companies 
where Name in ('The Big Cheese', 'Unknown company name')

from Orders 
where Lines[].ProductName in ('Chang', 'Spegesild', 'Unknown product name')

from "Orders" 
where Lines[].ProductName all in ("Chang", "Spegesild", "Unknown product name")

from "Orders"
where Lines[].ProductName all in ("Chang", "Spegesild")

from "Companies"
where Name = "The Big Cheese" OR Name = "Richter Supermarkt"

from "Orders"
where Freight > 500 AND ShippedAt > '1998-01-01'

from "Orders"
where Freight > 500 AND ShippedAt > '1998-01-01' AND NOT Freight = 830.75

The keyword group by is used to create an aggregation query.
Learn more in dynamic group by queries.

The keyword include has been introduced to support:

• including related documents or counters in the query response
• highlighting results
• get query timings
• get explanations

Use order by to perform sorting.
Learn more in this sorting article.

Use select to have the query return a projection instead of the full document.
Learn more in this projection article.

Use loadwhen you need to use data from a related document in projection.
See an example in this projection article.

Use limit to limit the number of results returned by the query.
Specify the number of items to skip from the beginning of the result set and the number of items to take (return).
This is useful when paging results.

// Available syntax options:
// =========================

from "Products" limit 5, 10       // skip 5, take 10

from "Products" limit 10 offset 5 // skip 5, take 10

from "Products" offset 5          // skip 5, take all the rest

To patch documents on the server-side, use update with the desired JavaScript that will be applied to any document matching the query criteria.
For more information, please refer to this patching article.

The keyword with is used to determine the data source of a graph query.
There are two types of with clauses, regular with and with edges.

• with:    with {from Orders} as o
  The above statement means that the data source referred to by the alias o is the result of the from Orders query.

• with edges:    with edges (Lines) { where Discount >= 0.25 select Product } as cheap
  The above statement means that our data source is the property Lines of the source documents and we filter all lines that match Discount >= 0.25 query.
  The destination referred to by the cheap alias is the product pointed by the Product property of the order line.

The keyword match is used to determine the pattern of a graph query.

match (Orders as o)-[Lines as cheap where Discount >= 0.25 select Product]->(Products as p)
The above statement means that we are searching for a pattern that starts with an order and traverse using the order lines referred to by the Lines property where their Discount property is larger than 25% and the destination is the product referred to by the Product property.

A match may contain an edge in both direction, a right edge would look like so (node1)-[right]->(node2)
and a left one would look like so (node1)<-[left]-(node2).

Any combination of edges is allowed in a match clause e.g.
(node1)-[right]->(node2)<-[left]-(node3)

The above match will actually be translated to:
(node1)-[right]->(node2)
and
(node3)-[left]->(node2)
where the and is a set intersection between the two patterns.