Interface SqmFunctionDescriptor

All Known Implementing Classes:
AbstractArrayContainsFunction, AbstractArrayFillFunction, AbstractArrayIncludesFunction, AbstractArrayIntersectsFunction, AbstractArrayPositionFunction, AbstractArrayPositionsFunction, AbstractArrayRemoveFunction, AbstractArrayTrimFunction, AbstractJsonArrayAppendFunction, AbstractJsonArrayInsertFunction, AbstractJsonInsertFunction, AbstractJsonMergepatchFunction, AbstractJsonRemoveFunction, AbstractJsonReplaceFunction, AbstractJsonSetFunction, AbstractRegexpLikeFunction, 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, HANARegexpLikeFunction, HANASpatialAggregate, HANASpatialFunction, HSQLArrayConstructorFunction, HSQLArrayFillFunction, HSQLArrayPositionFunction, HSQLArrayPositionsFunction, HSQLArrayRemoveFunction, HSQLArraySetFunction, HSQLArrayToStringFunction, HSQLJsonArrayAggFunction, HSQLJsonArrayFunction, HSQLJsonObjectFunction, HSQLRegexpLikeFunction, 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, RegexpLikeOperatorFunction, RegexpLikePredicateFunction, RegexpPredicateFunction, 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, StringFunction, 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(List, ReturnableType, 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(List, ReturnableType, 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(String, 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, @Nullable 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, @Nullable 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, @Nullable 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, @Nullable 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, @Nullable ReturnableType<T> impliedResultType, QueryEngine queryEngine)
      Convenience for a single argument.

    • generateSqmExpression

      default <T> SelfRenderingSqmFunction<T> generateSqmExpression(@Nullable 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