Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Querying/Criteria"

(Functions)
(Functions)
Line 407: Line 407:
 
| <tt>abs</tt>
 
| <tt>abs</tt>
 
| absolute value
 
| absolute value
| <source lang="java">cb.abs(cb.diff(e.<Number>get("salary"), e.get("manager").<Number>get("salary")))</source>
+
| <source lang="java">cb.abs(
 +
    cb.diff(e.<Number>get("salary"), e.get("manager").<Number>get("salary")))</source>
 
|-
 
|-
 
| <tt>selectCase</tt>
 
| <tt>selectCase</tt>
 
| defines a case statement
 
| defines a case statement
| <source lang="java">cb.selectCase(e.get("status")).when(0, "active").when(1, "consultant").otherwise("unknown")</source>
+
| <source lang="java">cb.selectCase(e.get("status")).
<source lang="java">cb.selectCase().when(cb.equal(e.get("status"), 0), "active").when(cb.equal(e.get("status"), 1), "consultant").otherwise("unknown")</source>
+
    when(0, "active").
 +
    when(1, "consultant").
 +
    otherwise("unknown")</source>
 +
<source lang="java">cb.selectCase().
 +
    when(cb.equal(e.get("status"), 0), "active").
 +
    when(cb.equal(e.get("status"), 1), "consultant").
 +
    otherwise("unknown")</source>
 
|-
 
|-
 
| <tt>coalesce</tt>
 
| <tt>coalesce</tt>

Revision as of 15:06, 11 June 2012

EclipseLink JPA

Criteria API

The Java Persistence Criteria API is used to define dynamic queries through the construction of object-based query definition objects, rather than use of the string-based approach of JPQL. The criteria API allows dynamic queries to be built problematically offering better integration with the Java language than a string-based 4th GL approach.

The Criteria API has two modes, the type-safe mode, and the non-typed mode. The type-safe mode uses a set of JPA meta-model generated class to define the query-able attributes of a class. The non-typed mode uses strings to reference attributes of a class.

The criteria API is only for dynamic queries, and cannot be used in meta-data or named queries. Criteria queries are dynamic queries, so are not as performant as static named queries, or even dynamic parametrized JPQL which benefit from EclipseLink's parse cache.

The Criteria API was added in JPA 2.0, and EclipseLink 2.0.

Elug javaspec icon.gif

For more information, see Chapter 6 "Criteria API" in the JPA Specification.

CriteriaBuilder

CriteriaBuilder is the main interface into the Criteria API. A CriteriaBuilder is obtained from an EntityManager or an EntityManagerFactory using the getCriteriaBuilder() API. CriteriaBuilder is used to construct CriteriaQuery objects and their expressions. The Criteria API currently only supports select queries.

CriteriaBuilder defines API to create CriteriaQuery objects:

  • createQuery() - Creates a CriteriaQuery.
  • createQuery(Class) - Creates a CriteriaQuery using generics to avoid casting the result class.
  • createTupleQuery() - Creates a CriteriaQuery that returns map like Tuple objects, instead of object arrays for multiselect queries.

CriteriaBuilder also defines all supported comparison operations and functions used for defining the query's clauses.

CriteriaQuery

CriteriaQuery defines a database select query. A CriteriaQuery models all of the clauses of a JPQL select query. Elements from one CriteriaQuery cannot be used in other CriteriaQuerys. A CriteriaQuery is used with the EntityManager createQuery() API to create a JPA Query.

CriteriaQuery defines the following clauses and options:

  • distinct(boolean) - Defines if the query should filter duplicate results (defaults to false). If a join to a collection relationship is used, distinct should be used to avoid duplicate results.
  • from(Class) - Defines and returns an element in the query's from clause for the entity class. At least one from element is required for the query to be valid.
  • from(EntityType) - Defines and returns an element in the query's from clause for the meta-model entity type. At least one from element is required for the query to be valid.
  • select(Selection) - Defines the query's select clause. If not set, the first root will be selected by default.
  • multiselect(Selection...), multiselect(List<Selection>) - Defines a multi-select query.
  • where(Expression), where(Predicate...) - Defines the query's where clause. By default all instances of the class are selected.
  • orderBy(Order...), orderBy(List<Order>) - Defines the query's order clause. By default the results are not ordered.
  • groupBy(Expression...), groupBy(List<Expression>) - Defines the query's group by clause. By default the results are not grouped.
  • having(Expression), having(Predicate...) - Defines the query's having clause. Having allows grouped results to be filtered.
  • subquery(Class) - Creates a Subquery to be used in one of the other clauses.

The Expressions, Predicates, Order elements are defined using the CriteriaBuilder API and expressions derived from the from Root elements.

CriteriaQuery examples
CriteriaBuilder cb = em.getCriteriaBuilder();
 
// Query for a List of objects.
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.where(cb.greaterThan(e.get("salary"), 100000));
Query query = em.createQuery(cq);
List<Employee> result = query.getResultList();
 
// Query for a single object.
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.where(cb.equal(e.get("id"), cb.parameter(Long.class, "id")));
Query query = em.createQuery(cq);
query.setParameter("id", id);
Employee result2 = (Employee)query.getSingleResult();
 
// Query for a single data element.
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.select(cb.max(e.get("salary")));
Query query = em.createQuery(cq);
BigDecimal result3 = (BigDecimal)query.getSingleResult();
 
// Query for a List of data elements.
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.select(e.get("firstName"));
Query query = em.createQuery(cq);
List<String> result4 = query.getResultList();
 
// Query for a List of element arrays.
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.multiselect(e.get("firstName"), employee.get("lastName"));
Query query = em.createQuery(cq);
List<Object[]> result5 = query.getResultList();

Selection

A Selection define what is selected by a query. A Selection can be any object expression, attribute expression, function, sub-select, constructor or aggregation function. An alias can be defined for a Selection using the alias() API.

Aggregation functions

Aggregation functions can include summary information on a set of objects. These functions can be used to return a single result, or can be used with a groupBy to return multiple results.

Aggregate functions are defined on CriteriaBuilder and include:

  • max(Expression) - Return the maximum value for all of the results. Used for numeric types.
  • greatest(Expression) - Return the maximum value for all of the results. Used for non-numeric types.
  • min(Expression) - Return the minimum value for all of the results. Used for numeric types.
  • least(Expression) - Return the minimum value for all of the results. Used for non-numeric types.
  • avg(Expression) - Return the mean average of all of the results. A Double is returned.
  • sum(Expression) - Return the sum of all of the results.
  • sumAsLong(Expression) - Return the sum of all of the results. A Long is returned.
  • sumAsDouble(Expression) - Return the sum of all of the results. A Double is returned.
  • count(Expression) - Return the count of all of the results. null values are not counted. A Long is returned.
  • countDistinct(Expression) - Return the count of all of the distinct results. null values are not counted. A Long is returned.
CriteriaBuilder cb = em.getCriteriaBuilder();
 
// Count the total employees
CriteriaQuery cq = cb.createQuery();
Root employee = cq.from(Employee.class);
cq.select(cb.count(employee));
Query query = em.createQuery(cq);
List<Employee> result = query.getResultList();
 
// Maximum salary
CriteriaQuery cq = cb.createQuery();
Root employee = cq.from(Employee.class);
cq.select(cb.max(employee.get("salary"));
Query query = em.createQuery(cq);
List<Employee> result = query.getResultList();

Constructors

The construct operator on CriteriaBuilder can be used with a class and values to return data objects from a criteria query. These will not be managed objects, and the class must define a constructor that matches the arguments and types. Constructor queries can be used to select partial data or reporting data on objects, and get back a class instance instead of an object array or tuple.

CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.select(cb.construct(EmpReport.class, e.get("firstName"), e.get("lastName"), e.get("salary")));
Query query = em.createQuery(cq);
List<EmpReport> result = query.getResultList();

From

The query from clause defines what is being queried. The from clause is defined using the from API on CriteriaQuery. A Root object is return from from, which represent the object in the context of the query. A Root also implements From, and Path. From defines a variable in the from clause, and allows joins. Path defines any attribute value and allows traversal to nested attributes.

Root e = cq.from(Employee.class);

Criteria queries allow for multiple root level objects. Caution should be used when doing this, as it can result in Cartesian products of the two table. The where clause should ensure the two objects are joined in some way.

// Select the employees and the mailing addresses that have the same address.
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
Root a = cq.from(MailingAddress.class);
cq.multiselect(e, a);
cq.where(cb.equal(e.get("address"), a.get("address"));
Query query = em.createQuery(cq);
List<Object[]> result = query.getResultList();

Join

A join operation can be used on a From object to obtain a relationship to use in the query. join does not mean the relationships will be fetched, to also fetch the related objects in the result use the fetch operation instead.

Root e = cq.from(Employee.class);
Join a = e.join("address");
cq.where(cb.equal(a.get("city"), city);

The join operation can be used with OneToOne, ManyToOne, OneToMany, ManyToMany and ElementColleciton mappings. When used with a collection relationship you can join the same relationship multiple times to query multiple independent values.

// All employees who work on both projects.
Root e = cq.from(Employee.class);
Join p = e.join("projects");
Join p2 = e.join("projects");
cq.where(cb.and(cb.equal(p.get("name"), p1), cb.equal(p2.get("name"), p2));

Fetch

The fetch operation can be used on a From object to fetch the related objects in a single query. This avoids additional queries for each of the object's relationships, and ensures that the relationships have been fetched if they were LAZY. EclipseLink also supports batch fetching through query hints.

Root e = cq.from(Employee.class);
Fetch a = e.fetch("address");
cq.select(e);

Caution should be used in using a Fetch in the where clause as it can affect the data returned for the resulting object's relationships. Objects should normally always have the same data, no matter how they were queried, this is important for caching and consistency. This is only an issue if the alias is used in the where clause on a collection relationship to filter the related objects that will be fetched. This should not be done, but is sometimes desirable, in which case the query should ensure it has been set to BYPASS the cache.

JoinType

By default join and fetch are INNER joins. This means that results that do not have the relationship will be filtered from the query results. To avoid this, a join can be defined as an OUTER join using the LEFT JoinType as an argument to the join or fetch operation.

Root e = cq.from(Employee.class);
Join a = e.join("address", JoinType.LEFT);
cq.order(a.get("city"));

Order

The query order by clause defines how the query results will be ordered. The order by clause is defined using the orderBy API on CriteriaQuery. Only Order objects can be passed to orderBy, and are obtained from CriteriaBuilder using the asc or desc API.

// Order by the last and first names.
Root e = cq.from(Employee.class);
cq.orderBy(cb.desc(e.get("lastName")), cb.asc(e.get("firstName")));
// Order by the last name, ignoring case.
Root e = cq.from(Employee.class);
cq.orderBy(cb.asc(cb.upper(e.get("lastName"))));
// Order by the address object (orders by its id).
Root e = cq.from(Employee.class);
cq.orderBy(cb.asc(e.get("address")));

Group By

The query group by clause allows for summary information to be computed on a set of objects. group by is normally used in conjunction with aggregation functions. The group by clause is defined using the groupBy API on CriteriaQuery with any valid Expression object.

// Select the average salaries grouped by city.
Root e = cq.from(Employee.class);
cq.multiselect(cb.avg(e.<Number>get("salary")), e.get("address").get("city"));
cq.groupBy(e.get("address").get("city"));
// Select the average salaries grouped by city, ordered by the average salary.
Root e = cq.from(Employee.class);
Expression avg = cb.avg(e.<Number>get("salary"));
cq.multiselect(avg, e.get("address").get("city"));
cq.groupBy(e.get("address").get("city"));
cq.orderBy(avg);
// Select employees and the count of their number of projects.
Root e = cq.from(Employee.class);
Expression p = e.join("projects", JoinType.LEFT);
cq.multiselect(e, cb.count(p));
cq.groupBy(e);

Having

The query having clause allows for the results of a group by to be filtered. The having clause is defined using the having API on CriteriaQuery with any Predicate object.

// Select the average salaries grouped by city, only including cities with average salaries over 100000.
Root e = cq.from(Employee.class);
Expression avg = cb.avg(e.<Number>get("salary"));
cq.multiselect(avg, e.get("address").get("city"));
cq.groupBy(e.get("address").get("city"));
cq.having(cb.greaterThan(avg, 100000));

Where

The where clause is normally the main part of the query as it defines the conditions (predicates) that filter what is returned. The where clause is defined using the where API on CriteriaQuery with any Predicate objects. A Predicate is obtained using a comparison operation, or a logical operation on CriteriaBuilder. The isNull, isNotNull, and in operations can also be called on Expression. The not operation can also be called on Predicate

Comparison operations defined on CriteriaBuilder
Operation Description Example
equal, notEqual equal
cb.lessThan(e.get("firstName"), "Bob")
lessThan, lt less than
cb.lessThan(e.get("salary"), 100000)
greaterThan, gt greater than
cb.greaterThan(e.get("salary"), cb.parameter(Integer.class, "sal"))
lessThanOrEqualTo, le less than or equal
cb.lessThanOrEqualTo(e.get("salary"), 100000)
greaterThanOrEqualTo, ge greater than or equal
cb.greaterThanOrEqualTo(e.get("salary"), cb.parameter(Integer.class, "sal"))
like, notLike evaluates if the two string match, '%' and '_' are valid wildcards, and ESCAPE character is optional
cb.or(cb.like(e.get("firstName"), "A%"), cb.notLike(e.get("firstName"), "%._%", '.'))
between evaluates if the value is between the two values
cb.between(e.<String>get("firstName"), "A", "C"))
isNull compares the value to null, databases may not allow or have unexpected results when using = with null
cb.isNull(e.get("endDate"))
e.get("endDate").isNull()
in evaluates if the value is contained in the list
cb.in(e.get("firstName")).value("Bob").value("Fred").value("Joe")
e.get("firstName").in("Bob", "Fred", "Joe")
e.get("firstName").in(cb.parameter(List.class, "names")

Logical operations defined on CriteriaBuilder:

Logical operations defined on CriteriaBuilder
Operation Description Example
and and two or more predicates together
cb.and(cb.equal(e.get("firstName"), "Bob"), cb.equal(e.get("lastName"), "Smith"))
or or two or more predicates together
cb.or(cb.equal(e.get("firstName"), "Bob"), cb.equal(e.get("firstName"), "Bobby"))
not negate a predicate
cb.not(cb.or(cb.equal(e.get("firstName"), "Bob"), cb.equal(e.get("firstName"), "Bobby")))
cb.or(cb.equal(e.get("firstName"), "Bob"), cb.equal(e.get("firstName"), "Bobby")).not()

Parameters

Parameters can be defined using the parameter API on CriteriaBuilder. JPA defines named parameters, and positional parameters. For named parameters the parameter type and name are specified. For positional parameters only the parameter type is specified. Positional parameters start at position 1 not 0.

Named parameter criteria example
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.where(cb.equal(e.get("firstName"), cb.parameter(String.class, "first")), cb.equal(e.get("lastName"), cb.parameter(String.class, "last")));
Query query = em.createQuery(cq)
query.setParameter("first", "Bob");
query.setParameter("last", "Smith");
List<Employee> = query.getResultList();
Positional parameter criteria example
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery();
Root e = cq.from(Employee.class);
cq.where(cb.equal(e.get("firstName"), cb.parameter(String.class)), cb.equal(e.get("lastName"), cb.parameter(String.class)));
Query query = em.createQuery(cq)
query.setParameter(1, "Bob");
query.setParameter(2, "Smith");
List<Employee> = query.getResultList();

Functions

Several database functions are supported by the Criteria API. All supported functions are defined on CriteriaBuilder. Some functions may not be supported by some databases, if they are not SQL compliant, and offer no equivalent function.

CriteriaBuilder database functions
Function Description Example
diff subtraction
cb.diff(e.<Number>get("salary"), 1000)
sum addition
cb.sum(e.<Number>get("salary"), 1000)
prod multiplication
cb.prod(e.<Number>get("salary"), 2)
quot division
cb.quot(e.<Number>get("salary"), 2)
abs absolute value
cb.abs(
    cb.diff(e.<Number>get("salary"), e.get("manager").<Number>get("salary")))
selectCase defines a case statement
cb.selectCase(e.get("status")).
    when(0, "active").
    when(1, "consultant").
    otherwise("unknown")
cb.selectCase().
    when(cb.equal(e.get("status"), 0), "active").
    when(cb.equal(e.get("status"), 1), "consultant").
    otherwise("unknown")
coalesce evaluates to the first non null argument value
cb.coalesce(cb.concat(e.<Number>get("salary"), 0)
concat concatenates two or more string values
cb.concat(cb.concat(e.<String>get("firstName"), " "), e.<String>get("lastName"))
currentDate the current date on the database
cb.currentDate()
currentTime the current time on the database
cb.currentTime()
currentTimestamp the current date-time on the database
cb.currentTimestamp()
length the character/byte length of the character or binary value
cb.length(e.<String>get("lastName"))
locate the index of the string within the string, optionally starting at a start index
cb.locate("-", e.<String>get("lastName"))
lower convert the string value to lower case
cb.lower(e.<String>get("lastName"))
mod computes the remainder of dividing the first integer by the second
cb.mod(e.<Integer>get("hoursWorked"), 8)
nullif returns null if the first argument to equal to the second argument, otherwise returns the first argument
cb.nullif(e.<Number>get("salary"), 0)
sqrt computes the square root of the number
cb.sqrt(e.<Number>get("salary"))
substring the substring from the string, starting at the index, optionally with the substring size
cb.substring(e.<String>get("lastName"), 0, 2)
trim trims leading, trailing, or both spaces or optional trim character from the string
cb.trim(TrimSpec.TRAILING, e.<String>get("lastName"))
cb.trim(e.<String>get("lastName"))
cb.trim(TrimSpec.LEADING, '-', e.<String>get("lastName"))
upper convert the string value to upper case
cb.upper(e.<String>get("lastName"))

Special Functions

JPQL defines several special functions that are not database functions, but have special meaning in JPQL. These include INDEX, KEY, SIZE, IS EMPTY, TYPE, FUNCTION and TREAT. EclipseLink (as of 2.4) also defines several special functions FUNC, OPERATOR, SQL and COLUMN.

JPQL special functions
Function Description Example
INDEX the index of the ordered List element, only supported with @OrderColumn
SELECT l FROM Employee e JOIN e.toDoList l WHERE INDEX(l) = 1
KEY the key of the Map element
SELECT p FROM Employee e JOIN e.priorities p WHERE KEY(p) = 'high'
SIZE the size of the collection relationships, this evaluates to a sub-select
SELECT e FROM Employee e WHERE SIZE(e.managedEmployees) < 2
IS EMPTY evaluates to true if the collection relationship is empty, this evaluates to a sub-select
SELECT e FROM Employee e WHERE e.managedEmployees IS EMPTY
TYPE the inheritance discriminator value
SELECT p FROM Project p WHERE TYPE(p) = LargeProject
TREAT treat (cast) the object as its subclass value (JPA 2.1 draft)
SELECT e FROM Employee JOIN TREAT(e.projects AS LargeProject) p WHERE p.budget > 1000000
FUNCTION call a database function (JPA 2.1 draft)
SELECT p FROM Phone p WHERE FUNCTION('TO_NUMBER', e.areaCode) > 613

EclipseLink Extensions (EQL)

EclipseLink provides many extensions to the standard JPA JPQL. These extensions provide access to additional database features many of which are part of the SQL standard, provide access to native database features and functions, and provide access to EclipseLink specific features. EclipseLink JPQL extensions are referred to as the EclipseLink Query Language (EQL).

EclipseLink's JPQL extensions include:

  • Less restrictions than JPQL, allows sub-selects and functions within operations such as LIKE, IN, ORDER BY, constructors, functions etc.
  • Allow != in place of <>
  • FUNC operation to call database specific functions (now FUNCTION in JPA 2.1)
  • TREAT operation to downcast related entities with inheritance
  • OPERATOR operation to call EclipseLink database independent functions (EL 2.4)
  • SQL operation to mix SQL with JPQL (EL 2.4)
  • CAST and EXTRACT functions (EL 2.4)
  • REGEXP function for regular expression querying (EL 2.4)
  • Usage of sub-selects in the SELECT and FROM clause (EL 2.4)
  • ON clause support for defining JOIN and LEFT JOIN conditions (EL 2.4)
  • Joins between independent entities (EL 2.4)
  • Usage of an alias on a JOIN FETCH (EL 2.4)
  • COLUMN operation to allow querying on non mapped columns (EL 2.4)
  • TABLE operation to allow querying on non mapped tables (EL 2.4)
  • UNION, INTERSECT, EXCEPT support (EL 2.4)
  • Usage of object variables in =, <>, IN, IS NULL, and ORDER BY


Eclipselink-logo.gif
Version: 2.4 DRAFT
Other versions...