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 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 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 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.QueryResults;
  import java.util.Map;

  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...
  });

The second option for processing large result sets is to use the fetchAll() method which will return a paging iterator which will internally perform queries to fetch the next set of results to process. A code example is provided below:


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

  QueryResults results = Documents.collection("customers")
      .query()
      .fetchAll();

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

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Query.QueryResults<T>`	Provides a Query Result class.
`static class`	`Query.ResultDoc<T>`	Provides a Query Result Document class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Query.QueryResults<T>`	`fetch()`	Perform the Query operation and return the fetched results.
`Query.QueryResults<T>`	`fetchAll()`	Perform the Query operation and return all 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.
`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 Query.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.
  - fetchAll
```
public Query.QueryResults<T> fetchAll()
```
    Perform the Query operation and return all the fetched results. The QueryResults iterator will continue to process all the pages of results until no more are available from the server. If no fetch limit is specified, this method will set the query fetch limit to 1000.
    
    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

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

where

where

where

where

pagingFrom

limit

fetch

fetchAll

toString