Query vs DocumentQuery



API support

Query:

  • The Query API supports LINQ, the essential data access solution in .NET.

  • The API exposed by the Query method is a wrapper of DocumentQuery and is built on top of it.

  • When using Query, the query is translated into a DocumentQuery object,
    which then builds into an RQL that is sent to the server.

  • The available Query methods and extensions are listed here.


DocumentQuery:

  • DocumentQuery does Not support LINQ.

  • It exposes a lower-level API that provides more flexibility and control when building a query.

  • When using DocumentQuery, the query is translated into an RQL that is sent to the server.

  • The available DocumentQuery methods and extensions are listed here.


Note:

Query and DocumentQuery can be converted to one another.
This enables you to take advantage of all available API methods & extensions.
See Convert between DocumentQuery and Query.

Immutability

  • Query is immutable while DocumentQuery is mutable.
    You might get different results if you try to reuse a query.

  • The usage of the Query method in the following example:

    IRavenQueryable<User> query = session
        .Query<User>()
        .Where(x => x.Name.StartsWith("A"));
    
    IRavenQueryable<User> ageQuery = query
        .Where(x => x.Age > 21);
    
    IRavenQueryable<User> eyeQuery = query
        .Where(x => x.EyeColor == "blue");

    will result with the following Lucene-syntax queries:

    query: from Users where startsWith(Name, 'A')

    ageQuery: from Users where startsWith(Name, 'A') and Age > 21

    eyeQuery: from Users where startsWith(Name, 'A') and EyeColor = 'blue'


  • A similar usage with DocumentQuery:

    IDocumentQuery<User> documentQuery = session
        .Advanced
        .DocumentQuery<User>()
        .WhereStartsWith(x => x.Name, "A");
    
    IDocumentQuery<User> ageDocumentQuery = documentQuery
        .WhereGreaterThan(x => x.Age, 21);
    
    IDocumentQuery<User> eyeDocumentQuery = documentQuery
        .WhereEquals(x => x.EyeColor, "blue");
    
    // Here all of the DocumentQuery variables have the same reference

    will result with the following Lucene queries:

    documentQuery: from Users where startsWith(Name, 'A')
    (before creating ageDocumentQuery)

    ageDocumentQuery: from Users where startsWith(Name, 'A') and Age > 21
    (before creating eyeDocumentQuery)

    eyeDocumentuery: from Users where startsWith(Name, 'A') and Age > 21 and EyeColor = 'blue'

    All created Lucene queries are the same query (actually the same instance).
    This is an important hint to be aware of if you are going to reuse DocumentQuery.

Default Query Operator

  • Starting from version 4.0, both Query and DocumentQuery use AND as the default operator.
    (Previously, Query used AND and DocumentQuery used OR).

  • This behavior can be modified by calling UsingDefaultOperator:

session
    .Advanced
    .DocumentQuery<User>()
    .UsingDefaultOperator(QueryOperator.Or);