2020
2121use arrow:: datatypes:: DataType ;
2222
23+ /// Constant that is used as a placeholder for any valid timezone.
24+ /// This is used where a function can accept a timestamp type with any
25+ /// valid timezone, it exists to avoid the need to enumerate all possible
26+ /// timezones. See [`TypeSignature`] for more details.
27+ ///
28+ /// Type coercion always ensures that functions will be executed using
29+ /// timestamp arrays that have a valid time zone. Functions must never
30+ /// return results with this timezone.
31+ pub const TIMEZONE_WILDCARD : & str = "+TZ" ;
32+
2333///A function's volatility, which defines the functions eligibility for certain optimizations
2434#[ derive( Debug , PartialEq , Eq , PartialOrd , Ord , Clone , Copy , Hash ) ]
2535pub enum Volatility {
26- /// Immutable - An immutable function will always return the same output when given the same
27- /// input. An example of this is [super::BuiltinScalarFunction::Cos].
36+ /// An immutable function will always return the same output when given the same
37+ /// input. An example of this is [super::BuiltinScalarFunction::Cos]. DataFusion
38+ /// will attempt to inline immutable functions during planning.
2839Immutable ,
29- /// Stable - A stable function may return different values given the same input across different
40+ /// A stable function may return different values given the same input across different
3041/// queries but must return the same value for a given input within a query. An example of
31- /// this is [super::BuiltinScalarFunction::Now].
42+ /// this is [super::BuiltinScalarFunction::Now]. DataFusion
43+ /// will attempt to inline `Stable` functions during planning, when possible.
44+ /// For query `select col1, now() from t1`, it might take a while to execute but
45+ /// `now()` column will be the same for each output row, which is evaluated
46+ /// during planning.
3247Stable ,
33- /// Volatile - A volatile function may change the return value from evaluation to evaluation.
48+ /// A volatile function may change the return value from evaluation to evaluation.
3449/// Multiple invocations of a volatile function may return different results when used in the
35- /// same query. An example of this is [super::BuiltinScalarFunction::Random].
50+ /// same query. An example of this is [super::BuiltinScalarFunction::Random]. DataFusion
51+ /// can not evaluate such functions during planning.
52+ /// In the query `select col1, random() from t1`, `random()` function will be evaluated
53+ /// for each output row, resulting in a unique random value for each row.
3654Volatile ,
3755}
3856
39- /// A function's type signature, which defines the function's supported argument types.
57+ /// A function's type signature defines the types of arguments the function supports.
58+ ///
59+ /// Functions typically support only a few different types of arguments compared to the
60+ /// different datatypes in Arrow. To make functions easy to use, when possible DataFusion
61+ /// automatically coerces (add casts to) function arguments so they match the type signature.
62+ ///
63+ /// For example, a function like `cos` may only be implemented for `Float64` arguments. To support a query
64+ /// that calles `cos` with a different argument type, such as `cos(int_column)`, type coercion automatically
65+ /// adds a cast such as `cos(CAST int_column AS DOUBLE)` during planning.
66+ ///
67+ /// # Data Types
68+ /// Types to match are represented using Arrow's [`DataType`]. [`DataType::Timestamp`] has an optional variable
69+ /// timezone specification. To specify a function can handle a timestamp with *ANY* timezone, use
70+ /// the [`TIMEZONE_WILDCARD`]. For example:
71+ ///
72+ /// ```
73+ /// # use arrow::datatypes::{DataType, TimeUnit};
74+ /// # use datafusion_expr::{TIMEZONE_WILDCARD, TypeSignature};
75+ /// let type_signature = TypeSignature::Exact(vec![
76+ /// // A nanosecond precision timestamp with ANY timezone
77+ /// // matches Timestamp(Nanosecond, Some("+0:00"))
78+ /// // matches Timestamp(Nanosecond, Some("+5:00"))
79+ /// // does not match Timestamp(Nanosecond, None)
80+ /// DataType::Timestamp(TimeUnit::Nanosecond, Some(TIMEZONE_WILDCARD.into())),
81+ /// ]);
82+ /// ```
4083#[ derive( Debug , Clone , PartialEq , Eq , Hash ) ]
4184pub enum TypeSignature {
42- /// arbitrary number of arguments of an common type out of a list of valid types
43- // A function such as `concat` is `Variadic(vec![DataType::Utf8, DataType::LargeUtf8])`
85+ /// arbitrary number of arguments of an common type out of a list of valid types.
86+ ///
87+ /// # Examples
88+ /// A function such as `concat` is `Variadic(vec![DataType::Utf8, DataType::LargeUtf8])`
4489Variadic ( Vec < DataType > ) ,
45- /// arbitrary number of arguments of an arbitrary but equal type
46- // A function such as `array` is `VariadicEqual`
47- // The first argument decides the type used for coercion
90+ /// arbitrary number of arguments of an arbitrary but equal type.
91+ /// DataFusion attempts to coerce all argument types to match the first argument's type
92+ ///
93+ /// # Examples
94+ /// A function such as `array` is `VariadicEqual`
4895VariadicEqual ,
4996 /// arbitrary number of arguments with arbitrary types
5097VariadicAny ,
51- /// fixed number of arguments of an arbitrary but equal type out of a list of valid types
98+ /// fixed number of arguments of an arbitrary but equal type out of a list of valid types.
5299///
53100/// # Examples
54101/// 1. A function of one argument of f64 is `Uniform(1, vec![DataType::Float64])`
@@ -58,7 +105,8 @@ pub enum TypeSignature {
58105Exact ( Vec < DataType > ) ,
59106 /// fixed number of arguments of arbitrary types
60107Any ( usize ) ,
61- /// One of a list of signatures
108+ /// Matches exactly one of a list of [`TypeSignature`]s. Coercion is attempted to match
109+ /// the signatures in order, and stops after the first success, if any.
62110OneOf ( Vec < TypeSignature > ) ,
63111}
64112
@@ -104,46 +152,48 @@ impl TypeSignature {
104152 }
105153}
106154
107- /// The signature of a function defines the supported argument types
108- /// and its volatility.
155+ /// Defines the supported argument types ([`TypeSignature`]) and [`Volatility`] for a function.
156+ ///
157+ /// DataFusion will automatically coerce (cast) argument types to one of the supported
158+ /// function signatures, if possible.
109159#[ derive( Debug , Clone , PartialEq , Eq , Hash ) ]
110160pub struct Signature {
111- /// type_signature - The types that the function accepts. See [TypeSignature] for more information.
161+ /// The data types that the function accepts. See [TypeSignature] for more information.
112162pub type_signature : TypeSignature ,
113- /// volatility - The volatility of the function. See [Volatility] for more information.
163+ /// The volatility of the function. See [Volatility] for more information.
114164pub volatility : Volatility ,
115165}
116166
117167impl Signature {
118- /// new - Creates a new Signature from any type signature and the volatility.
168+ /// Creates a new Signature from a given type signature and volatility.
119169pub fn new ( type_signature : TypeSignature , volatility : Volatility ) -> Self {
120170 Signature {
121171 type_signature,
122172 volatility,
123173 }
124174 }
125- /// variadic - Creates a variadic signature that represents an arbitrary number of arguments all from a type in common_types.
175+ /// An arbitrary number of arguments with the same type, from those listed in ` common_types` .
126176pub fn variadic ( common_types : Vec < DataType > , volatility : Volatility ) -> Self {
127177 Self {
128178 type_signature : TypeSignature :: Variadic ( common_types) ,
129179 volatility,
130180 }
131181 }
132- /// variadic_equal - Creates a variadic signature that represents an arbitrary number of arguments of the same type.
182+ /// An arbitrary number of arguments of the same type.
133183pub fn variadic_equal ( volatility : Volatility ) -> Self {
134184 Self {
135185 type_signature : TypeSignature :: VariadicEqual ,
136186 volatility,
137187 }
138188 }
139- /// variadic_any - Creates a variadic signature that represents an arbitrary number of arguments of any type.
189+ /// An arbitrary number of arguments of any type.
140190pub fn variadic_any ( volatility : Volatility ) -> Self {
141191 Self {
142192 type_signature : TypeSignature :: VariadicAny ,
143193 volatility,
144194 }
145195 }
146- /// uniform - Creates a function with a fixed number of arguments of the same type, which must be from valid_types.
196+ /// A fixed number of arguments of the same type, from those listed in ` valid_types` .
147197pub fn uniform (
148198 arg_count : usize ,
149199 valid_types : Vec < DataType > ,
@@ -154,21 +204,21 @@ impl Signature {
154204 volatility,
155205 }
156206 }
157- /// exact - Creates a signature which must match the types in exact_types in order.
207+ /// Exactly matches the types in ` exact_types`, in order.
158208pub fn exact ( exact_types : Vec < DataType > , volatility : Volatility ) -> Self {
159209 Signature {
160210 type_signature : TypeSignature :: Exact ( exact_types) ,
161211 volatility,
162212 }
163213 }
164- /// any - Creates a signature which can a be made of any type but of a specified number
214+ /// A specified number of arguments of any type
165215pub fn any ( arg_count : usize , volatility : Volatility ) -> Self {
166216 Signature {
167217 type_signature : TypeSignature :: Any ( arg_count) ,
168218 volatility,
169219 }
170220 }
171- /// one_of Creates a signature which can match any of the [TypeSignature]s which are passed in .
221+ /// Any one of a list of [TypeSignature]s.
172222pub fn one_of ( type_signatures : Vec < TypeSignature > , volatility : Volatility ) -> Self {
173223 Signature {
174224 type_signature : TypeSignature :: OneOf ( type_signatures) ,
0 commit comments