Interface SqmFunctionDescriptor
- All Known Implementing Classes:
AbstractArrayContainsFunction
,AbstractArrayFillFunction
,AbstractArrayIncludesFunction
,AbstractArrayIntersectsFunction
,AbstractArrayPositionFunction
,AbstractArrayPositionsFunction
,AbstractArrayRemoveFunction
,AbstractArrayTrimFunction
,AbstractJsonArrayAppendFunction
,AbstractJsonArrayInsertFunction
,AbstractJsonInsertFunction
,AbstractJsonMergepatchFunction
,AbstractJsonRemoveFunction
,AbstractJsonReplaceFunction
,AbstractJsonSetFunction
,AbstractSqmFunctionDescriptor
,AbstractSqmSelfRenderingFunctionDescriptor
,ArrayAggFunction
,ArrayConcatElementFunction
,ArrayConcatFunction
,ArrayConstructorFunction
,ArrayContainsOperatorFunction
,ArrayContainsUnnestFunction
,ArrayGetUnnestFunction
,ArrayIncludesOperatorFunction
,ArrayIncludesUnnestFunction
,ArrayIntersectsOperatorFunction
,ArrayIntersectsUnnestFunction
,ArrayRemoveIndexUnnestFunction
,ArrayReplaceUnnestFunction
,ArraySetUnnestFunction
,ArraySliceUnnestFunction
,ArrayToStringFunction
,AvgFunction
,CaseLeastGreatestEmulation
,CastFunction
,CastingConcatFunction
,CastStrEmulation
,ChrLiteralEmulation
,CoalesceIfnullEmulation
,CockroachArrayFillFunction
,CockroachDBJsonExistsFunction
,CockroachDBJsonQueryFunction
,CockroachDBJsonRemoveFunction
,CockroachDBJsonValueFunction
,ConcatPipeFunction
,CountFunction
,CurrentFunction
,DateTruncEmulation
,DB2FormatEmulation
,DB2JsonArrayAggFunction
,DB2JsonArrayFunction
,DB2JsonObjectAggFunction
,DB2JsonObjectFunction
,DB2JsonValueFunction
,DB2PositionFunction
,DB2SubstringFunction
,DynamicDispatchFunction
,EveryAnyEmulation
,ExtractFunction
,FormatFunction
,H2ArrayContainsFunction
,H2ArrayFillFunction
,H2ArrayIncludesFunction
,H2ArrayIntersectsFunction
,H2ArrayPositionFunction
,H2ArrayPositionsFunction
,H2ArrayRemoveFunction
,H2ArrayRemoveIndexFunction
,H2ArrayReplaceFunction
,H2ArraySetFunction
,H2ArrayToStringFunction
,H2JsonArrayAggFunction
,H2JsonExistsFunction
,H2JsonObjectAggFunction
,H2JsonQueryFunction
,H2JsonValueFunction
,H2XmlConcatFunction
,H2XmlElementFunction
,H2XmlForestFunction
,H2XmlPiFunction
,HANAJsonArrayAggFunction
,HANAJsonArrayFunction
,HANAJsonExistsFunction
,HANAJsonObjectAggFunction
,HANAJsonObjectFunction
,HANAJsonValueFunction
,HANASpatialAggregate
,HANASpatialFunction
,HSQLArrayConstructorFunction
,HSQLArrayFillFunction
,HSQLArrayPositionFunction
,HSQLArrayPositionsFunction
,HSQLArrayRemoveFunction
,HSQLArraySetFunction
,HSQLArrayToStringFunction
,HSQLJsonArrayAggFunction
,HSQLJsonArrayFunction
,HSQLJsonObjectFunction
,HypotheticalSetFunction
,HypotheticalSetWindowEmulation
,InsertSubstringOverlayEmulation
,IntegralTimestampaddFunction
,InverseDistributionFunction
,InverseDistributionWindowEmulation
,JdbcEscapeFunctionDescriptor
,JsonArrayAggFunction
,JsonArrayFunction
,JsonExistsFunction
,JsonObjectAggFunction
,JsonObjectFunction
,JsonQueryFunction
,JsonValueFunction
,LegacyDB2XmlExistsFunction
,LegacyDB2XmlQueryFunction
,LengthFunction
,ListaggFunction
,ListaggGroupConcatEmulation
,ListaggStringAggEmulation
,LocatePositionEmulation
,LpadRpadPadEmulation
,MariaDBJsonArrayAggFunction
,MariaDBJsonArrayAppendFunction
,MariaDBJsonArrayFunction
,MariaDBJsonObjectAggFunction
,MariaDBJsonQueryFunction
,MariaDBJsonValueFunction
,MinMaxCaseEveryAnyEmulation
,ModeStatsModeEmulation
,MultipatternSqmFunctionDescriptor
,MySQLJsonArrayAggFunction
,MySQLJsonArrayFunction
,MySQLJsonExistsFunction
,MySQLJsonObjectAggFunction
,MySQLJsonObjectFunction
,MySQLJsonQueryFunction
,MySQLJsonValueFunction
,NamedSqmFunctionDescriptor
,NvlCoalesceEmulation
,OracleArrayAggEmulation
,OracleArrayConcatElementFunction
,OracleArrayConcatFunction
,OracleArrayConstructorFunction
,OracleArrayContainsFunction
,OracleArrayFillFunction
,OracleArrayGetFunction
,OracleArrayIncludesFunction
,OracleArrayIntersectsFunction
,OracleArrayLengthFunction
,OracleArrayPositionFunction
,OracleArrayPositionsFunction
,OracleArrayRemoveFunction
,OracleArrayRemoveIndexFunction
,OracleArrayReplaceFunction
,OracleArraySetFunction
,OracleArraySliceFunction
,OracleArrayToStringFunction
,OracleArrayTrimFunction
,OracleJsonArrayAggFunction
,OracleJsonArrayAppendFunction
,OracleJsonArrayFunction
,OracleJsonArrayInsertFunction
,OracleJsonInsertFunction
,OracleJsonMergepatchFunction
,OracleJsonObjectAggFunction
,OracleJsonObjectFunction
,OracleJsonRemoveFunction
,OracleJsonReplaceFunction
,OracleJsonSetFunction
,OracleJsonValueFunction
,OracleSpatialFunction
,OracleSpatialSQLMMFunction
,OracleTruncFunction
,OrderByFragmentFunction
,OrdinalFunction
,PatternBasedSqmFunctionDescriptor
,PostgreSQLArrayConcatElementFunction
,PostgreSQLArrayConcatFunction
,PostgreSQLArrayConstructorFunction
,PostgreSQLArrayFillFunction
,PostgreSQLArrayPositionFunction
,PostgreSQLArrayPositionsFunction
,PostgreSQLArrayTrimEmulation
,PostgreSQLJsonArrayAggFunction
,PostgreSQLJsonArrayAppendFunction
,PostgreSQLJsonArrayFunction
,PostgreSQLJsonArrayInsertFunction
,PostgreSQLJsonExistsFunction
,PostgreSQLJsonInsertFunction
,PostgreSQLJsonMergepatchFunction
,PostgreSQLJsonObjectAggFunction
,PostgreSQLJsonObjectFunction
,PostgreSQLJsonQueryFunction
,PostgreSQLJsonRemoveFunction
,PostgreSQLJsonReplaceFunction
,PostgreSQLJsonSetFunction
,PostgreSQLJsonValueFunction
,PostgreSQLMinMaxFunction
,PostgreSQLTruncFunction
,PostgreSQLTruncRoundFunction
,PostgreSQLXmlQueryFunction
,QuantifiedLeastGreatestEmulation
,SDOGetGeometryType
,SDOMethodDescriptor
,SDORelateFunction
,SqlColumn
,SqlFunction
,SqlServerConvertTruncFunction
,SQLServerEveryAnyEmulation
,SQLServerFormatEmulation
,SQLServerJsonArrayAggFunction
,SQLServerJsonArrayAppendFunction
,SQLServerJsonArrayFunction
,SQLServerJsonArrayInsertFunction
,SQLServerJsonExistsFunction
,SQLServerJsonInsertFunction
,SQLServerJsonObjectAggFunction
,SQLServerJsonObjectFunction
,SQLServerJsonQueryFunction
,SQLServerJsonRemoveFunction
,SQLServerJsonReplaceFunction
,SQLServerJsonSetFunction
,SQLServerJsonValueFunction
,SQLServerXmlAggFunction
,SQLServerXmlConcatFunction
,SQLServerXmlElementFunction
,SQLServerXmlExistsFunction
,SQLServerXmlForestFunction
,SQLServerXmlPiFunction
,SQLServerXmlQueryFunction
,StandardSQLFunction
,STRelateFunction
,SybaseTruncFunction
,TimestampaddFunction
,TimestampdiffFunction
,TransactSQLStrFunction
,TrimFunction
,TruncFunction
,XmlAggFunction
,XmlConcatFunction
,XmlElementFunction
,XmlExistsFunction
,XmlForestFunction
,XmlPiFunction
,XmlQueryFunction
When a function call is encountered in the text of an HQL query,
a SqmFunctionDescriptor
for the given name is obtained
from the SqmFunctionRegistry
, and the
generateSqmExpression(java.util.List<? extends org.hibernate.query.sqm.tree.SqmTypedNode<?>>, org.hibernate.query.ReturnableType<T>, org.hibernate.query.spi.QueryEngine)
method is called with SQM nodes
representing the invocation arguments. It is the responsibility
of the SqmFunctionDescriptor
to produce a subtree of SQM
nodes representing the function invocation.
The resulting subtree might be quite complex, since the
SqmFunctionDescriptor
is permitted to perform syntactic
de-sugaring. On the other hand, generateSqmExpression(java.util.List<? extends org.hibernate.query.sqm.tree.SqmTypedNode<?>>, org.hibernate.query.ReturnableType<T>, org.hibernate.query.spi.QueryEngine)
returns SelfRenderingSqmFunction
, which is an object
that is permitted to take over the logic of producing the
SQL AST subtree, so de-sugaring may also be performed there.
User-written function descriptors may be contributed via a
FunctionContributor
or by
calling Configuration.addSqlFunction(java.lang.String, org.hibernate.query.sqm.function.SqmFunctionDescriptor)
.
The SqmFunctionRegistry
exposes methods which simplify
the definition of a function, including
SqmFunctionRegistry.namedDescriptorBuilder(String)
and
SqmFunctionRegistry.patternAggregateDescriptorBuilder(String, String)
.
For example, this code registers a function named prefixes()
:
Configuration config = ... ; config.addSqlFunction("prefixes", new SqmFunctionDescriptor() { @Override public <T> SelfRenderingSqmFunction<T> generateSqmExpression( List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine) { final SqmFunctionRegistry registry = queryEngine.getSqmFunctionRegistry(); final TypeConfiguration types = queryEngine.getTypeConfiguration(); return registry.patternDescriptorBuilder("prefix", "(left(?1, character_length(?2)) = ?2)" ) .setExactArgumentCount(2) .setParameterTypes(FunctionParameterType.STRING, FunctionParameterType.STRING) .setInvariantType(types.standardBasicTypeForJavaType(Boolean.class)) .descriptor() .generateSqmExpression(arguments, impliedResultType, queryEngine); } @Override public ArgumentsValidator getArgumentsValidator() { return new ArgumentTypesValidator( StandardArgumentsValidators.exactly(2), FunctionParameterType.STRING, FunctionParameterType.STRING ); } } );The function may be called like this:
prefixes('Hibernate',book.title)
.-
Method Summary
Modifier and TypeMethodDescriptiondefault boolean
Will a call to the described function always include parentheses?default <T> SelfRenderingSqmFunction<T>
generateAggregateSqmExpression
(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
, but also accepts afilter
predicate.default <T> SelfRenderingSqmFunction<T>
generateOrderedSetAggregateSqmExpression
(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, SqmOrderByClause withinGroupClause, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
, but also accepts afilter
predicate and anorder by
clause.<T> SelfRenderingSqmFunction<T>
generateSqmExpression
(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Instantiate this template with the given arguments and expected return type.default <T> SelfRenderingSqmFunction<T>
generateSqmExpression
(ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for no arguments.default <T> SelfRenderingSqmFunction<T>
generateSqmExpression
(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for a single argument.default <T> SelfRenderingSqmFunction<T>
generateWindowSqmExpression
(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, Boolean respectNulls, Boolean fromFirst, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
but also accepts afilter
predicate.The object responsible for validating arguments of the function.default FunctionKind
What sort of function is this?default String
getSignature
(String name) Used only for pretty-printing the function signature in the log.default boolean
Whether the function renders as a predicate.
-
Method Details
-
generateSqmExpression
<T> SelfRenderingSqmFunction<T> generateSqmExpression(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Instantiate this template with the given arguments and expected return type. This produces a tree of SQM nodes representing a tree of function invocations. This allows a single HQL function to be defined in terms of other predefined (database independent) HQL functions, simplifying the task of writing HQL functions which are portable between databases. -
generateAggregateSqmExpression
default <T> SelfRenderingSqmFunction<T> generateAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
, but also accepts afilter
predicate.This method is intended for aggregate functions.
-
generateOrderedSetAggregateSqmExpression
default <T> SelfRenderingSqmFunction<T> generateOrderedSetAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, SqmOrderByClause withinGroupClause, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
, but also accepts afilter
predicate and anorder by
clause.This method is intended for ordered set aggregate functions.
-
generateWindowSqmExpression
default <T> SelfRenderingSqmFunction<T> generateWindowSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, Boolean respectNulls, Boolean fromFirst, ReturnableType<T> impliedResultType, QueryEngine queryEngine) LikegenerateSqmExpression(List, ReturnableType, QueryEngine)
but also accepts afilter
predicate.This method is intended for window functions.
-
generateSqmExpression
default <T> SelfRenderingSqmFunction<T> generateSqmExpression(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for a single argument. -
generateSqmExpression
default <T> SelfRenderingSqmFunction<T> generateSqmExpression(ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for no arguments. -
alwaysIncludesParentheses
default boolean alwaysIncludesParentheses()Will a call to the described function always include parentheses?Instances of this interface are usually used for rendering of functions. However, there are cases where Hibernate needs to consume a fragment and decide if a token represents a function name. In cases where the token is followed by an opening parenthesis, we can safely assume the token is a function name. Bur if the next token is not an opening parenthesis, the token might still represent a function if the function has a "no paren" form in the case of no arguments.
For example, many databases do not require parentheses for functions like
current_timestamp
and friends. This method helps account for those cases.- Returns:
true
by default- API Note:
- The most common case, by far, is that a function call requires the parentheses. So this method returns true by default.
-
getSignature
Used only for pretty-printing the function signature in the log.- Parameters:
name
- the function name- Returns:
- the signature of the function
-
getFunctionKind
What sort of function is this?- Returns:
FunctionKind.NORMAL
by default
-
getArgumentsValidator
ArgumentsValidator getArgumentsValidator()The object responsible for validating arguments of the function.- Returns:
- an instance of
ArgumentsValidator
-
isPredicate
default boolean isPredicate()Whether the function renders as a predicate.- Since:
- 7.0
-