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 | |
19 | namespace DB |
20 | { |
21 | |
22 | /// Cache for functions result if it was executed on low cardinality column. |
23 | class ExecutableFunctionLowCardinalityResultCache; |
24 | using ExecutableFunctionLowCardinalityResultCachePtr = std::shared_ptr<ExecutableFunctionLowCardinalityResultCache>; |
25 | |
26 | class IExecutableFunctionImpl |
27 | { |
28 | public: |
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 | |
70 | using 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. |
77 | class IFunctionBaseImpl |
78 | { |
79 | public: |
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 | |
117 | using FunctionBaseImplPtr = std::unique_ptr<IFunctionBaseImpl>; |
118 | |
119 | |
120 | class IFunctionOverloadResolverImpl |
121 | { |
122 | public: |
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 | |
187 | using FunctionOverloadResolverImplPtr = std::unique_ptr<IFunctionOverloadResolverImpl>; |
188 | |
189 | |
190 | /// Previous function interface. |
191 | class IFunction : public std::enable_shared_from_this<IFunction> |
192 | { |
193 | public: |
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 | |
307 | protected: |
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 | |
321 | using FunctionPtr = std::shared_ptr<IFunction>; |
322 | |
323 | } |
324 | |