java.lang.Object
- io.nitric.api.document.Query<T>

public class Query<T>
extends Object

Provides a Document Query class.

Query Examples

The example below illustrates using the Document Query class.


  import io.nitric.api.document.Documents;
  import io.nitric.api.document.Key;
  import io.nitric.api.document.QueryResults;
  import java.util.Map;

  // Fetch the first 100 customers
  QueryResults results = Documents.collection("customers")
      .query()
      .limit(100)
      .fetch();

  // Process results
  results.foreach(doc -> {
      Key key = doc.getKey();
      Map customer = doc.getContent();
  });

In the example a QueryResults object is returned. The QueryResults performs a lazy execution of the where when it is iterated over in the foreach. The query results also return a typed ResultDoc object which provides access to the documents content and key.

To use typed results content class, specify the content type in the query method. The example code marshals the document contents into the specified Customer class. If a query type is not specified a Map type is used.


  import io.nitric.api.document.Documents;
  import io.nitric.api.document.QueryResults;
  import com.example.entity.Customer;

  QueryResults<Customer> results = Documents.collection("customers")
      .query(Customer.class)
      .fetch();

  results.foreach(doc -> {
      Customer customer = doc.getContent();
  });

Sub Collection Queries

You can create a sub collection query under a top level collection or a top level collection document. For example:


  import io.nitric.api.document.Documents;
  import io.nitric.api.document.QueryResults;
  import com.example.entity.Order;

  // Fetch all customers orders
  QueryResults results = Documents.collection("customers").collection("orders")
      .query(Order.class)
      .fetch();

  results.foreach(doc -> {
      Order order = doc.getContent();
  });

  // Fetch all orders for a specific customer
  QueryResults<Order> results = Documents.collection("customers").doc("[email protected]")
      .collection("orders")
      .query(Order.class)
      .fetch();

  results.foreach(doc -> {
      Order order = doc.getContent();
  });

Where Filter Expressions

The Query class supports chaining where clause filter expressions. All where clauses are explicitly AND together.


  import io.nitric.api.document.Documents;
  import io.nitric.api.document.QueryResults;

  // Fetch all the customers based in US which are active and over 21
  QueryResults results = Documents.collection("customers")
      .query()
      .where("status", "==", "active")
      .where("country", "==", "US")
      .where("age", ">", "21")
      .fetch();

The available where clause operators are provide listed below:

Operator	Description	Example
`==`	Equals	`.where("status", "==", "active")`
`<`	Less Than	`.where("count", "<", 10)`
`>`	Greater Than	`.where("price", ">", 100.0)`
`<=`	Less Than or Equals	`.where("count", "<", 10)`
`>=`	Greater Than or Equals	`.where("price", ">=", 50.0)`
`startsWith`	Starts With	`.where("type", "startsWith", "Inverter/Hybrid")`

Large Result Sets

When processing large result sets the Query API provides two options. The first option is to use the stream() method which will return ResultDoc Stream object. This stream will internally make further Document Service query calls until there are no more results available from the server.


  import java.util.stream.Stream;
  import io.nitric.api.document.Documents;
  import io.nitric.api.document.ResultDoc;

  Stream<ResultDoc<Map>> stream = Documents.collection("customers")
      .query()
      .stream();

  stream.foreach(doc -> {
      // Process results...
  });

The second option form processing large result sets is to use a paginated query where you pass pagingToken from the previous query results to the next query to continue. This technique is useful for paged user experiences. An example is provided below:


  import io.nitric.api.document.Documents;
  import io.nitric.api.document.Query;
  import io.nitric.api.document.QueryResults;

  Query query = Documents.collection("customers")
      .query()
      .where("status", "==", "active")
      .limit(100);

  QueryResults results = query().fetch();

  // Fetch the first page of 100 customers
  results.foreach(doc -> {
      // Process results...
  });

  // Fetch next page of 100 results
  Map pagingToken = results.getPagingToken()

  results = query().pagingFrom(pagingToken).fetch();

  results.foreach(doc -> {
      // Process results...
  });

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`QueryResults<T>`	`fetch()`	Perform the Query operation and return the fetched results.
`Query<T>`	`limit(int limit)`	Set the query fetch limit.
`Query<T>`	`pagingFrom(Map<String,String> pagingToken)`	Set the query paging continuation token.
`Stream<ResultDoc<T>>`	`stream()`	Perform the Query operation and return a Stream object.
`String`	`toString()`	Return the string representation of this object.
`Query<T>`	`where(String operand, String operator, Boolean value)`	Add a where expression to the query.
`Query<T>`	`where(String operand, String operator, Double value)`	Add a where expression to the query.
`Query<T>`	`where(String operand, String operator, Integer value)`	Add a where expression to the query.
`Query<T>`	`where(String operand, String operator, String value)`	Add a where expression to the query.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - where
```
public Query<T> where(String operand,
                      String operator,
                      String value)
```
    Add a where expression to the query. Valid expression operators include: == , < , > , <= , >= , startsWith
    
    Queries with multiple where() expressions are implicitly AND together when executed.
    
    Parameters:
    
    operand - the left-hand side expression operand (required)
    
    operator - the query expression operator (required)
    
    value - the right-hand side operand (required)
    
    Returns:
    
    the Query operation
  - where
```
public Query<T> where(String operand,
                      String operator,
                      Double value)
```
    Add a where expression to the query. Valid expression operators include: == , < , > , <= , >= , startsWith
    
    Queries with multiple where() expressions are implicitly AND together when executed.
    
    Parameters:
    
    operand - the left hand side expression operand (required)
    
    operator - the query expression operator (required)
    
    value - the right hand side operand (required)
    
    Returns:
    
    the Query operation
  - where
```
public Query<T> where(String operand,
                      String operator,
                      Integer value)
```
    Add a where expression to the query. Valid expression operators include: == , < , > , <= , >= , startsWith
    
    Queries with multiple where() expressions are implicitly AND together when executed.
    
    Parameters:
    
    operand - the left hand side expression operand (required)
    
    operator - the query expression operator (required)
    
    value - the right hand side operand (required)
    
    Returns:
    
    the Query operation
  - where
```
public Query<T> where(String operand,
                      String operator,
                      Boolean value)
```
    Add a where expression to the query. Valid expression operators include: == , < , > , <= , >= , startsWith
    
    Queries with multiple where() expressions are implicitly AND together when executed.
    
    Parameters:
    
    operand - the left hand side expression operand (required)
    
    operator - the query expression operator (required)
    
    value - the right hand side operand (required)
    
    Returns:
    
    the Query operation
  - pagingFrom
```
public Query<T> pagingFrom(Map<String,String> pagingToken)
```
    Set the query paging continuation token.
    
    Parameters:
    
    pagingToken - the query paging continuation token
    
    Returns:
    
    the Query operation
  - limit
```
public Query<T> limit(int limit)
```
    Set the query fetch limit.
    
    Parameters:
    
    limit - the query fetch limit
    
    Returns:
    
    the Query operation
  - fetch
```
public QueryResults<T> fetch()
```
    Perform the Query operation and return the fetched results. If a fetch limit is specified then only the specified number of items will be returned. If a pagingToken is also specified then the results will be for the next page of results from the token offset.
    
    Returns:
    
    the Query operations fetched results.
  - stream
```
public Stream<ResultDoc<T>> stream()
```
    Perform the Query operation and return a Stream object. If no fetch limit is specified this stream() object will continue to perform Document Service queries until there are not more results available from the server.
    
    Returns:
    
    the Query operations fetched results
  - toString
```
public String toString()
```
    Return the string representation of this object.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the string representation of this object

Class Query<T>

Query Examples

Sub Collection Queries

Where Filter Expressions

Large Result Sets

Method Summary

Methods inherited from class java.lang.Object

Method Detail

where

where

where

where

pagingFrom

limit

fetch

stream

toString