1#pragma once
2#include <Functions/IFunction.h>
3
4/// This file contains developer interface for functions.
5/// In order to implement a new function you can choose one of two options:
6/// * Implement interface for IFunction (old function interface, which is planned to be removed sometimes)
7/// * Implement three interfaces for IExecutableFunctionImpl, IFunctionBaseImpl and IFunctionOverloadResolverImpl
8/// Generally saying, IFunction represents a union of tree new interfaces. However, it can't be used for all cases.
9/// Examples:
10/// * Function properties may depend on arguments type (e.g. toUInt32(UInt8) is globally monotonic, toUInt32(UInt64) - only on intervals)
11/// * In implementation of lambda functions DataTypeFunction needs an functional object with known arguments and return type
12/// * Function CAST prepares specific implementation based on argument types
13///
14/// Interfaces for IFunction, IExecutableFunctionImpl, IFunctionBaseImpl and IFunctionOverloadResolverImpl are pure.
15/// Default implementations are in adaptors classes (IFunctionAdaptors.h), which are implement user interfaces via developer ones.
16/// Interfaces IExecutableFunctionImpl, IFunctionBaseImpl and IFunctionOverloadResolverImpl are implemented via IFunction
17/// in DefaultExecutable, DefaultFunction and DefaultOverloadResolver classes (IFunctionAdaptors.h).
18
19namespace DB
20{
21
22/// Cache for functions result if it was executed on low cardinality column.
23class ExecutableFunctionLowCardinalityResultCache;
24using ExecutableFunctionLowCardinalityResultCachePtr = std::shared_ptr<ExecutableFunctionLowCardinalityResultCache>;
25
26class IExecutableFunctionImpl
27{
28public:
29 virtual ~IExecutableFunctionImpl() = default;
30
31 virtual String getName() const = 0;
32
33 virtual void execute(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) = 0;
34 virtual void executeDryRun(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count)
35 {
36 execute(block, arguments, result, input_rows_count);
37 }
38
39 /** Default implementation in presence of Nullable arguments or NULL constants as arguments is the following:
40 * if some of arguments are NULL constants then return NULL constant,
41 * if some of arguments are Nullable, then execute function as usual for block,
42 * where Nullable columns are substituted with nested columns (they have arbitrary values in rows corresponding to NULL value)
43 * and wrap result in Nullable column where NULLs are in all rows where any of arguments are NULL.
44 */
45 virtual bool useDefaultImplementationForNulls() const { return true; }
46
47 /** If the function have non-zero number of arguments,
48 * and if all arguments are constant, that we could automatically provide default implementation:
49 * arguments are converted to ordinary columns with single value, then function is executed as usual,
50 * and then the result is converted to constant column.
51 */
52 virtual bool useDefaultImplementationForConstants() const { return false; }
53
54 /** If function arguments has single low cardinality column and all other arguments are constants, call function on nested column.
55 * Otherwise, convert all low cardinality columns to ordinary columns.
56 * Returns ColumnLowCardinality if at least one argument is ColumnLowCardinality.
57 */
58 virtual bool useDefaultImplementationForLowCardinalityColumns() const { return true; }
59
60 /** Some arguments could remain constant during this implementation.
61 */
62 virtual ColumnNumbers getArgumentsThatAreAlwaysConstant() const { return {}; }
63
64 /** True if function can be called on default arguments (include Nullable's) and won't throw.
65 * Counterexample: modulo(0, 0)
66 */
67 virtual bool canBeExecutedOnDefaultArguments() const { return true; }
68};
69
70using ExecutableFunctionImplPtr = std::unique_ptr<IExecutableFunctionImpl>;
71
72
73/// This class generally has the same methods as in IFunctionBase.
74/// See comments for IFunctionBase in IFunction.h
75/// The main purpose is to implement `prepare` which returns IExecutableFunctionImpl, not IExecutableFunction
76/// Inheritance is not used for better readability.
77class IFunctionBaseImpl
78{
79public:
80 virtual ~IFunctionBaseImpl() = default;
81
82 virtual String getName() const = 0;
83
84 virtual const DataTypes & getArgumentTypes() const = 0;
85 virtual const DataTypePtr & getReturnType() const = 0;
86
87 virtual ExecutableFunctionImplPtr prepare(const Block & sample_block, const ColumnNumbers & arguments, size_t result) const = 0;
88
89#if USE_EMBEDDED_COMPILER
90
91 virtual bool isCompilable() const { return false; }
92
93 virtual llvm::Value * compile(llvm::IRBuilderBase & /*builder*/, ValuePlaceholders /*values*/) const
94 {
95 throw Exception(getName() + " is not JIT-compilable", ErrorCodes::NOT_IMPLEMENTED);
96 }
97
98#endif
99
100 virtual bool isStateful() const { return false; }
101
102 virtual bool isSuitableForConstantFolding() const { return true; }
103 virtual ColumnPtr getResultIfAlwaysReturnsConstantAndHasArguments(const Block & /*block*/, const ColumnNumbers & /*arguments*/) const { return nullptr; }
104
105 virtual bool isInjective(const Block & /*sample_block*/) { return false; }
106 virtual bool isDeterministic() const { return true; }
107 virtual bool isDeterministicInScopeOfQuery() const { return true; }
108 virtual bool hasInformationAboutMonotonicity() const { return false; }
109
110 using Monotonicity = IFunctionBase::Monotonicity;
111 virtual Monotonicity getMonotonicityForRange(const IDataType & /*type*/, const Field & /*left*/, const Field & /*right*/) const
112 {
113 throw Exception("Function " + getName() + " has no information about its monotonicity.", ErrorCodes::NOT_IMPLEMENTED);
114 }
115};
116
117using FunctionBaseImplPtr = std::unique_ptr<IFunctionBaseImpl>;
118
119
120class IFunctionOverloadResolverImpl
121{
122public:
123 virtual ~IFunctionOverloadResolverImpl() = default;
124
125 virtual String getName() const = 0;
126
127 virtual FunctionBaseImplPtr build(const ColumnsWithTypeAndName & arguments, const DataTypePtr & return_type) const = 0;
128
129 virtual DataTypePtr getReturnType(const DataTypes & /*arguments*/) const
130 {
131 throw Exception("getReturnType is not implemented for " + getName(), ErrorCodes::NOT_IMPLEMENTED);
132 }
133
134 /// This function will be called in default implementation. You can overload it or the previous one.
135 virtual DataTypePtr getReturnType(const ColumnsWithTypeAndName & arguments) const
136 {
137 DataTypes data_types(arguments.size());
138 for (size_t i = 0; i < arguments.size(); ++i)
139 data_types[i] = arguments[i].type;
140
141 return getReturnType(data_types);
142 }
143
144 /// For non-variadic functions, return number of arguments; otherwise return zero (that should be ignored).
145 virtual size_t getNumberOfArguments() const = 0;
146
147 /// Properties from IFunctionOverloadResolver. See comments in IFunction.h
148 virtual bool isDeterministic() const { return true; }
149 virtual bool isDeterministicInScopeOfQuery() const { return true; }
150 virtual bool isStateful() const { return false; }
151 virtual bool isVariadic() const { return false; }
152
153 /// Will be called if isVariadic returns true. You need to check if function can have specified number of arguments.
154 virtual void checkNumberOfArgumentsIfVariadic(size_t /*number_of_arguments*/) const
155 {
156 throw Exception("checkNumberOfArgumentsIfVariadic is not implemented for " + getName(), ErrorCodes::NOT_IMPLEMENTED);
157 }
158
159 virtual void getLambdaArgumentTypes(DataTypes & /*arguments*/) const
160 {
161 throw Exception("Function " + getName() + " can't have lambda-expressions as arguments", ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
162 }
163
164 virtual ColumnNumbers getArgumentsThatAreAlwaysConstant() const { return {}; }
165 virtual ColumnNumbers getArgumentsThatDontImplyNullableReturnType(size_t /*number_of_arguments*/) const { return {}; }
166
167 /** If useDefaultImplementationForNulls() is true, than change arguments for getReturnType() and build():
168 * if some of arguments are Nullable(Nothing) then don't call getReturnType(), call build() with return_type = Nullable(Nothing),
169 * if some of arguments are Nullable, then:
170 * - Nullable types are substituted with nested types for getReturnType() function
171 * - wrap getReturnType() result in Nullable type and pass to build
172 *
173 * Otherwise build returns build(arguments, getReturnType(arguments));
174 */
175 virtual bool useDefaultImplementationForNulls() const { return true; }
176
177 /** If useDefaultImplementationForNulls() is true, than change arguments for getReturnType() and build().
178 * If function arguments has low cardinality types, convert them to ordinary types.
179 * getReturnType returns ColumnLowCardinality if at least one argument type is ColumnLowCardinality.
180 */
181 virtual bool useDefaultImplementationForLowCardinalityColumns() const { return true; }
182
183 /// If it isn't, will convert all ColumnLowCardinality arguments to full columns.
184 virtual bool canBeExecutedOnLowCardinalityDictionary() const { return true; }
185};
186
187using FunctionOverloadResolverImplPtr = std::unique_ptr<IFunctionOverloadResolverImpl>;
188
189
190/// Previous function interface.
191class IFunction : public std::enable_shared_from_this<IFunction>
192{
193public:
194 virtual ~IFunction() = default;
195
196 virtual String getName() const = 0;
197
198 virtual void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) = 0;
199 virtual void executeImplDryRun(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count)
200 {
201 executeImpl(block, arguments, result, input_rows_count);
202 }
203
204 /** Default implementation in presence of Nullable arguments or NULL constants as arguments is the following:
205 * if some of arguments are NULL constants then return NULL constant,
206 * if some of arguments are Nullable, then execute function as usual for block,
207 * where Nullable columns are substituted with nested columns (they have arbitrary values in rows corresponding to NULL value)
208 * and wrap result in Nullable column where NULLs are in all rows where any of arguments are NULL.
209 */
210 virtual bool useDefaultImplementationForNulls() const { return true; }
211
212 /** If the function have non-zero number of arguments,
213 * and if all arguments are constant, that we could automatically provide default implementation:
214 * arguments are converted to ordinary columns with single value, then function is executed as usual,
215 * and then the result is converted to constant column.
216 */
217 virtual bool useDefaultImplementationForConstants() const { return false; }
218
219 /** If function arguments has single low cardinality column and all other arguments are constants, call function on nested column.
220 * Otherwise, convert all low cardinality columns to ordinary columns.
221 * Returns ColumnLowCardinality if at least one argument is ColumnLowCardinality.
222 */
223 virtual bool useDefaultImplementationForLowCardinalityColumns() const { return true; }
224
225 /// If it isn't, will convert all ColumnLowCardinality arguments to full columns.
226 virtual bool canBeExecutedOnLowCardinalityDictionary() const { return true; }
227
228 /** Some arguments could remain constant during this implementation.
229 */
230 virtual ColumnNumbers getArgumentsThatAreAlwaysConstant() const { return {}; }
231
232 /** True if function can be called on default arguments (include Nullable's) and won't throw.
233 * Counterexample: modulo(0, 0)
234 */
235 virtual bool canBeExecutedOnDefaultArguments() const { return true; }
236
237#if USE_EMBEDDED_COMPILER
238
239 virtual bool isCompilable() const
240 {
241 throw Exception("isCompilable without explicit types is not implemented for IFunction", ErrorCodes::NOT_IMPLEMENTED);
242 }
243
244 virtual llvm::Value * compile(llvm::IRBuilderBase & /*builder*/, ValuePlaceholders /*values*/) const
245 {
246 throw Exception("compile without explicit types is not implemented for IFunction", ErrorCodes::NOT_IMPLEMENTED);
247 }
248
249#endif
250
251 /// Properties from IFunctionBase (see IFunction.h)
252 virtual bool isSuitableForConstantFolding() const { return true; }
253 virtual ColumnPtr getResultIfAlwaysReturnsConstantAndHasArguments(const Block & /*block*/, const ColumnNumbers & /*arguments*/) const { return nullptr; }
254 virtual bool isInjective(const Block & /*sample_block*/) { return false; }
255 virtual bool isDeterministic() const { return true; }
256 virtual bool isDeterministicInScopeOfQuery() const { return true; }
257 virtual bool isStateful() const { return false; }
258 virtual bool hasInformationAboutMonotonicity() const { return false; }
259
260 using Monotonicity = IFunctionBase::Monotonicity;
261 virtual Monotonicity getMonotonicityForRange(const IDataType & /*type*/, const Field & /*left*/, const Field & /*right*/) const
262 {
263 throw Exception("Function " + getName() + " has no information about its monotonicity.", ErrorCodes::NOT_IMPLEMENTED);
264 }
265
266 /// For non-variadic functions, return number of arguments; otherwise return zero (that should be ignored).
267 virtual size_t getNumberOfArguments() const = 0;
268
269 virtual DataTypePtr getReturnTypeImpl(const DataTypes & /*arguments*/) const
270 {
271 throw Exception("getReturnType is not implemented for " + getName(), ErrorCodes::NOT_IMPLEMENTED);
272 }
273
274 /// Get the result type by argument type. If the function does not apply to these arguments, throw an exception.
275 virtual DataTypePtr getReturnTypeImpl(const ColumnsWithTypeAndName & arguments) const
276 {
277 DataTypes data_types(arguments.size());
278 for (size_t i = 0; i < arguments.size(); ++i)
279 data_types[i] = arguments[i].type;
280
281 return getReturnTypeImpl(data_types);
282 }
283
284 virtual bool isVariadic() const { return false; }
285
286 virtual void checkNumberOfArgumentsIfVariadic(size_t /*number_of_arguments*/) const
287 {
288 throw Exception("checkNumberOfArgumentsIfVariadic is not implemented for " + getName(), ErrorCodes::NOT_IMPLEMENTED);
289 }
290
291 virtual void getLambdaArgumentTypes(DataTypes & /*arguments*/) const
292 {
293 throw Exception("Function " + getName() + " can't have lambda-expressions as arguments", ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
294 }
295
296 virtual ColumnNumbers getArgumentsThatDontImplyNullableReturnType(size_t /*number_of_arguments*/) const { return {}; }
297
298
299#if USE_EMBEDDED_COMPILER
300
301 bool isCompilable(const DataTypes & arguments) const;
302
303 llvm::Value * compile(llvm::IRBuilderBase &, const DataTypes & arguments, ValuePlaceholders values) const;
304
305#endif
306
307protected:
308
309#if USE_EMBEDDED_COMPILER
310
311 virtual bool isCompilableImpl(const DataTypes &) const { return false; }
312
313 virtual llvm::Value * compileImpl(llvm::IRBuilderBase &, const DataTypes &, ValuePlaceholders) const
314 {
315 throw Exception(getName() + " is not JIT-compilable", ErrorCodes::NOT_IMPLEMENTED);
316 }
317
318#endif
319};
320
321using FunctionPtr = std::shared_ptr<IFunction>;
322
323}
324