hibernate-orm/design/sqm.adoc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

56 lines
2.2 KiB
Plaintext
Raw Normal View History

= SQM
The Semantic Query Model (SQM) is Hibernate's representation of an HQL or Criteria query's semantic (meaning). This
representation is modeled as an "abstract syntax tree" (AST) - meaning it is a structured tree of nodes where each node
represents an atomic piece of the query. E.g. `SqmSelectClause` represents the query's select clause.
`SqmSelectClause` is ultimately a collection of one or more `SqmSelection` references representing the individual
selections to be returned from the query (called the domain results). Etc
All of these details are handled by the `QuerySqmImpl` implementation of `Query`. This is what Hibernate
uses for both HQL and Criteria queries.
== The Tree
SQM is an Abstract Syntax Tree (AST) describing a query from the perspective of the domain model. It uses the Hibernate
domain model, which is Hibernate's extension to the JPA model. This model contains no relational mapping information -
it simply describes the domain model in mostly Java terms although it does incorporate "classifications" of the type
system. E.g. it understand that `Customer` is an entity, but contains no information about the tables, columns, etc.
See the `design/type-system-domain.adoc` design doc. For details about this domain model
The tree model is defined in the package `org.hibernate.query.sqm.tree`
== Building an SQM - HQL
`org.hibernate.query.hql.HqlTranslator#translate`
== Building an SQM - Criteria
`org.hibernate.query.sqm.internal.SqmCriteriaNodeBuilder`
== Translating an SQM
Generic support for walking over the SQM tree via the `org.hibernate.query.sqm.SemanticQueryWalker` contract.
More specialized support specifically for translating the SQM into a SQL AST is also defined by
`org.hibernate.query.sqm.sql.SqmToSqlAstConverter`.
[source]
----
final SessionFactoryImplementor sessionFactory = ...;
final QueryEngine queryEngine = sessionFactory.getQueryEngine();
final SqmTranslatorFactory sqmTranslatorFactory = queryEngine.getSqmTranslatorFactory();
final SqmSelectTranslator sqmConverter = sqmTranslatorFactory.createSelectTranslator( ... );
final SqmSelectTranslation interpretation = sqmConverter.translate( sqm );
----
See the document `design/sql-ast.adoc` for details about the SQL AST, including its execution.