Package org.hibernate.cfg

Interface QuerySettings

All Known Subinterfaces:

AvailableSettings

All Known Implementing Classes:

Environment

public interface QuerySettings

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CALLABLE_NAMED_PARAMS_ENABLED	When enabled, specifies that Hibernate should attempt to map parameter names given in a ProcedureCall or StoredProcedureQuery to named parameters of the JDBC CallableStatement.
static final String	CRITERIA_COPY_TREE	When enabled, specifies that queries created via EntityManager.createQuery(CriteriaQuery), EntityManager.createQuery(CriteriaUpdate) or EntityManager.createQuery(CriteriaDelete) must create a copy of the passed criteria query object such that the resulting Query object is not affected by mutation of the original criteria query.
static final String	CRITERIA_VALUE_HANDLING_MODE	By default, a criteria query produces SQL with a JDBC bind parameter for any value specified via the criteria query API, except when the value is passed via CriteriaBuilder.literal(Object), in which case the value is "inlined" as a SQL literal.
static final String	DEFAULT_NULL_ORDERING	Specifies the default precedence of null values sorted via the HQL ORDER BY clause, either none, first, or last, or an instance of the enumeration Nulls.
static final String	FAIL_ON_PAGINATION_OVER_COLLECTION_FETCH	When pagination is used in combination with a fetch join applied to a collection or many-valued association, the limit must be applied in-memory instead of on the database.
static final String	IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE	This setting defines how Immutable entities are handled when executing a bulk update query.
static final String	IN_CLAUSE_PARAMETER_PADDING	Determines how parameters occurring in a SQL IN predicate are expanded.
static final String	JSON_FUNCTIONS_ENABLED	Boolean setting to control if the use of tech preview JSON functions in HQL is enabled.
static final String	NATIVE_IGNORE_JDBC_PARAMETERS	When enabled, ordinal parameters (represented by the ? placeholder) in native queries will be ignored.
static final String	NATIVE_PREFER_JDBC_DATETIME_TYPES	When enabled, native queries will return Date, Time, and Timestamp instead of the datetime types from java.time, recovering the behavior of native queries in Hibernate 6 and earlier.
static final String	PORTABLE_INTEGER_DIVISION	Specifies that division of two integers should produce an integer on all databases.
static final String	QUERY_MULTI_TABLE_INSERT_STRATEGY	Defines the "global" strategy to use for handling HQL and Criteria insert queries.
static final String	QUERY_MULTI_TABLE_MUTATION_STRATEGY	Defines the "global" strategy to use for handling HQL and Criteria mutation queries.
static final String	QUERY_PASS_PROCEDURE_PARAMETER_NAMES	For database supporting name parameters this setting allows to use named parameter is the procedure call.
static final String	QUERY_PLAN_CACHE_ENABLED	When enabled, specifies that query plans should be cached.
static final String	QUERY_PLAN_CACHE_MAX_SIZE	The maximum number of entries in the query interpretation cache.
static final String	QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE	Deprecated. this setting is not currently used
static final String	QUERY_STARTUP_CHECKING	When enabled, specifies that named queries be checked during startup.
static final String	SEMANTIC_QUERY_PRODUCER	Specifies a HqlTranslator to use for HQL query translation.
static final String	SEMANTIC_QUERY_TRANSLATOR	Specifies a SqmTranslatorFactory to use for HQL query translation.
static final String	XML_FUNCTIONS_ENABLED	Boolean setting to control if the use of tech preview XML functions in HQL is enabled.

Field Details

JSON_FUNCTIONS_ENABLED

@Incubating
static final String JSON_FUNCTIONS_ENABLED

Boolean setting to control if the use of tech preview JSON functions in HQL is enabled.

Since:

7.0

See Also:

• Constant Field Values

Default Value:

false (disabled) since the functions are still incubating.

XML_FUNCTIONS_ENABLED

@Incubating
static final String XML_FUNCTIONS_ENABLED

Boolean setting to control if the use of tech preview XML functions in HQL is enabled.

Since:

7.0

See Also:

• Constant Field Values

Default Value:

false (disabled) since the functions are still incubating.

PORTABLE_INTEGER_DIVISION

static final String PORTABLE_INTEGER_DIVISION

Specifies that division of two integers should produce an integer on all databases. By default, integer division in HQL can produce a non-integer on Oracle, MySQL, or MariaDB.

Since:

6.5

See Also:

• Constant Field Values

Default Value:

false

SEMANTIC_QUERY_PRODUCER

static final String SEMANTIC_QUERY_PRODUCER

Specifies a HqlTranslator to use for HQL query translation.

See Also:

• Constant Field Values

SEMANTIC_QUERY_TRANSLATOR

static final String SEMANTIC_QUERY_TRANSLATOR

Specifies a SqmTranslatorFactory to use for HQL query translation.

See Also:

• Constant Field Values

QUERY_MULTI_TABLE_MUTATION_STRATEGY

static final String QUERY_MULTI_TABLE_MUTATION_STRATEGY

Defines the "global" strategy to use for handling HQL and Criteria mutation queries. Specifies a SqmMultiTableMutationStrategy..

See Also:

• Constant Field Values

QUERY_MULTI_TABLE_INSERT_STRATEGY

static final String QUERY_MULTI_TABLE_INSERT_STRATEGY

Defines the "global" strategy to use for handling HQL and Criteria insert queries. Specifies a SqmMultiTableInsertStrategy.

See Also:

• Constant Field Values

QUERY_STARTUP_CHECKING

static final String QUERY_STARTUP_CHECKING

When enabled, specifies that named queries be checked during startup.

Mainly intended for use in test environments.

See Also:

• SessionFactoryBuilder.applyNamedQueryCheckingOnStartup(boolean)
• Constant Field Values

Default Value:

true (enabled) - named queries are checked at startup.

CRITERIA_VALUE_HANDLING_MODE

static final String CRITERIA_VALUE_HANDLING_MODE

By default, a criteria query produces SQL with a JDBC bind parameter for any value specified via the criteria query API, except when the value is passed via CriteriaBuilder.literal(Object), in which case the value is "inlined" as a SQL literal.

This setting may be used to override this default behavior:

• the "bind" mode uses bind parameters to pass such values to JDBC, but
• the "inline" mode inlines values as SQL literals.

In both modes:

• values specified using literal() are inlined, and
• values specified using CriteriaBuilder.parameter(Class) to create a criteria parameter and Query.setParameter(jakarta.persistence.Parameter,Object) to specify its argument are passed to JDBC using a bind parameter.

Since:

6.0.0

See Also:

• ValueHandlingMode
• CriteriaBuilder.literal(Object)
• CriteriaBuilder.parameter(Class)
• HibernateCriteriaBuilder.value(Object)
• Constant Field Values

Default Value:

ValueHandlingMode.BIND.

DEFAULT_NULL_ORDERING

static final String DEFAULT_NULL_ORDERING

Specifies the default precedence of null values sorted via the HQL ORDER BY clause, either none, first, or last, or an instance of the enumeration Nulls.

See Also:

• Nulls
• SessionFactoryBuilder.applyDefaultNullPrecedence(jakarta.persistence.criteria.Nulls)
• Constant Field Values

Default Value:

none.

CRITERIA_COPY_TREE

static final String CRITERIA_COPY_TREE

When enabled, specifies that queries created via EntityManager.createQuery(CriteriaQuery), EntityManager.createQuery(CriteriaUpdate) or EntityManager.createQuery(CriteriaDelete) must create a copy of the passed criteria query object such that the resulting Query object is not affected by mutation of the original criteria query.

If disabled, it's assumed that the client does not mutate the criteria query after calling createQuery(). Thus, in the interest of performance, no copy is created.

The default behavior depends on how Hibernate is bootstrapped:

• When bootstrapping Hibernate through the native bootstrap APIs, this setting is disabled, that is, no copy of the criteria query object is made.
• When bootstrapping Hibernate through the JPA SPI, this setting is enabled so that criteria query objects are copied, as required by the JPA specification.

Since:

6.0

See Also:

• Constant Field Values

NATIVE_IGNORE_JDBC_PARAMETERS

static final String NATIVE_IGNORE_JDBC_PARAMETERS

When enabled, ordinal parameters (represented by the ? placeholder) in native queries will be ignored.

See Also:

• SessionFactoryOptions.getNativeJdbcParametersIgnored()
• Constant Field Values

Default Value:

false (disabled) - native queries are checked for ordinal placeholders.

NATIVE_PREFER_JDBC_DATETIME_TYPES

@Compatibility
static final String NATIVE_PREFER_JDBC_DATETIME_TYPES

When enabled, native queries will return Date, Time, and Timestamp instead of the datetime types from java.time, recovering the behavior of native queries in Hibernate 6 and earlier.

Since:

7.0

See Also:

• Constant Field Values

Default Value:

false (disabled) - native queries return LocalDate, LocalTime, and LocalDateTime.

FAIL_ON_PAGINATION_OVER_COLLECTION_FETCH

static final String FAIL_ON_PAGINATION_OVER_COLLECTION_FETCH

When pagination is used in combination with a fetch join applied to a collection or many-valued association, the limit must be applied in-memory instead of on the database. This typically has terrible performance characteristics, and should be avoided.

When enabled, this setting specifies that an exception should be thrown for any query which would result in the limit being applied in-memory.

Since:

5.2.13

See Also:

• Constant Field Values

Default Value:

false (disabled) - no exception is thrown and the possibility of terrible performance is left as a problem for the client to avoid.

IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE

static final String IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE

This setting defines how Immutable entities are handled when executing a bulk update query. Valid options are enumerated by ImmutableEntityUpdateQueryHandlingMode:

• "warning" specifies that a warning log message is issued when an immutable entity is to be updated via a bulk update statement, and
• "exception" specifies that a HibernateException should be thrown.

Since:

5.2.17

See Also:

• ImmutableEntityUpdateQueryHandlingMode
• Constant Field Values

Default Value:

"warning"

IN_CLAUSE_PARAMETER_PADDING

static final String IN_CLAUSE_PARAMETER_PADDING

Determines how parameters occurring in a SQL IN predicate are expanded. By default, the IN predicate expands to include sufficient bind parameters to accommodate the specified arguments.

However, for database systems supporting execution plan caching, there's a better chance of hitting the cache if the number of possible IN clause parameter list lengths is smaller.

When this setting is enabled, we expand the number of bind parameters to an integer power of two: 4, 8, 16, 32, 64. Thus, if 5, 6, or 7 arguments are bound to a parameter, a SQL statement with 8 bind parameters in the IN clause will be used, and null will be bound to the left-over parameters.

Since:

5.2.17

See Also:

• Constant Field Values

CALLABLE_NAMED_PARAMS_ENABLED

static final String CALLABLE_NAMED_PARAMS_ENABLED

When enabled, specifies that Hibernate should attempt to map parameter names given in a ProcedureCall or StoredProcedureQuery to named parameters of the JDBC CallableStatement.

Since:

6.0

See Also:

• SessionFactoryOptions.isUseOfJdbcNamedParametersEnabled()
• Constant Field Values

QUERY_PLAN_CACHE_ENABLED

static final String QUERY_PLAN_CACHE_ENABLED

When enabled, specifies that query plans should be cached.

By default, the query plan cache is disabled, unless one of the configuration properties "hibernate.query.plan_cache_max_size" or "hibernate.query.plan_parameter_metadata_max_size" is set.

See Also:

• Constant Field Values

QUERY_PLAN_CACHE_MAX_SIZE

static final String QUERY_PLAN_CACHE_MAX_SIZE

The maximum number of entries in the query interpretation cache.

The default maximum is 2048.

See Also:

• QueryInterpretationCache
• Constant Field Values

QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE

@Deprecated(since="6.0")
static final String QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE

Deprecated.

this setting is not currently used

The maximum number of ParameterMetadata instances maintained by the QueryInterpretationCache.

See Also:

• Constant Field Values

QUERY_PASS_PROCEDURE_PARAMETER_NAMES

static final String QUERY_PASS_PROCEDURE_PARAMETER_NAMES

For database supporting name parameters this setting allows to use named parameter is the procedure call.

By default, this is set to false

See Also:

• Constant Field Values