Querying

The Query API is an abstraction layer that provides a single query syntax regardless of the underlying database type. Queries are represented by instances of the Query class. This class will look familiar if you have used SQL before.

You can use the Code Editor to test queries. For additional debugging functionality, see the Database Query Tool.

Overview of querying with Dari

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. The API methods correspond to SQL clauses, described in the table that follows.

Query.from(<class>)
    .where(<predicate>)
    .and | .or | .not (<predicate>)
    .sortAscending | .sortDescending
    .selectAll | .first()
    /* OR */
    .select(<range>)
    /* OR */
    .groupBy<fields>

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 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 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 simplify 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 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 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 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 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> groupings = Query.from(Article.class).groupBy("author");

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 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 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 simplify 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 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 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 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 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> groupings = Query.from(Article.class).groupBy("author");

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

Previous Topic

Configuring StorageItem

Next Topic

FROM