What is RQL?
RQL, the Raven Query Language, is a SQL-like language used to retrieve the data from the server when queries are being executed. It is designed to expose externally the RavenDB query pipeline in a way that is easy to understand, easy to use and not overwhelming to the user.
Keywords and methods
Following keywords and methods are available in RQL:
- ORDER BY
With following operators:
- <> or !=
- = or ==
- ALL IN
And following values:
- string e.g. 'John' or "John"
- number (long and double) e.g. 17
- parameter e.g. $param1
declare gives you the ability to create a JS function that can be reused in
select (when projection is done). You can read more about it here.
from is used to determine the source data that should be used when query is executed. We have two options here:
This option is used to perform:
- Collection queries that are doing basic ID filtering only e.q.
from Companies where id() == 'companies/1-A'where there is no need to query an index, we can return the document from the storage directly,
Dynamic queries that are being executed against Auto Index
from INDEX <index-name>
This option is used to perform RQL operations against a given [static index].
where is used to filter-out the documents from final results.
Operator: >= <= <> != < > = ==
The operators above are considered basic and self-explanatory. They work on all value types including 'numbers' and 'strings'.
The simplest example would be to return results with field value equal to a given input e.g. if we want to return a document from
@companies collection (more about collection can be read here) you need to execute following query:
from Companies where Name = 'The Big Cheese'
between returns results inclusively and the type of border values used must match. It works on both 'numbers' and 'strings' and can be substituted with
<= operators (see the example below).
from Products where PricePerUnit between 10.5 and 13.0
from Products where PricePerUnit >= 10.5 and PricePerUnit <= 13.0
in is validating if a given field contains passed values. It will return results if a given field matches any of the passed values.
from Companies where Name IN ('The Big Cheese', 'Unknown company name')
from Orders where Lines.ProductName in ('Chang', 'Spegesild', 'Unknown product name')
Operator: ALL IN
This operator checks if all passes values are matching given field. Due to its mechanics it is only usefull when used on array fields.
Following query will yield no results in contrast to 'in' operator.
from Orders where Lines.ProductName all in ('Chang', 'Spegesild', 'Unknown product name')
but removing the 'Unknown product name' will give you Orders that only contains products with both 'Chang' and 'Spegesild' names
from Orders where Lines.ProductName all in ('Chang', 'Spegesild')
Binary operators: AND OR NOT
Binary operators can be used to build more complex statements. The
NOT operator can only be used with one of the other binary operators creating
OR NOT or
AND NOT ones.
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
Subclauses: ( )
Subcluses can be used along with binary operators to build even more complex logical statements and are self-explanatory so no example will be given.
To perform sorting
order by must be used. If you are interested in this subject, please read our dedicated sorting article that can be found here.
When there is a need to use data from external document in projection
load can be used. Please refer to following projection article to find out more about it.
Projections can be performed by using
select. Please read our dedicated projection article that can be found here.
To patch documents on server-side use
update with desired JS script that will be applied to any documents matching the query criteria. Please refer to our patching article for more information.
include has been introduced to support attaching additional documents to the query response. Dedicated article that tackles this subject can be found here.