Jakarta Query

The complete list of Jakarta Query contributors may be found here.

Inheritance is a relationship between entity types. An entity X inherits an entity Y if and only if for every type labeled y in Y, there is a corresponding type labeled y in X and either:

Thus, there is a simple mapping from records of type X to records of type Y. Given a record r of type X, the restriction of r to a type Y inherited by X is a structure s containing an element labeled y for each type with label y occurring in the type Y:

Then s is a record of type Y.

Any well-defined operation on records of type Y is also a well-defined operation on the restriction of a record to Y. We therefore adopt the principle that an operation which may be applied to a record of a given entity type may also be applied to a record of any entity type which inherits the first entity type.

A join may specify the name of an entity:

where Y is the name of the entity, y is the label (alias) assigned to it, and [from] is a root entity or a join. As before, the keyword as is optional.

This kind of join produces a cartesian product. For each structure r of the result list of the operation on which the join acts, and for each record y of any entity type which inherits Y, the result list contains a structure r' containing all labeled elements of r together with the record y labeled by the alias y.

For example, this query is a cartesian product:

This query evaluates to a result list containing a structure for each pairing of a record of entity Book with a record of entity Loan. The structure contains two labeled elements, one for each entity, each labeled by its corresponding alias, book, and loan, respectively. The list might contain structures this:

Note that there is no meaningful relationship between the book and the loan.

A join to a named entity may be immediately followed by a restriction. In this case, the syntax is slightly different:

where [predicate] is a predicate, as defined later in Conditional expressions.

For example:

This kind of join is interpreted as a sequence of two operations, a join of the previous kind, with no on, followed by a restriction with the given predicate.

The result of the query might contain structures like:

This time, isbn and bookIsbn agree.

Instead of a named entity, a join may identify a structure or collection nested within the result list of the operation on which it acts:

where [path] is a path expression, as defined later in Path expressions, and y is the label.

As usual, the keyword as is optional. The keyword inner is also completely optional, and so a join may be written:

For example:

The path expression identifies a structure nested within the result list of the operation on which the join acts.

For each structure r of the result list of the operation on which the join acts:

The previous example evaluates to a list containing a structure for each Author of each Book. The structure contains two labeled elements, one for each entity, each labeled by its corresponding alias, book, and author, respectively. The list might contain structures like this:

Notice that this kind of join has the effect of duplicating nested structures or atomic values at the top level of the of structure belonging to the result list.

A join to a structure or collection may be immediately followed by a restriction.

where [predicate] is a predicate, as defined later in Conditional expressions.

This kind of join is interpreted as a sequence of two operations: a join of the previous kind, with no on, followed by a restriction with the given predicate.

A left join is similar to a regular join:

where [path] is a path expression, as before, and y is the label.

As usual, the keyword as is optional. The keyword outer is also completely optional, and so a left join may be written:

For example:

The path expression identifies a structure nested within the result list of the operation on which the join acts.

For each structure r of the result list of the operation on which the join acts:

Just like regular joins, a left join may be followed by a restriction:

In this case, however, the restriction is only evaluated for elements of the result list which contain structures labeled by the alias y. Any element of the result list of the join which does not contain a structure labeled by the alias y is taken to satisfy the restriction, even when the predicate would not be satisfied by that element.

A fetch join is a hint to the Jakarta Query implementation regarding which data in the query result set the application program will access. A fetch join does not affect the shape (type) of the query result set, and therefore does not introduce a label. Otherwise, the syntax is similar to a left join:

When restriction is applied to a query involving aggregation, the predicate may only involve:

In this case, the restriction eliminates entire nested lists belonging to the result list of the aggregation operation.

When projection is applied to a query involving aggregation, every value expression in the select list must be either:

In this case, the projection has the additional effect of collapsing the list of lists produced by aggregation, producing a single result structure for each nested list in the result list of the operation to which the projection applies.

Alternatively, if every value expression in the select list is an aggregate function, and if the query does not have a group by clause, then aggregation over all elements of the result list is implied.^[8] Such a query produces a result list with a single element.

A query with no group by clause may not mix aggregate function expressions with other value expressions.

The syntax for literal expressions is given by the rules string_literal and numeric_literal, and in the previous section titled Lexical structure.

In an implementation for Java, a string, integer, or decimal literal is assigned the type it would be assigned in Java. So, for example, 'Hello' is assigned the type java.lang.String, 123 is assigned the type int, 1e4 is assigned the type double, and 1.23f is assigned the type float. In the extended language:

When executed, a literal expression evaluates to its literal value.

The syntax for special values is given by the rules special_boolean_expression and special_datetime_expression.

In an implementation of Jakarta Query for Java:

The expression true and false evaluate to their literal values. The expressions local date, local time, and local datetime evaluate to the current date, current time, and current datetime of the database server, respectively.

A parameter expression, with syntax given by input_parameter, is assigned a type and value either:

When executed, a parameter expression evaluates to the argument assigned to the parameter.

Positional and named parameters must not be mixed in a single query.

An enum literal expression is a sequence of identifiers, with syntax specified by enum_literal, and must refer to a member of some sort of enumerated type. An enum literal may only occur as:

In each case, the enum literal expression is assigned the type of the left operand of the assignment, comparison, or in operator.

In an implementation for Java, the type assigned must be a Java enum type, and the identifier must be the name of an enumerated value of the enum type including the fully qualified Java enum class name. For example, day <> java.time.DayOfWeek.MONDAY is a legal comparison expression.

When executed, the enum literal expression evaluates to the named member of the enumerated type.

TODO allow day <> MONDAY, since the enum type can be inferred.

In the extended language, an entity type literal, with syntax given by entity_type_literal is just the name of an entity type, in the sense given in Entities and embeddable types. When executed, it evaluates to a value which represents the named entity type.

An implementation for Java assigns the type java.lang.Class<E> to an entity type literal, where E is the Java class mapping the named entity type. When executed, the literal evaluates to an instance of Class representing the Java class E.

A path expression has syntax specified by:

A simple_path_expression or joinable_path_expression is simply a period-separated list of identifiers. Any other sort of path expression might begin with:

The first element of the path expression is called the root element of the path.

A path expression is a compound path identifying a labelled element of a structure, as discussed above in Paths. Every prefix of a path is itself a path. That is, every identifier in a path is interpreted as the label of an element of a structure.

Each element of the path is assigned a type:

The type of the whole path expression is the type of the last element of the list. For example, pages might be assigned the type int, address might be assigned the type org.example.Address, and address.street might be assigned the type java.lang.String.

When a path expression is executed, each element of the path is evaluated in turn:

If any element of a path expression evaluates to a null value, the whole path expression evaluates to a null value.

In the core language, an identifier expression, with syntax given by id_expression, is assigned the type of the unique identifier of the queried entity and evaluates to the unique identifier of a given record. An identifier expression is a synonym for a path expression with one element matching the identifier attribute of the queried entity type. An identifier expression may occur in the select clause, in the order clause, or as a scalar expression in the where clause.

In the extended language, the grammar rule entity_id_or_version_function gives the syntax of the special functions id and version, which accept a path expression whose last element is assigned an entity type, and evaluate to, respectively, the identifier or version element of the record to which the path expression evaluates when executed.

A function call is the name of a function recognized by the Jakarta Query implementation, followed by a parenthesized list of argument expressions, with syntax given by:

This specification defines the standard functions listed in the table below.

When any argument expression of any function call evaluates to a null value, the whole function call evaluates to null.

An implementation Java must assign:

The primitive types double, float, long, int, short, byte, wrappers for these primitive types, BigInteger, and BigDecimal are all considered "Numeric" types.

In the extended language, the extract() function accepts an expression assigned a date, time, or datetime type, along with an identifier — a datetime_field or datetime_part — indicating a specific part of the date, time, or datetime to extract, and evaluates to the specified part of the value to which its argument expression evaluates.

Like keywords, datetime_field and datetime_part identifiers are case-insensitive.

In the extended language, a map key expression, map value expression, or map entry expression is an application of the special key() function, special value() function, or special entry() function, respectively.

The entry() function may only occur in the select clause, as specified by the full grammar of the extended language.

The argument of the key(), value(), or entry() function must be an alias of a collection join of a map, as defined in Join clauses.

TODO This is very restrictive. Should we allow application of key() or value() to a path expression?

An implementation for Java must assign the type java.util.Map.Entry<K,V> to a map entry expression, where K is the type of the key of the map, and V is the type of the value of the map. The map entry expression evaluates to an instance of this type packaging the value to which its argument expression evaluates and the key of the map entry of this value.

The extended language provides three special functions for working with subtype polymorphism.

An aggregate function call may only occur in the select or having clause of a query involving aggregation. Such a clause operates on a list of nested result lists, as specified above in Projection and aggregation and Restriction and aggregation. An aggregate function call is evaluated in the context of such a nested list.

This specification defines the standard aggregate functions listed in the table below.

In the core language, the only allowed aggregate function call is the expression count(this), as specified below in Select clause.

In the extended language, the syntax for aggregate functions is given by aggregate_expression. An aggregate function invocation may specify the keyword distinct, in which case duplicate elimination is applied to the list of values produced by evaluating the argument expression over all elements of the nested list before counting or summing the values.^[13]

In the extended language, a case expression has syntax given by general_case_expression or simple_case_expression.

A general_case_expression has:

When a general case expression is executed, each conditional_expression is evaluated, in order, until one is satisfied.

The whole case expression evaluates to the value produced by the result or default scalar_expression which was evaluated. If there is no else, and no scalar_expression was evaluated, the whole case expression evaluates to the null value.

A simple_case_expression has:

When a simple case expression is executed, the case_operand is evaluated, and then each tested scalar_expression is evaluated, in order, until one produces a value identical to the value of the case_operand.

The whole case expression evaluates to the value produced by the result or default scalar_expression which was evaluated. If there is no else, and no scalar_expression was evaluated, the whole case expression evaluates to the null value.

The syntax of an operator expression is given by the scalar_expression rule. Within an operator expression, parentheses indicate grouping.

All binary infix operators are left-associative. The relative precedence, from highest to lowest precedence, is given by:

The unary prefix operators + and - have higher precedence than the binary infix operators. Thus, 2 * -3 + 5 means (2 * (-3)) + 5 and evaluates to -1.

In an implementation for Java:

In the extended language, a subquery may occur as a scalar_expression in many places where an expression of atomic type is legal. Such a subquery must produce a result list with exactly one element when executed. When the scalar_expression is evaluated, the subquery is executed, and the whole expression evaluates to the single element of the result list of the subquery.

The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. Numeric type promotion is defined by the following rules:

A null comparison, with syntax given by null_comparison_expression, is satisfied when:

In the core language, an in expression, with syntax given by in_expression, must have:

All operands must have the same type.

TODO We should relax the restrictions on the left operand.

In the extended language, the leftmost operand must be a path expression assigned an atomic type or an entity type expression, and there must be exactly one of the following elements:

If the condition has a list of expressions, it is satisfied when its leftmost operand evaluates to a non-null value, and:

If the condition has a subquery, it is satisfied when its leftmost operand evaluates to a non-null value, and:

If the condition has an unparenthesized parameter, it is satisfied when its leftmost operand evaluates to a non-null value, and:

A between expression, with syntax given by between_expression is satisfied when its operands all evaluate to non-null values, and, if the not keyword is missing, its left operand evaluates to a value which is:

Or, if the not keyword occurs, the left operand must evaluate to a value which is:

All three operands must have the same type.

A like expression has syntax given by like_expression.

If an implementation of Jakarta Query targets clients written in Java, it must allow expressions assigned the type java.lang.String as the left operand of a like expression.

The expression is satisfied when its left operand evaluates to a non-null value and:

Matching is lexicographic. Within the pattern, the character bigram '' is interpreted as a literal ', and the characters _ and % are interpreted as wildcards:

Any other character occurring in the pattern is interpreted literally and matches only itself.

An escape character may be used to suppress the interpretation as a wildcard of a particular _ or % character in the pattern.

That is, if the escape character is c, then the character bigram c_ is interpreted literally as the character _, the bigram c% as the character %, and the bigram cc as the character c.

The equality and inequality operators are =, <>, <, >, <=, >=.

The operands of an equality or inequality operator must have the same type, and it must be an atomic type considered comparable by the implementation of Jakarta Query. Any type with a natural order must be treated as a comparable type, and the equality and inequality operators must be interpreted in a way which is consistent with the natural order.

For non-null values, the following table defines an interpretation consistent with the natural order:

When exactly one of the operands of an equality or inequality operator evaluates to a null value, the conditional expression is not satisfied.

In an implementation of Jakarta Query which targets clients written in Java, every primitive or primitive wrapper type is considered comparable, along with java.lang.String, java.math.BigInteger, java.math.BigDecimal, and types representing dates and datetimes.

In the extended language, the right operand of an equality or inequality operator may be a subquery, as discussed in the next section.

In the extended language, there are two kinds of conditional expression involving quantification:

In either case, a subquery occurs as the argument of one of the following special quantifier functions: exists, all, any, or some. When a quantifier is evaluated, the subquery is executed, producing a result list containing values which are instances of some atomic or entity type. For a quantified comparison expression, the type of these values must be the same as the type of the left operand of the equality or inequality operator.

An existence expression is satisfied if and only if:

A quantified comparison expression is satisfied if and only if:

In the core language, the from clause, with syntax given by from_clause, specifies an entity name identifying the root entity of the query, as defined in The root entity. This entity is always assigned the implicit alias this.

In the core language, path expressions occurring in later clauses are interpreted with respect to this entity. That is, the first element of each path expression in the query must be a persistent attribute of the entity named in the from clause. The entity name is a Java identifier, usually the unqualified name of the entity class, as specified in Entities and embeddable types.

In the extended language, the from clause might enumerate multiple steps of the basic operation pipeline. The from_clause of the full grammar allows:

When the root entity is declared using the rule this_implicit_variable, the query must not have joins. A query with joins must use an identification_variable_declarations list to specify the root entity and joins.

When a from clause has multiple elements in the identification_variable_declarations list, the root entity is always the first identification_variable_declaration to occur in the list. Each subsequent identification_variable_declaration is considered a join to a named entity. Join clauses are discussed below.

An identification_variable_declaration declaring a root entity has a range_variable_declaration with an entity_name specifying the name of the root entity, and an identification_variable specifying its alias (label).

Since a from clause may introduce multiple distinct labels, paths in the extended language may begin with the label of an entity. Alternatively, a path which does not begin with the label of an entity is interpreted as beginning with the implicit label this.

The from clause is optional in select statements when a mechanism from an external specification is used to identify the queried entity. For example:

For example, this query provided to the Jakarta Persistence createQuery() method with result type of Book.class or supplied to a Jakarta Data repository method that returns List<Book>:

is equivalent to:

In the extended language, an identification_variable_declaration might include a list of:

Each join is in turn either a range_join, with semantics given by Joins to named entities or a path_join, with semantics given by Joins to nested entities or collections. Such joins may specify a restriction.

In addition, each identification_variable_declaration apart from the first — which specifies the root entity — is itself considered a join. Every such identification_variable_declaration is interpreted as a regular (inner) join and never specifies a restriction.

Every join has a target, either a named entity type belonging to the database, or a path to a nested structure or collection in the result list of the previous operation in the pipeline:

In either case, a join_condition may occur, specifying a restriction which is applied to the result list of the join.

A range_join or identification_variable_declaration has a range_variable_declaration with an identification_variable. Similarly, a path_join has a identification_variable. The identification_variable specifies the alias (label) introduced by the join.

Every join or fetch_join begins with a join_spec:

The joins belonging to a query are evaluated in the order in which they occur in the query.

The where clause, with syntax given by where_clause, specifies a restriction on a result list, as specified by Restriction.

The where clause specifies a conditional_expression, interpreted as the logical predicate of the restriction.

A restriction specified using where is applied after every join and before any aggregation or projection.

The group clause in the extended language, with syntax given by groupby_clause, specifies a list of grouping items, which are collectively interpreted as an aggregation, as specified in Aggregation.

According to the rule groupby_item, each item must be either:

Each such path expression is interpreted as a value expression producing an element of the grouping tuple of the aggregation.

The having clause in the extended language, with syntax given by having_clause, specifies a restriction on the result list of an aggregation, as specified by Restriction.

The having clause specifies a conditional_expression, interpreted as the logical predicate of the restriction.

The having clause must follow a group clause. A query with no group clause may not have a having clause. A restriction specified using having is applied after aggregation and before any projection.

In the core language, the select clause, with syntax given by select_clause, specifies one or more path expressions with syntax simple_path_expression, which are collectively interpreted as a projection with automatically assigned aliases, as specified in Projection.

Alternatively, the select clause may contain either:

A query beginning with select count(this) performs aggregation (without grouping), as specified by Projection and aggregation and always returns a result list of unit length.

In the extended language, the select clause is much more flexible. Its syntax, given by select_clause, permits:

The list of expressions is interpreted as a projection, as specified by Projection, and, if at least one of the expressions is an aggregate function, also aggregation, as specified in Projection and aggregation.

If the distinct keyword occurs, then projection is followed by duplicate elimination, as specified by Duplicate elimination.

The set clause, with syntax given by set_clause, specifies a list of updates to attributes of the queried entity. For each record satisfying the restriction imposed by the where clause, and for each element of the list, the scalar expression is evaluated and assigned to the entity attribute identified by the path expression.

The order clause (or order by clause), with syntax given by orderby_clause, specifies a lexicographic order for the query results, that is, a list of expressions used to sort the records which satisfy the restriction imposed by the where clause, as specified in Ordering.

An item of the order by clause, with syntax given by orderby_item has:

In the core language, an orderby_expression must be a path expression or identifier expression. In the extended language, an orderby_expression may be almost any sort of atomic-valued expression (but not a parameter), as specified by the full grammar of the extended language.

The keyword asc or desc specifies that the values of a given expression should be sorted in ascending or descending order respectively; when neither is specified, ascending order is the default:

Entity attributes occurring earlier in the order by clause take precedence. That is, an attribute occurring later in the order by clause is only used to resolve "ties" between records which cannot be unambiguously ordered using only earlier attributes.

In the extended language, nulls first or nulls last specifies whether null values should be considered, respectively, smaller or larger than non-null values. This specification does not define how null values are ordered with respect to non-null values when the sorting of null values is not explicitly specified. The ordering of null values may vary between data stores and between Jakarta Query providers.

The order clause is always optional. When it is missing, the order of the query results is not defined by this specification and might not be deterministic.

The syntax of union, union all, except, and except all is given by the rule union of the full grammar. The operands must produce result lists of the same type. The type of the union or complement expression is the same as the type of its operands.

The syntax of intersect and intersect all is given by the rule intersection of the full grammar. The operands must produce result lists of the same type. The type of the intersection expression is the same as the type of its operands.

A select statement, with syntax given by select_statement, returns data to the client.

In the core language, a select statement may contain one of more of the following clauses:

A select statement is a pipeline as defined in Basic operations. The result list of the whole select statement is the same as the result list of the last operation in the pipeline.

In the extended language, a select statement may contain, in addition, a group and/or a having clause, with syntax specified by select_query. Each select_query is a pipeline as defined in Basic operations. A select_statement in the full grammar may contain union, intersection, and complement operations, as defined in Union, intersect, and except.

The select clause is optional in a select statement. A query with a missing select clause is interpreted as if it had the following single-item select clause:

where this is the implicit alias.

An update statement, with syntax given by update_statement, updates each record belonging to the entity type named in the update clause which satisfies the restriction imposed by the where clause, if any.

An update statement does not have a well-defined result, but implementations typically return the number of matching records to the client. Such functionality falls outside the scope of this specification.

A delete statement, with syntax given by delete_statement, deletes each record belonging to the entity type named in the update clause which satisfies the restriction imposed by the where clause, if any.

A delete statement does not have a well-defined result, but implementations typically return the number of deleted records to the client. Such functionality falls outside the scope of this specification.