see on GitHub

Full query syntax

A full query syntax is a combination of a Lucene syntax and RavenDB-specific extensions. This article describes Raven flavored options which a user can use to construct index queries. The syntax that is presented here can by used to query by using either HTTP API or Client API (Query, DocumentQuery methods and Commands).

Tokenized values

If you want to execute a query by using a field that was marked as NotAnalyzed in the index definition and your intention is to do an exact match, you have to tokenize it by using the following syntax:

FieldName:[[Value]]
It will cause that on the server side such field will be treated as not analyzed by a Lucene analyzer and will look for exact match of the query.

Example I

To get all documents from Users collection by using the Raven/DocumentsByEntityName index use the query:

Tag:[[Users]]

There are also two reserved tokenized values [[NULL_VALUE]] and [[EMPTY_STRING]] that denotes respectively null and string.Empty values.

Example II

In order to get users that have a null or empty name specify the query:

Name:[[NULL_VALUE]] OR Name:[[EMPTY_STRING]]

Querying nested properties

If a document stored in a database contains an another object you need to use a . (dot) operator to query by using a nested value.

Example

The sample document:

{
    "FullName" : {
        "FirstName" : "John",
        "LastName" : "Smith"
    }
}

The query:

FullName.FirstName:John

Quering collections

For querying into collections use a , (comma) operator.

Example

The sample document:

{
    "Tags" : [
        {
            "Name" : "sport"
        },
        {
            "Name" : "tv"
        }
    ]
}

The query:

Tags,Name:sport

Numeric values

If an indexed value is numeric then RavenDB will create two fields in the Lucene index. In the first one the numeric value will be stored as a not analyzed string while the second one will have a _Range suffix and have a numeric form in order to allow to perform a range query.

Example I

If you want to query by the exact value just create the query as usual:

Age:20

The query above will return all users that are 20 years old.

Example II

If you need specify a range of the value then add the mentioned prefix to the property name that you are interested in. For example to ask for users whose age is greater than 20 we need to create the following query:

Age_Range:{20 TO NULL}

Information

The syntax for range queries is the same like in Lucene. Inclusive range queries are denoted by square brackets. Exclusive range queries are denoted by curly brackets.

ISO dates parsing

RavenDB supports parsing dates in ISO standard.

Example

In order to get all users that were born between 1/1/1980 and 12/31/1999 use the following query:

DateOfBirth:[1980-01-01 TO 1999-12-31T00:00:00.0000000]

Note that we can use date only (1980-01-01) as well as pass it together with time (1999-12-31T00:00:00.0000000).

Suggestions over multiple words

By default RavenDB support suggestions by using single search term. However if you need to find suggestions by using multiple words you have to use extended suggestion query syntax:

<<word1 word2>>

or

(word1 word2)

You can provide any number of the words, the expected term separators are: '  ' (space), '\t', '\r', '\n'.

Query methods

@in

In order to specify multiple values in Where clause an operator @in was introduced. Its syntax looks as follow:

@in<FieldName>:(value1, value2)

You can specify any number of parameters that you are looking for. The , (comma) character is a separator of the values.

Example I

@in<Age>:(20, 25)

The result of the query above will be users that are 20 or 25 years old.

Example II

In order to specify a phrase (i.e. when search term contains whitespaces) wrap it by using \\". If you need to escape a comma character, wrap it by using grave accent (`) character. For example apply the following query to Users/ByVisitedCountries index:

@in<VisitedCountries>:(\"Australia`,`Canada\", Israel)

This will cause the exact search for string values "Australia, Canada" or "Israel".

Information

The operator @in is used internally by WhereIn method. If the specified list of values is empty then instead of @in the following expression is created @emptyIn<FieldName>:(no-results) to handle such cases.