Literals in JPQL and Criteria Queries

Literals in JPQL, as in Java, represent constant values. JPQL supports various types of literals, including NULL, boolean literals (TRUE and FALSE), numeric literals (for example, 100), string literals (for example, 'abc'), enum literals (for example, mypackage.MyEnum.MY_VALUE), and entity type literals (for example, Country).

Use JPQL literals sparingly. Queries that use parameters instead of literals are more generic and efficient because they can be compiled once and then run many times with different parameter values. Embed literals in JPQL queries only when a single, constant value is always used and never replaced.

The NULL literal

The NULL literal represents a null value, similar to null in Java and SQL. Because JPQL is case-insensitive, NULL, null, and Null are equivalent. Comparison with NULL in JPQL follows SQL rules for NULL comparison rather than Java rules, as explained on the Comparison Operators page.

Boolean literalsLiterals

Similar to Java and SQL, JPQL supports two boolean literals: TRUE and FALSE. Because JPQL is case-insensitive, TRUE is equivalent to true and True, and FALSE is equivalent to false and False.

Numeric literals

JPQL supports both Java and SQL syntax for numeric literals. Numeric suffixes (for example, 1.5F) are also supported. The following are examples of valid numeric literals in JPQL:

• int: 100, -127, 0, 07777
• long: 100L, -127L, 0L, 07777L
• float: 3.14F, 0f, 1e2f, -2.f, 5.04e+17f
• double: 3.14, 0d, 1e2D, -2., 5.04e+17

ObjectDB also supports hexadecimal (for example, 0xFF and 0xFFL) and octal (for example, 077 and 077L) numeric literals. This feature is not supported by all JPA implementations.

String literals

JPQL follows SQL syntax for string literals. Strings are enclosed in single quotation marks (for example, 'Adam' or ''), and a single quotation mark within a string is represented by two single quotation marks (for example, 'Adam''s').

ObjectDB also supports the Java and JDO syntax for string literals, where strings are enclosed in double quotation marks (for example, "Adam" and "") and can use Java escape characters (for example, "Adam\'s" and "abcd 1234"). However, this syntax is not supported by all JPA implementations.

Unlike most other JPQL components, string literals (which represent data) are case-sensitive, so 'abc' and 'ABC' are not equivalent.

Date and time literals

JPQL follows the SQL and JDBC syntax for date and time literals:

• Date: {d 'yyyy-mm-dd'}. For example: {d '2019-12-31'}
• Time: {t 'hh:mm:ss'}. For example: {t '23:59:59'}
• Timestamp: {ts 'yyyy-mm-dd hh:mm:ss'}. For example: {ts '2020-01-03 13:59:59'}

Enum literals

Enum literals in JPQL queries use the standard Java syntax for enum values, but you must specify the fully qualified name of the enum type.

For example, given the following enum definition:

package example.ui;
enum Color { RED, GREEN, BLUE }

Then, example.ui.Color.RED is a valid literal in JPQL, but Color.RED is not.

Entity type literals

Entity type literals represent entity types in JPQL, similar to how java.lang.Class instances represent Java types in Java. Entity type literals enable selective retrieval by type.

In JPQL, an entity type literal is the name of the entity class (for example, Country).
This is equivalent to Country.class in Java code. The name of the entity class is not enclosed in quotation marks because type literals are not string literals.

By default, the name of an entity class is its unqualified name (that is, without the package name), but you can change it by specifying a different name in the name element of the @Entityjakarta.persistence.EntityDeclares that the annotated class is an entity. annotation.

Criteria query literals

The CriteriaBuilderjakarta.persistence.criteria.CriteriaBuilderUsed to construct criteria queries, compound selections, expressions, predicates, orderings. interface provides two factory methods for building literal expressions.

Ordinary literals

The main method, literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal., takes a Java object and returns a literal expression. For example:

  // Boolean literals:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Boolean> t = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(true);
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Boolean> f = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(Boolean.FALSE);
  // Numeric literals:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Integer> i1 = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(1);
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Integer> i2 = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(Integer.ValueOf(2));
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Double> d = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(3.4);
  // String literals:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<String> empty = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.("");
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<String> jpa = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.("JPA");
  // Date and Time literals:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<java.sql.Date> today = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(new java.sql.Date());
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<java.sql.Time> time = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(new java.sql.Time());
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<java.sql.Timestamp> now = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(new java.sql.Timestamp());
  // Enum literal:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Color> red = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(Color.RED);
  // Entity Type literal:
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Class> type = cb.literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal.(MyEntity.class);

Null literals

You can build null literal expressions with the standard literaljakarta.persistence.criteria.CriteriaBuilder.literal(T)Create an expression for a literal. method:

  Expressionjakarta.persistence.criteria.ExpressionType for query expressions. n = cb.literal(null);

Alternatively, you can use the CriteriaBuilderjakarta.persistence.criteria.CriteriaBuilderUsed to construct criteria queries, compound selections, expressions, predicates, orderings. method nullLiteraljakarta.persistence.criteria.CriteriaBuilder.nullLiteral(Class)Create an expression for a null literal with the given type., which returns a typed expression:

  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<String> strNull = cb.nullLiteraljakarta.persistence.criteria.CriteriaBuilder.nullLiteral(Class)Create an expression for a null literal with the given type.(String.class);
  Expressionjakarta.persistence.criteria.ExpressionType for query expressions.<Integer> intNull = cb.nullLiteraljakarta.persistence.criteria.CriteriaBuilder.nullLiteral(Class)Create an expression for a null literal with the given type.(Integer.class);