Queries are Cayenne abstraction for communicating with an external data storage. Queries are Java objects that are generally independent from the SQL dialect used by the target database. Cayenne includes a number of standard queries in the org.apache.cayenne.query package. Many of them are only used internally. Here we describe the queries that can be useful in the application.

General Purpose Queries

  • SelectQuery is an "object query" based on some Java class. All its parameters are specified in terms of the properties of this Java class. It is completely portable and SQL-free. SelectQuery is the most commonly used out of the three queries discussed here, as it stays as close to the object model as possible. For most tasks it should be considered the first choice. Other types of queries should be used only if SelectQuery can't address a particular application need.
  • SQLTemplate Query is a scriptable raw SQL query, that can be both selecting and non-selecting. Main use of SQLTemplate is to create complex SQL queries with structure that has no direct correspondence with the object model. SQLTemplate allows customizing SQL dialect code for more than one target database, encapsulating this fact from the callers. Just like other types of queries, SQLTemplates can be mapped in CayenneModeler, so the code can stay free from SQL building.
  • ProcedureQuery is intended to invoke mapped stored procedures. It can be selecting or non-selecting, or even contain multiple result sets and update counts, depending on what the target procedure does.
  • EJBQLQuery is an object query with a SQL-like syntax standardized by the JPA specification. It is a SelectQuery on steroids.

Other Helpful Queries

  • QueryChain is a Query that is itself a collection of other queries. Its intention is to execute multiple queries in a single batch.
  • ObjectIdQuery is a query that selects objects matching an ObjectId.
  • RelationshipQuery is a query that fetches object(s) related to a single given object via a mapped ObjRelationship.
  • NamedQuery is a query that is a reference to another query stored in the DataMap.

Custom Queries

To extend standard Query functionality, users can create Custom Queries that implement org.apache.cayenne.query.Query interface.


  1. SelectQuery
  2. SQLTemplate Query
  3. EJBQLQuery
  4. NamedQuery
  5. ObjectIdQuery
  6. QueryChain
  7. RelationshipQuery
  8. Storing Queries in DataMap
  9. Caching Query Results
  10. Customizing Queries