@Incubating

Package org.hibernate.query.sqm

This package defines a semantic model of HQL queries.

Semantic Query Model (SQM)

An SQM is a tree representing the semantic interpretation of a query. It's "semantic" in the sense that it contains more information than a simple syntax tree.

HQL

HQL is interpreted as an SQM with the help of an ANTRL-generated parser. The class SemanticQueryBuilder is responsible for visiting the syntax tree produced by the parser and building an SQM.

Criteria queries

The SQM tree nodes directly implement the JPA criteria query contracts. For example, SqmFrom implements From.

Our implementation of the JPA CriteriaBuilder interface is SqmCriteriaNodeBuilder. It instantiates SQM nodes and arranges them into SQM tree using the standard operations for building a JPA criteria query.

Transforming SQM to SQL

The package org.hibernate.sql.ast defines an AST representing SQL. To generate SQL from SQM, we must transform the SQM tree to a SQL AST tree. This process is described here, and is handled by a StandardSqmTranslator and a SqlAstTranslator.

API Note:

This entire package is in an incubating state.

Interface Summary

Interface	Description
NodeBuilder	Adapts the JPA CriteriaBuilder to generate SQM nodes.
SemanticQueryWalker<T>	Support for walking a Semantic Query Model (SQM) tree
SqmExpressible<J>	Anything in the application domain model that can be used in an SQM query as an expression
SqmJoinable<O,E>	Specialization for attributes that that can be used in creating SQM joins todo (6.0) : should we define this for entities as well to handle cross joins and "entity joins"? - the result type would need to change to just SqmJoin...
SqmPathSource<J>	Represents parts of the application's domain model that can be used to create SqmPath nodes.
SqmSelectionQuery<R>
SqmTreeCreationLogger	Logger used to log information about the creation of an SQM tree.
SqmTreeTransformationLogger

Enum Summary

Enum	Description
BinaryArithmeticOperator	Enumeration of standard binary arithmetic operators
CastType	Defines the set of basic types which should be accepted by the cast() function on every platform.
ComparisonOperator	Defines the comparison operators.
DynamicInstantiationNature	Represents the type of instantiation to be performed.
FetchClauseType	The kind of fetch to use for the FETCH clause.
FrameExclusion
FrameKind
FrameMode
IntervalType	The different types of intervals that SQL defines.
NullOrdering	The order of null.
NullPrecedence	Defines precedence of null values within ORDER BY clause.
SetOperator	The SQL set operators.
SortOrder
SqmQuerySource	Informational - used to identify the source of an SQM statement.
StrictJpaComplianceViolation.Type
TemporalUnit	A temporal field type which can occur as an argument to extract() or as the unit of a duration expression.
TrimSpec
UnaryArithmeticOperator

Exception Summary

Exception	Description
AliasCollisionException
InterpretationException	Represents a general uncaught problem performing the interpretation.
LiteralNumberFormatException
ParsingException	The root exception for errors (potential bugs) in the sqm parser code itself, as opposed to SemanticException which indicates problems with the query itself.
StrictJpaComplianceViolation	Indicates violations of strict JPQL syntax while strict JPQL syntax checking was enabled.
UnknownEntityException	Indicates we were not able to resolve a given "path structure" as an entity name.
UnknownPathException	todo (6.0) : account for this in the "exception conversion" handling