Cayenne User Documentation
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.

### Sections

1. Parameterized Queries
2. Qualifier Expressions
3. Using Orderings
4. SelectQuery Customization

.
Copyright ©2001-2008 Apache Software Foundation