OverviewΒΆ

The Query API provides several methods for specifying the types of objects to be retrieved, for filtering results, and for executing actions on retrieved objects. A typical Dari query is expressed as a chain of methods, as shown in this diagram of a basic query. Note that the API methods correspond to SQL clauses, described in the table that follows.

../../_images/query-diagram.svg
Query Clause Description

from<class>

Specifies the class type on which to search for instances. The following query creates a Query object that retrieves all Article objects:
Query<Article> query = Query.from(Article.class);

There are several from-related methods that specify the object type to search for. See FROM.

where<predicate>
Specifies predicates to filter search results. You can express conditions with comparison, compound, and other operators.
The following query retrieves an Article object with the specified headline:
Query<Article> query = Query.from(Article.class).where(headline = "Marshmallow Dreams");

Alternatively, you can express conditions using predicate objects instead of string operators.

To express predicates with object operands, you can use bind variables and object references to simply your query constructs.

and |
or |
not<predicate>
Represents logical operations AND, OR, NOT to combine additional predicates with the predicate expressed in the where clause.
The following query retrieves an Article object with one of two specified headlines:
Query<Article> query = Query.from(Article.class).where(headline = "Marshmallow Dreams").or(headline = "Cotton Candy Fantasies");
sortAscending |
sortDescending<field>
Sorts results by field, in ascending or descending order.
The following query sorts Author objects in ascending alphabetical order by last name:
List<Author> authors = Query.from(Author.class).sortAscending("lastName");

There are several sort-related methods. See Sorting.

selectAll() | first()
Specifies the objects to be selected from the query results. See FROM.
selectAll() selects all instances retrieved by the query, for example:
List<Article> articles = Query.from(Article.class).selectAll();
first() selects only the first instance retrieved by the query, for example:
Article article = Query.from(Article.class).first();
select<range>
Specifies the number of instances to return in a paginated result.
The following query limits the number of articles returned at any one time to 100, referenced in a PaginatedResult object.
PaginatedResult<Article> results =  Query.from(Article.class).select(0, 99);
Subsequent calls can be made on PaginatedResult to return additional batches of articles.
groupBy<fields>
Groups retrieved objects by field, with objects with the same field value placed into the same grouping.
The following query groups the articles returned by author field, with articles by the same author grouped together.
List<Grouping<Article>> groupings = Query.from(Article.class).groupBy("author");

The Query API includes methods to retrieve objects as reference-only. For more information, see Advanced.