Package org.hibernate.query.sqm.function

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, OracleExtractFunction, 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
public interface SqmFunctionDescriptor
A factory for SQM nodes representing invocations of a certain named function.

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.metamodel.model.domain.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.metamodel.model.domain.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).
See Also:

  • 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)
      Like generateSqmExpression(List, ReturnableType, QueryEngine), but also accepts a filter 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)
      Like generateSqmExpression(List, ReturnableType, QueryEngine), but also accepts a filter predicate and an order 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)
      Like generateSqmExpression(List, ReturnableType, QueryEngine) but also accepts a filter 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

      default String getSignature(String name)
      Used only for pretty-printing the function signature in the log.
      Parameters:
      name - the function name
      Returns:
      the signature of the function

    • getFunctionKind

      default FunctionKind 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