Title: SelectQuery

The most commonly used query is SelectQuery. It is a descriptor that allows DataContext to fetch lists of DataObjects of the right type matching the specified criteria. SelectQuery together with the DataMap provides just enough information to the Cayenne runtime objects to build the right SQL SELECT statement and control various execution parameters.

SelectQuery Parts

A SelectQuery consists of a root object, qualifier expression and orderings list. Here is a logical correspondence of Cayenne SelectQuery parts and SQL constructs:

Cayenne SelectQuery	SQL SELECT statement	Required
Root	FROM clause	yes
Qualifier Expression	WHERE clause	no
Orderings	ORDER BY clause	no

The only required query part is root. Query root tells Cayenne what kind of objects to fetch. It can be one of the following:

(most commonly used) Java class for the type of persistent objects in question.
ObjEntity that provides the mapping for the class in question.
A String that is an ObjEntity name.

SelectQuery provides constructors for all three types. For example:

import org.apache.cayenne.query.SelectQuery;
...
// this is a valid Cayenne query that would allow to fetch
// all records from the ARTIST table as Artist objects
SelectQuery query = new SelectQuery(Artist.class);

Other components of the SelectQuery are discussed in the following sections.

Executing SelectQueries

As mentioned earlier, queries are executed via DataContext.performQuery(). For instance to fetch all Artists existing in the database the following code is used:

import org.apache.cayenne.query.SelectQuery;
import org.apache.cayenne.access.DataContext;
import java.util.List;
...
DataContext ctxt; // assume this exists
SelectQuery query = new SelectQuery(Artist.class);

// The query would fetch *ALL* rows from the ARTIST table
// The list returned contains Artist objects, one object per row
List artists = ctxt.performQuery(query);

There is a special case when a query is run using DataContext.performIteratedQuery(). This is discussed in "Performance Tuning" chapter.